Skip to main content
LLM ReadyRaw Markdown for AI agents:call-history.mdFull index:llms.txtllms-full.txt

Call History, Recordings & Transcription

Retrieve the history of calls handled by the authenticated agent, play back or download call recordings, and inspect speaker-diarized AI transcriptions, summaries, sentiment, and action items.

Data Scoping

Standard /call-center/call-history endpoints return calls accessible to the authenticated agent (where the agent was a participant). Team leaders and supervisors can also query team-wide call history via /call-center/teams/:team_id/call-history.

Endpoints​

MethodEndpointDescription
GET/call-center/call-historyList calls accessible by the current agent
GET/call-center/call-history/:idGet details of an accessible call
GET/call-center/call-history/:id/recordingsGet all recordings for an accessible call
GET/call-center/call-history/:id/recordings/streamStream primary recording audio (302 redirect or stream metadata JSON)
GET/call-center/call-history/:id/recordings/:index/streamStream a specific recording by index (302 redirect or JSON)
GET/call-center/call-history/:id/recordings/:index/downloadDownload a specific recording by index (302 redirect or JSON)
GET/call-center/call-history/:id/transcriptionGet AI transcription, speaker dialogues, summary & sentiment
GET/call-center/teams/:team_id/call-historyList calls handled by team agents (Team Leader / Supervisor)
GET/call-center/teams/:team_id/call-history/:idGet details of a team call (Team Leader / Supervisor)

Authentication​

All endpoints require a Bearer JWT with the agent-api audience:

Authorization: Bearer YOUR_AGENT_JWT

1. List My Calls​

GET /api/v1/call-center/call-history

Retrieve a paginated list of calls accessible by the authenticated agent, sorted by most recent first.

Query Parameters​

ParameterTypeDefaultDescription
directionstringallFilter by call direction: inbound, outbound, internal, or all
statusstring—Filter by call status: answered, active, completed, failed, busy, no_answer, created, queued
sentimentstringallFilter by AI sentiment analysis: positive, neutral, negative, or all
pagenumber1Page number (minimum: 1)
limitnumber20Items per page (minimum: 1, maximum: 100)
searchstring—Search by phone number or party name (maxLength: 50)
sort_fieldstring—Field to sort by (maxLength: 25, e.g., created_at, start_time, duration)
sort_orderstringdescSort order: asc or desc

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history?page=1&limit=20&direction=inbound&sentiment=positive" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK​

{
"data": [
{
"id": "call_01h900000000000000000001",
"workspace_id": "ws_123456789",
"number": "18005550199",
"client_number": "14155552671",
"from": {
"type": "agent",
"name": "Support Agent 1",
"number": "agent1001",
"avatar": null
},
"to": {
"type": "client",
"name": "14155552671",
"number": "14155552671",
"avatar": null
},
"source": "client-api",
"type": "audio",
"direction": "outbound",
"status": "completed",
"start_time": "2026-08-13T04:32:42.551Z",
"answer_time": "2026-08-13T04:32:46.191Z",
"end_time": "2026-08-13T04:32:48.931Z",
"duration": 6,
"billsec": 2,
"hangup_cause": "NORMAL_CLEARING",
"recording": "ready",
"transcription": "completed",
"sentiment": "positive",
"summary": "Client asked about service pricing and installation options.",
"action_items": [
"Send quote to client email",
"Schedule follow-up call"
],
"created_at": "2026-08-13T04:32:42.600Z",
"updated_at": "2026-08-13T04:32:48.983Z"
}
],
"meta": {
"total": 1,
"page": 1,
"limit": 20,
"total_pages": 1
}
}

Call Object Schema​

FieldTypeDescription
idstringUnique Call ID (e.g., call_01h900000000000000000001)
workspace_idstringWorkspace identifier
numberstringWorkspace phone number (DID) or extension used
client_numberstringExternal party phone number
fromobjectCaller party metadata (type, name, number, avatar)
toobjectCallee party metadata (type, name, number, avatar)
sourcestringCall origin (client-api, agent-api, server-api, call_flow)
typestringMedia type (audio or video)
directionstringCall direction: inbound, outbound, or internal
statusstringCall status (answered, active, completed, failed, busy, no_answer, created, queued)
start_timestringISO 8601 timestamp when call signaling started
answer_timestring|nullISO 8601 timestamp when the call was answered
end_timestring|nullISO 8601 timestamp when the call ended
durationnumberTotal call duration in seconds
billsecnumberBillable talk time in seconds (after answer)
hangup_causestring|nullSIP hangup cause (e.g., NORMAL_CLEARING)
recordingstring|nullRecording state (e.g., ready, processing, none)
transcriptionstring|nullAI transcription state (e.g., completed, processing, none)
sentimentstring|nullAI sentiment classification (positive, neutral, negative)
summarystring|nullAI-generated executive summary of the conversation
action_itemsstring[]|nullExtracted follow-up tasks and action items
created_atstringISO 8601 record creation timestamp
updated_atstringISO 8601 record last-updated timestamp

