Voice Calls
AI voice bot interactions including IVR and outbound campaigns.
Endpoints
| Method | Endpoint | Scope | Description |
|---|---|---|---|
| GET | /api/v1/voice-calls | voice:read | List voice calls with filters |
| GET | /api/v1/voice-calls/{id} | voice:read | Get a voice call with full transcript |
| GET | /api/v1/voice-calls/{id}/recording-url | audio:download | Generate recording SAS URL (15 min expiry) |
| GET | /api/v1/voice-calls/{id}/epa-results | voice:read | Get post-call survey results |
| GET | /api/v1/voice-calls/{callId}/context | voice:read | Get live call context for an agent handoff (available during the call) |
Query Parameters (List Endpoint)
| Parameter | Type | Description |
|---|---|---|
| campaignId | string | Filter by campaign ID |
| state | string | Filter by call state (e.g., Completed, Busy, NoAnswer) |
| direction | string | Filter by direction (Inbound or Outbound) |
| dateFrom | datetime | Start of date range |
| dateTo | datetime | End of date range |
| page | int | Page number for pagination |
| pageSize | int | Number of results per page |
Voice Call Object
{
"id": "vc_abc123",
"campaignId": "camp_456",
"direction": "Outbound",
"state": "Completed",
"startTime": "2024-01-15T10:30:00Z",
"endTime": "2024-01-15T10:35:12Z",
"durationSeconds": 312,
"talkTimeSeconds": 287,
"outcome": "Successful",
"transcript": [
{ "role": "agent", "text": "Hello, this is...", "timestamp": "00:00:01" },
{ "role": "customer", "text": "Hi, yes...", "timestamp": "00:00:04" }
],
"epaResults": {
"state": "Completed",
"completionReason": "AllAnswered",
"totalQuestions": 3,
"questionsAnswered": 3,
"calculatedScore": 85.5,
"responses": [
{ "question": "How satisfied are you?", "answer": "Very satisfied", "score": 5 }
]
},
"createdAt": "2024-01-15T10:30:00Z"
}EPA Results (Post-Call Survey)
EPA (Encuesta Post-Atención) results are available when a post-call survey is configured for the campaign. Use the /epa-results endpoint or access them inline via the voice call object.
| Field | Type | Description |
|---|---|---|
| state | string | Survey state (e.g., Completed, Partial, NotStarted) |
| completionReason | string | Why the survey ended (e.g., AllAnswered, HangUp, Timeout) |
| totalQuestions | int | Total number of survey questions |
| questionsAnswered | int | Number of questions the caller answered |
| calculatedScore | number | Aggregated satisfaction score |
| responses | array | Individual question/answer/score entries |
Recording Download Flow
Audio recordings are accessed via temporary signed URLs. Follow this three-step process:
# 1. Get voice call list
GET /api/v1/voice-calls?state=Completed&direction=Outbound
Authorization: Bearer <token>
# 2. Request a recording SAS URL (valid for 15 minutes)
GET /api/v1/voice-calls/vc_abc123/recording-url
Authorization: Bearer <token>
Response:
{
"recordingUrl": "https://storage.blob.core.windows.net/recordings/vc_abc123.wav?sv=...&se=...",
"expiresAt": "2024-01-15T10:45:00Z"
}
# 3. Download the recording (no auth required, URL is pre-signed)
GET https://storage.blob.core.windows.net/recordings/vc_abc123.wav?sv=...&se=...Live Call Context (Agent Handoff)
When the voice bot hands a call to a human agent, it publishes a context document for that call so the agent sees who is calling and what was already resolved. Look it up with the value of the X-Auralytik-Call-Id SIP header that travels on the transferred leg — that value is the {callId} path segment, not the voice call record ID.
The structured part — customer, captured data and actions — is written before the transfer completes, so it is already there the moment the agent screen opens. The AI narrative is best-effort and can land a few hundred milliseconds later: branch on status and render the structured fields immediately instead of holding the screen for the summary.
| Field | Type | Description |
|---|---|---|
| callId | string | The X-Auralytik-Call-Id value this context belongs to |
| status | string | ready when the AI summary is present, partial when it is not |
| campaignId | string | Campaign the call belongs to |
| direction | string | Inbound or Outbound |
| startedAt | datetime | When the call started (UTC) |
| transferRequestedAt | datetime | When the transfer was requested (UTC) |
| transferDestination | string | The extension or number dialled for the transfer |
| transferReason | string | Why the bot handed the call over |
| customer | object | id, name, phone, authenticated, authMethod, authenticatedAt. phone is E.164 when the number is unambiguously national; extensions and short codes pass through as dialled. Fields with no value are absent, not null |
| captured | object | Flat map of data collected during the call, using the flow's own key names |
| facts | array | Collected facts with provenance: key, value, provenance, source, recordedAt |
| actions | array | Backend actions the bot executed: functionName, success, executedAt |
| summary | string | AI narrative of the call so far. Absent from the body (not null) while still pending |
| summaryStatus | string | ready, pending, failed or disabled |
Every entry in facts carries a provenance: system (set by the platform, such as the campaign or the topic being handled), verified (confirmed by authentication or a backend lookup) or asserted (stated by the caller and not verified). Use it to decide what an agent can act on without asking again.
Add ?wait=1500 to hold the request briefly while the summary finishes. The value is in milliseconds and is clamped to 0–3000; the request returns as soon as the summary is ready, so the wait is an upper bound, not a delay. The context is a screen pop, not an archive: it carries the summary and the structured fields, not the conversation turns. The full transcript is available after the call from /api/v1/voice-calls/{id}, keyed by the same identifier. A call with no published context returns 404 — the same answer for an unknown ID, another tenant's call, or a context that has already expired. Contexts are retained for about one hour.
# The agent screen pops. Look the call up by its X-Auralytik-Call-Id value.
GET /api/v1/voice-calls/8f3c1a20-5d6e-4b71-9c02-7a1e5f8d4b33/context?wait=1500
Authorization: Bearer <token>
Response:
{
"callId": "8f3c1a20-5d6e-4b71-9c02-7a1e5f8d4b33",
"status": "ready",
"campaignId": "camp_456",
"direction": "Inbound",
"startedAt": "2024-01-15T10:30:00Z",
"transferRequestedAt": "2024-01-15T10:33:41Z",
"transferDestination": "9010",
"transferReason": "Customer asked for a human agent",
"customer": {
"name": "Maria Rojas",
"phone": "+56912345678",
"authenticated": true,
"authMethod": "IdentityDocument",
"authenticatedAt": "2024-01-15T10:30:52Z"
},
"captured": {
"CONTACT_TYPE": "account_holder",
"REQUESTED_AMOUNT": "120000"
},
"facts": [
{ "key": "customer_name", "value": "Maria Rojas", "provenance": "verified",
"source": "authentication", "recordedAt": "2024-01-15T10:30:52Z" }
],
"actions": [
{ "functionName": "get_account_balance", "success": true, "executedAt": "2024-01-15T10:31:20Z" }
],
"summary": "Verified account holder. Asked about an outstanding balance and requested a human agent.",
"summaryStatus": "ready"
}Full voice call docs coming soon
Detailed transcript schemas, webhook events for call state changes, and batch export capabilities are being documented.
Request API Access