Voice Calls

AI voice bot interactions including IVR and outbound campaigns.

Endpoints

MethodEndpointScopeDescription
GET/api/v1/voice-callsvoice:readList voice calls with filters
GET/api/v1/voice-calls/{id}voice:readGet a voice call with full transcript
GET/api/v1/voice-calls/{id}/recording-urlaudio:downloadGenerate recording SAS URL (15 min expiry)
GET/api/v1/voice-calls/{id}/epa-resultsvoice:readGet post-call survey results
GET/api/v1/voice-calls/{callId}/contextvoice:readGet live call context for an agent handoff (available during the call)

Query Parameters (List Endpoint)

ParameterTypeDescription
campaignIdstringFilter by campaign ID
statestringFilter by call state (e.g., Completed, Busy, NoAnswer)
directionstringFilter by direction (Inbound or Outbound)
dateFromdatetimeStart of date range
dateTodatetimeEnd of date range
pageintPage number for pagination
pageSizeintNumber 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.

FieldTypeDescription
statestringSurvey state (e.g., Completed, Partial, NotStarted)
completionReasonstringWhy the survey ended (e.g., AllAnswered, HangUp, Timeout)
totalQuestionsintTotal number of survey questions
questionsAnsweredintNumber of questions the caller answered
calculatedScorenumberAggregated satisfaction score
responsesarrayIndividual 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.

FieldTypeDescription
callIdstringThe X-Auralytik-Call-Id value this context belongs to
statusstringready when the AI summary is present, partial when it is not
campaignIdstringCampaign the call belongs to
directionstringInbound or Outbound
startedAtdatetimeWhen the call started (UTC)
transferRequestedAtdatetimeWhen the transfer was requested (UTC)
transferDestinationstringThe extension or number dialled for the transfer
transferReasonstringWhy the bot handed the call over
customerobjectid, 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
capturedobjectFlat map of data collected during the call, using the flow's own key names
factsarrayCollected facts with provenance: key, value, provenance, source, recordedAt
actionsarrayBackend actions the bot executed: functionName, success, executedAt
summarystringAI narrative of the call so far. Absent from the body (not null) while still pending
summaryStatusstringready, 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