Core Concepts

Calls and Sessions

A call is a single conversation session between a caller and an AI agent. Every call — whether browser-based, inbound from a phone number, or outbound initiated via the API — is tracked as a first-class resource with a unique ID, a full transcript, performance metrics, and post-call analysis results.

Call Types

Type	Description
`webrtc`	Browser-based session initiated via connection token — used for testing agents in Studio or embedding voice in a web app
`inbound`	Caller dials a Neuratel phone number; the number's assigned agent handles the call
`outbound`	Call initiated via the API or a campaign — the agent dials the destination number
`campaign`	Outbound call made as part of a bulk campaign — same mechanics as outbound, with campaign metadata attached

Call Statuses

A call moves through the following statuses during its lifecycle:

Status	Description
`queued`	Call has been scheduled but not yet dialed
`ringing`	Outbound dial is in progress; phone is ringing at the destination
`in-progress`	Call is connected and the conversation is active
`completed`	Call ended normally
`failed`	Call could not be connected due to a technical error
`no-answer`	Destination phone rang but was not answered
`busy`	Destination line was busy
`canceled`	Call was canceled before it connected

Call Record

Each call produces a record containing the full session data:


Code
{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "channel": "phone",
  "direction": "inbound",
  "status": "completed",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "Customer Support",
  "channel": "phone",
  "from_number": "+14155559999",
  "to_number": "+14155550123",
  "caller_id": "+14155559999",
  "started_at": "2025-01-15T14:30:00Z",
  "ended_at": "2025-01-15T14:35:45Z",
  "duration_seconds": 345,
  "end_reason": "completed",
  "conversation_turn_count": 12,
  "analysis_status": "completed",
  "user_sentiment": "Positive",
  "user_sentiment_score": 0.65,
  "call_successful": "success",
  "call_successful_rationale": "Customer's question about the order was resolved.",
  "agent_metrics": {
    "latency_ttft_ms": 120,
    "latency_ttfb_ms": 180,
    "eou_delay_ms": 95,
    "llm_tokens_total": 1250
  }
}

analysis_status is "pending" while async post-call analysis is running, "completed" once it lands, "failed" on a hard error. The four eval fields above (user_sentiment, user_sentiment_score, call_successful, call_successful_rationale) are populated only when analysis_status == "completed". See Post-call analysis for the full field set and access pattern.

End Reasons

The end_reason field records why the call ended:

Reason	Description
`completed`	Normal conversation end
`transferred`	Agent transferred the call to another destination
`timeout`	Silence timeout was exceeded with no response
`duration_limit`	Call hit the configured maximum duration
`error`	Call ended due to a technical error
`hangup`	Call was ended remotely via the hangup API

Transcripts

Every call generates a full turn-by-turn transcript.


Code
{
  "conversation": [
    {
      "speaker": "agent",
      "text": "Thank you for calling Acme Corp. How can I help you today?",
      "timestamp": "2025-01-15T14:30:05Z"
    },
    {
      "speaker": "user",
      "text": "Hi, I have a question about my recent order.",
      "timestamp": "2025-01-15T14:30:12Z"
    },
    {
      "speaker": "agent",
      "text": "Of course. Could you share your order number and I will look that up for you?",
      "timestamp": "2025-01-15T14:30:16Z"
    }
  ]
}

Fetch a call with its transcript:

Code
GET https://api.neuratel.ai/v1/voice-sessions/{call_id}?include=transcript

Use ?include=full to retrieve the transcript plus all post-call analysis results in a single response.

Recordings

Recording is configured at the agent level. When enabled, the call audio is captured and the recording URL ships on the call.summary.ready webhook (and on the recording field of GET /v1/voice-sessions/{id}) once processing is complete. The dedicated recording.ready event is defined but not yet emitted — see Webhook events for status.

Enable recording in the agent's analytics config:


Code
{
  "analytics": {
    "recording_enabled": true
  }
}

Call recording may be subject to consent requirements in your jurisdiction. Ensure you comply with all applicable laws before enabling recording.

Latency Metrics

Each call record includes a breakdown of processing latency:

Metric	Description
`latency_ttft_ms`	Time from end of user speech to agent's first token — measures LLM response start
`latency_ttfb_ms`	Time from end of user speech to first audio byte — measures full pipeline
`stt_turnaround_ms`	Time for speech-to-text transcription to complete

Active Calls

Retrieve all calls currently in progress for your organization:

Code
GET https://api.neuratel.ai/v1/voice-sessions/active


