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.
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
| Method | Endpoint | Description |
|---|---|---|
GET | /call-center/call-history | List calls accessible by the current agent |
GET | /call-center/call-history/:id | Get details of an accessible call |
GET | /call-center/call-history/:id/recordings | Get all recordings for an accessible call |
GET | /call-center/call-history/:id/recordings/stream | Stream primary recording audio (302 redirect or stream metadata JSON) |
GET | /call-center/call-history/:id/recordings/:index/stream | Stream a specific recording by index (302 redirect or JSON) |
GET | /call-center/call-history/:id/recordings/:index/download | Download a specific recording by index (302 redirect or JSON) |
GET | /call-center/call-history/:id/transcription | Get AI transcription, speaker dialogues, summary & sentiment |
GET | /call-center/teams/:team_id/call-history | List calls handled by team agents (Team Leader / Supervisor) |
GET | /call-center/teams/:team_id/call-history/:id | Get 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
| Parameter | Type | Default | Description |
|---|---|---|---|
direction | string | all | Filter by call direction: inbound, outbound, internal, or all |
status | string | — | Filter by call status: answered, active, completed, failed, busy, no_answer, created, queued |
sentiment | string | all | Filter by AI sentiment analysis: positive, neutral, negative, or all |
page | number | 1 | Page number (minimum: 1) |
limit | number | 20 | Items per page (minimum: 1, maximum: 100) |
search | string | — | Search by phone number or party name (maxLength: 50) |
sort_field | string | — | Field to sort by (maxLength: 25, e.g., created_at, start_time, duration) |
sort_order | string | desc | Sort 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
| Field | Type | Description |
|---|---|---|
id | string | Unique Call ID (e.g., call_01h900000000000000000001) |
workspace_id | string | Workspace identifier |
number | string | Workspace phone number (DID) or extension used |
client_number | string | External party phone number |
from | object | Caller party metadata (type, name, number, avatar) |
to | object | Callee party metadata (type, name, number, avatar) |
source | string | Call origin (client-api, agent-api, server-api, call_flow) |
type | string | Media type (audio or video) |
direction | string | Call direction: inbound, outbound, or internal |
status | string | Call status (answered, active, completed, failed, busy, no_answer, created, queued) |
start_time | string | ISO 8601 timestamp when call signaling started |
answer_time | string|null | ISO 8601 timestamp when the call was answered |
end_time | string|null | ISO 8601 timestamp when the call ended |
duration | number | Total call duration in seconds |
billsec | number | Billable talk time in seconds (after answer) |
hangup_cause | string|null | SIP hangup cause (e.g., NORMAL_CLEARING) |
recording | string|null | Recording state (e.g., ready, processing, none) |
transcription | string|null | AI transcription state (e.g., completed, processing, none) |
sentiment | string|null | AI sentiment classification (positive, neutral, negative) |
summary | string|null | AI-generated executive summary of the conversation |
action_items | string[]|null | Extracted follow-up tasks and action items |
created_at | string | ISO 8601 record creation timestamp |
updated_at | string | ISO 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Call 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Call 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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Call ID |
redirect | query | string | Yes | Set 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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Call ID |
index | path | string | Yes | Zero-based recording index (e.g., 0) |
redirect | query | string | Yes | Set 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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Call ID |
index | path | string | Yes | Zero-based recording index (e.g., 0) |
redirect | query | string | Yes | Set 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Call 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
| Field | Type | Description |
|---|---|---|
id | string | Transcription ID |
call_id | string | Associated Call ID |
workspace_id | string | Workspace ID |
direction | string | Call direction (inbound, outbound, internal) |
language | string | Detected or configured language code (e.g., en, vi) |
dialogue_count | number | Total number of speaker turns in dialogues |
duration_seconds | number | Transcribed audio duration in seconds |
dialogues | array | Chronological list of utterances (id, speaker, channel_index, text, confidence, duration_ms, timestamp) |
full_text | string | Concatenated plain-text transcript across all speakers |
summary | string | AI-generated summary of the call |
sentiment | string | Overall call sentiment (positive, neutral, negative) |
action_items | string[] | Extracted action items and next steps |
created_at | string | ISO 8601 creation timestamp |
updated_at | string | ISO 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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
team_id | path | string | Yes | Team ID |
page | query | number | No | Page number (minimum: 1, default: 1) |
limit | query | number | No | Items per page (minimum: 1, maximum: 100, default: 20) |
search | query | string | No | Search by phone number or caller name (maxLength: 50) |
sort_field | query | string | No | Field to sort by (maxLength: 25) |
sort_order | query | string | No | Sort 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
| Parameter | Type | Required | Description |
|---|---|---|---|
team_id | string | Yes | Team ID |
id | string | Yes | Call 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
| Status | Description |
|---|---|
401 | Missing or invalid agent-api Bearer JWT |
403 | Insufficient permissions to access this call or team resource |
404 | Call, recording, or transcription not found |