Conversations | FormantAI

Conversation endpoints expose the result of completed and attempted calls.

List conversations

1 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.

1 {
2   "data": [
3     {
4       "agent_id": 123,
5       "contact_number": "+919876543210",
6       "conversation_id": "e36853de-9cbb-441e-ad75-d3c8ac82abfb_1",
7       "duration_seconds": 142,
8       "end_timestamp": 1773867341766,
9       "start_timestamp": 1773867201766,
10       "status": "completed"
11     }
12   ],
13   "has_more": false,
14   "total": 1
15 }

Get one conversation

1 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.

1 {
2   "data": {
3     "agent_id": 123,
4     "contact_number": "+919876543210",
5     "conversation_id": "e36853de-9cbb-441e-ad75-d3c8ac82abfb_1",
6     "duration_seconds": 142,
7     "failure_reason": null,
8     "results": {
9       "intent": "payment_confirmed",
10       "sentiment": "positive"
11     },
12     "status": "completed",
13     "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
14     "transcript": [
15       { "role": "agent", "message": "Hello Rahul..." },
16       { "role": "human", "message": "Yes, I can talk." }
17     ]
18   }
19 }

Download recording

1 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.