Code
{
  "calls": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "channel": "phone",
      "direction": "inbound",
      "phone_number": "+14155559999",
      "agent_name": "Support Agent",
      "agent_id": "660e8400-e29b-41d4-a716-446655440001",
      "status": "in-progress",
      "started_at": "2025-01-15T14:30:00Z",
      "duration_seconds": 45
    }
  ],
  "total_active": 1
}

Concurrency

Check the current concurrent call count and your organization's limit:

Code
GET https://api.neuratel.ai/v1/voice-sessions/concurrency


Code
{
  "active_calls": 8,
  "concurrency_limit": 20
}

Supervisor Controls

While a call is in progress, authorized team members can join it in three modes without interrupting normal operations.

Listen

Join as a hidden observer. You hear everything — both the caller and the agent — but neither party can hear you or knows you are present.

Code
curl -X POST https://api.neuratel.ai/v1/voice-sessions/{call_id}/listen \
  -H "Authorization: Bearer nk_live_your_api_key"


Code
import os, httpx

response = httpx.post(
    f"https://api.neuratel.ai/v1/voice-sessions/{call_id}/listen",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
)
token = response.json()["token"]


Code
const response = await fetch(`https://api.neuratel.ai/v1/voice-sessions/${callId}/listen`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NEURATEL_API_KEY}` },
});
const { token } = await response.json();

Returns a connection token. Use it to join the session from your browser or supervisor client.

Whisper

Join with the ability to send text messages to the agent in real time. The caller cannot hear you. Use this to coach the agent without the caller knowing — for example, to provide a policy detail or suggest a next step.

Code
curl -X POST https://api.neuratel.ai/v1/voice-sessions/{call_id}/whisper \
  -H "Authorization: Bearer nk_live_your_api_key"


Code
response = httpx.post(
    f"https://api.neuratel.ai/v1/voice-sessions/{call_id}/whisper",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
)


Code
const response = await fetch(`https://api.neuratel.ai/v1/voice-sessions/${callId}/whisper`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NEURATEL_API_KEY}` },
});

Barge

Take over the call as a full participant. The caller can hear you. The agent disconnects immediately. Use this for escalations where a human needs to take direct control.

Code
curl -X POST https://api.neuratel.ai/v1/voice-sessions/{call_id}/barge \
  -H "Authorization: Bearer nk_live_your_api_key"


Code
response = httpx.post(
    f"https://api.neuratel.ai/v1/voice-sessions/{call_id}/barge",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
)


Code
const response = await fetch(`https://api.neuratel.ai/v1/voice-sessions/${callId}/barge`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NEURATEL_API_KEY}` },
});

Hangup

End a call remotely:

Code
curl -X POST https://api.neuratel.ai/v1/voice-sessions/{call_id}/hangup \
  -H "Authorization: Bearer nk_live_your_api_key"

Call History

List Calls

Code
GET https://api.neuratel.ai/v1/voice-sessions?limit=20&skip=0

Filter with query parameters:

Parameter	Description
`channel`	`phone`, `web`, `whatsapp_voice`
`direction`	`inbound`, `outbound` (NULL for `web`)
`campaign_id`	Restrict to a single outbound campaign
`status`	`completed`, `failed`, `in-progress`, etc.
`agent_id_any`	Comma-separated agent IDs
`created_at_gt`	Calls after this datetime (ISO 8601)
`created_at_lt`	Calls before this datetime
`date_preset`	`today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`
`duration_gt`	Calls longer than N seconds
`duration_lt`	Calls shorter than N seconds
`sort_order`	`ASC` or `DESC` (default: `DESC`)
`limit`	Results per page, max 1000
`skip`	Pagination offset

Get a Single Call

Code
GET https://api.neuratel.ai/v1/voice-sessions/{call_id}

Webhook Events

Configure webhooks on the agent to receive real-time call events:

Event	Description
`call.started`	Call began
`call.ended`	Call finished — includes duration, end reason, and metrics
`call.ringing`	Outbound call started ringing
`call.answered`	Call connected
`call.failed`	Call failed to connect
`call.transferred`	Call was transferred to a destination
`transcript.ready`	Full transcript is available
`call.summary.ready`	Post-call summary + analysis is complete. Includes `recording_url` if recording was enabled.
`recording.ready`	Coming soon — defined but not yet emitted; recording URLs ship on `call.summary.ready` for now.

Next Steps

Analytics — Aggregate metrics, post-call analysis, and export
Outbound Campaigns — Bulk automated outbound calling
Monitoring — Real-time event streaming and active call visibility

Last modified on November 7, 2026

Agents Conversations