Conversations | FormantAI

Conversation endpoints expose the result of completed and attempted calls.

List conversations

GET /v1/conversations

curl "https://api.voice.formantai.com/v1/conversations?agent_id=123&limit=20&offset=0" \
  -H "Authorization: Bearer $FORMANT_API_KEY"

Query parameter	Type	Description
`agent_id`	integer	Optional filter by agent.
`limit`	integer	Default `20`, maximum `100`.
`offset`	integer	Pagination offset.

{
  "data": [
    {
      "agent_id": 123,
      "contact_number": "+919876543210",
      "conversation_id": "e36853de-9cbb-441e-ad75-d3c8ac82abfb_1",
      "duration_seconds": 142,
      "end_timestamp": 1773867341766,
      "start_timestamp": 1773867201766,
      "status": "completed"
    }
  ],
  "has_more": false,
  "total": 1
}

Get one conversation

GET /v1/conversations/{conversation_id}

curl "https://api.voice.formantai.com/v1/conversations/e36853de-9cbb-441e-ad75-d3c8ac82abfb_1" \
  -H "Authorization: Bearer $FORMANT_API_KEY"

The response includes transcript and results when available.

{
  "data": {
    "agent_id": 123,
    "contact_number": "+919876543210",
    "conversation_id": "e36853de-9cbb-441e-ad75-d3c8ac82abfb_1",
    "duration_seconds": 142,
    "failure_reason": null,
    "results": {
      "intent": "payment_confirmed",
      "sentiment": "positive"
    },
    "status": "completed",
    "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transcript": [
      { "role": "agent", "message": "Hello Rahul..." },
      { "role": "human", "message": "Yes, I can talk." }
    ]
  }
}

Download recording

GET /v1/conversations/{conversation_id}/recording

curl "https://api.voice.formantai.com/v1/conversations/e36853de-9cbb-441e-ad75-d3c8ac82abfb_1/recording" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  --output recording.wav

Recordings may not be available immediately for every call. A missing recording returns a not_found error.

Status values

Common statuses include:

Status	Meaning
`completed`	Call connected and ended normally.
`failed`	Call setup or provider interaction failed.
`busy`	Recipient was busy.
`no_answer`	Recipient did not answer.
`socket_failure`	Call connected but voice streaming failed.
`telephony_failed`	Telephony provider failed after initiation.
`unreachable`	Destination number could not be reached.