2. Get Call Details​

GET /api/v1/call-center/call-history/:id

Retrieve full details for a single call accessible by the authenticated agent.

Path Parameters​

ParameterTypeRequiredDescription
idstringYesCall ID (e.g., call_01h900000000000000000001)

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK​

Returns a single Call Object.


3. Get Call Recordings​

GET /api/v1/call-center/call-history/:id/recordings

List all audio recordings associated with an accessible call, including pre-signed stream_url and download_url links.

Path Parameters​

ParameterTypeRequiredDescription
idstringYesCall ID (e.g., call_01h900000000000000000001)

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001/recordings" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK​

{
"call_id": "call_01h900000000000000000001",
"recordings": [
{
"index": 0,
"id": "rec_01h900000000000000000001",
"start_time": "2026-08-17T11:01:11.035Z",
"end_time": "2026-08-17T11:01:27.163Z",
"duration": 16,
"format": "wav",
"size_bytes": 256000,
"file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
"stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?X-Amz-Signature=...",
"download_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment..."
}
]
}

4. Stream Primary Call Recording​

GET /api/v1/call-center/call-history/:id/recordings/stream

Stream the primary recording (index 0) of an accessible call. When redirect=false, returns JSON metadata containing the signed stream_url; otherwise responds with an HTTP 302 redirect directly to the audio stream.

Parameters​

ParameterInTypeRequiredDescription
idpathstringYesCall ID
redirectquerystringYesSet to "false" to receive JSON metadata, or "true" to receive a 302 redirect to the audio

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001/recordings/stream?redirect=false" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK (redirect=false)​

{
"call_id": "call_01h900000000000000000001",
"recording_id": "rec_01h900000000000000000001",
"recording_index": 0,
"file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
"format": "wav",
"stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?X-Amz-Signature=...",
"size_bytes": 256000,
"start_time": "2026-08-17T11:01:11.035Z",
"end_time": "2026-08-17T11:01:27.163Z"
}

5. Stream Call Recording by Index​

GET /api/v1/call-center/call-history/:id/recordings/:index/stream

Stream a specific recording segment by its zero-based index. Supports both 302 redirect and JSON metadata response via the redirect query parameter.

Parameters​

ParameterInTypeRequiredDescription
idpathstringYesCall ID
indexpathstringYesZero-based recording index (e.g., 0)
redirectquerystringYesSet to "false" to receive JSON metadata, or "true" to receive a 302 redirect to the audio

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001/recordings/0/stream?redirect=false" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK (redirect=false)​

{
"call_id": "call_01h900000000000000000001",
"recording_id": "rec_01h900000000000000000001",
"recording_index": 0,
"file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
"format": "wav",
"stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?X-Amz-Signature=...",
"download_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment...",
"size_bytes": 256000,
"start_time": "2026-08-17T11:01:11.035Z",
"end_time": "2026-08-17T11:01:27.163Z"
}

6. Download Call Recording by Index​

GET /api/v1/call-center/call-history/:id/recordings/:index/download

Download a specific recording file with Content-Disposition: attachment. When redirect=false, returns JSON metadata with the pre-signed download_url; otherwise responds with a 302 redirect to start the file download.

Parameters​

ParameterInTypeRequiredDescription
idpathstringYesCall ID
indexpathstringYesZero-based recording index (e.g., 0)
redirectquerystringYesSet to "false" to receive JSON metadata, or "true" to 302 redirect to the attachment download

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001/recordings/0/download?redirect=false" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK (redirect=false)​

{
"call_id": "call_01h900000000000000000001",
"recording_id": "rec_01h900000000000000000001",
"recording_index": 0,
"file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
"format": "wav",
"stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment...",
"download_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment...",
"size_bytes": 256000,
"start_time": "2026-08-17T11:01:11.035Z",
"end_time": "2026-08-17T11:01:27.163Z"
}

7. Get Call Transcription & AI Summary​

GET /api/v1/call-center/call-history/:id/transcription

Retrieve the complete AI transcription for a call, including the speaker-diarized dialogues timeline (client vs. agent channels), full_text, executive summary, sentiment, and action_items.

Path Parameters​

ParameterTypeRequiredDescription
idstringYesCall ID (e.g., call_01h900000000000000000001)

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001/transcription" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK​

{
"id": "trans_01h900000000000000000001",
"call_id": "call_01h900000000000000000001",
"workspace_id": "ws_123456789",
"direction": "inbound",
"language": "en",
"dialogue_count": 2,
"duration_seconds": 18,
"dialogues": [
{
"id": "dlg_01h900000000000000000001_0_1",
"speaker": "client",
"channel_index": 0,
"text": "Hello, I would like to learn more about your cloud call center solutions.",
"confidence": 0.98,
"duration_ms": 3200,
"timestamp": "2026-08-18T07:00:02.100Z"
},
{
"id": "dlg_01h900000000000000000001_1_2",
"speaker": "agent",
"channel_index": 1,
"text": "Hello! I would be delighted to assist you. What features are you most interested in?",
"confidence": 0.99,
"duration_ms": 2800,
"timestamp": "2026-08-18T07:00:06.400Z"
}
],
"full_text": "Client: Hello, I would like to learn more about your cloud call center solutions.\nAgent: Hello! I would be delighted to assist you. What features are you most interested in?",
"summary": "Customer inquired about enterprise cloud contact center solutions and pricing.",
"sentiment": "positive",
"action_items": [
"Send Enterprise pricing sheet to customer",
"Schedule live product demo"
],
"created_at": "2026-08-18T07:00:10.500Z",
"updated_at": "2026-08-18T07:00:10.500Z"
}

Transcription Object Fields​

FieldTypeDescription
idstringTranscription ID
call_idstringAssociated Call ID
workspace_idstringWorkspace ID
directionstringCall direction (inbound, outbound, internal)
languagestringDetected or configured language code (e.g., en, vi)
dialogue_countnumberTotal number of speaker turns in dialogues
duration_secondsnumberTranscribed audio duration in seconds
dialoguesarrayChronological list of utterances (id, speaker, channel_index, text, confidence, duration_ms, timestamp)
full_textstringConcatenated plain-text transcript across all speakers
summarystringAI-generated summary of the call
sentimentstringOverall call sentiment (positive, neutral, negative)
action_itemsstring[]Extracted action items and next steps
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last-updated timestamp

8. List Team Call History (Leader / Supervisor)​

GET /api/v1/call-center/teams/:team_id/call-history

Retrieve a paginated list of calls handled by agents belonging to a specific team. Requires the leader or supervisor role.

Parameters​

ParameterInTypeRequiredDescription
team_idpathstringYesTeam ID
pagequerynumberNoPage number (minimum: 1, default: 1)
limitquerynumberNoItems per page (minimum: 1, maximum: 100, default: 20)
searchquerystringNoSearch by phone number or caller name (maxLength: 50)
sort_fieldquerystringNoField to sort by (maxLength: 25)
sort_orderquerystringNoSort order: asc or desc (default: desc)

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/teams/tm_a1b2c3d4e5f6g7h8i9j0k1/call-history?page=1&limit=20" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK​

{
"data": [
{
"id": "call_650000000000000000000150",
"workspace_id": "my_workspace",
"agent_id": "650000000000000000000001",
"direction": "inbound",
"status": "completed",
"number": "+14155551234",
"from": {
"name": "John Doe",
"number": "+14155551234"
},
"to": {
"name": null,
"number": "agent.01"
},
"duration": 120,
"billsec": 100,
"recording_url": "https://storage.firetell.app/recordings/call_150.wav",
"start_time": "2026-08-04T11:42:27.143Z",
"answer_time": "2026-08-04T11:42:36.123Z",
"end_time": "2026-08-04T11:43:00.843Z",
"created_at": "2026-08-04T11:42:27.000Z"
}
],
"meta": {
"total": 1,
"page": 1,
"limit": 20,
"total_pages": 1
}
}

9. Get Team Call Details (Leader / Supervisor)​

GET /api/v1/call-center/teams/:team_id/call-history/:id

Retrieve detailed information for a specific call handled by an agent in your managed team. Requires the leader or supervisor role.

Path Parameters​

ParameterTypeRequiredDescription
team_idstringYesTeam ID
idstringYesCall ID

Request​

curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/teams/tm_a1b2c3d4e5f6g7h8i9j0k1/call-history/call_650000000000000000000150" \
-H "Authorization: Bearer YOUR_AGENT_JWT"

Response 200 OK​

{
"id": "call_650000000000000000000150",
"workspace_id": "my_workspace",
"agent_id": "650000000000000000000001",
"direction": "inbound",
"status": "completed",
"number": "+14155551234",
"from": {
"name": "John Doe",
"number": "+14155551234"
},
"to": {
"name": null,
"number": "agent.01"
},
"duration": 120,
"billsec": 100,
"recording_url": "https://storage.firetell.app/recordings/call_150.wav",
"start_time": "2026-08-04T11:42:27.143Z",
"answer_time": "2026-08-04T11:42:36.123Z",
"end_time": "2026-08-04T11:43:00.843Z",
"created_at": "2026-08-04T11:42:27.000Z"
}

See the Teams API Reference for full team supervision and management endpoints.


Error Responses​

StatusDescription
401Missing or invalid agent-api Bearer JWT
403Insufficient permissions to access this call or team resource
404Call, recording, or transcription not found