Calls

Le descrizioni degli endpoint e dei campi restano in inglese, esattamente come le pubblica l'API. È una scelta voluta: qui legge ciò che vedrà anche nelle risposte.

GET /v1/calls#

List calls. Returns call records (CDRs), most recent first, filterable by agent, number, time window, and outcome. A chat session a person took over also carries a takeover block (trigger, requested_at, claimed_by, claimed_at, resolved_at, resolution, human_turns); it is absent on every conversation that never asked for one.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "items": [
    {
      "agent": "front-desk",
      "direction": "inbound",
      "id": "call_…",
      "talk_seconds": 42
    },
    {
      "agent": "front-desk",
      "direction": "inbound",
      "id": "call_…",
      "recording_purged_at": "2026-08-01T03:00:00Z",
      "talk_seconds": 31
    }
  ],
  "timezone": "Europe/Athens"
}

POST /v1/calls/dial#

Place an outbound call. Originates a call from an outbound-enabled agent to an E.164 destination. The caller-ID is the agent's own claimed number. **This call is bounded twice, and the two bounds behave differently.** A per-minute rate stops a runaway loop and clears in seconds (429 dial_rate_limit). A separate allowance for the current UTC day stops a stolen key dialling all day just under that rate (429 dial_daily_cap); waiting a few seconds does not clear it, and the message names the instant it resets. Both allowances come from your plan and ride every successful response, so a campaign can pace itself: x-ratelimit-limit is calls per minute, x-dial-cap-limit and x-dial-cap-remaining are today's total and what is left of it. A call refused by either limit is never placed and never billed.

Corpo della richiesta

application/json Schema: CallsDialRequest

Risposte

Esempio di richiesta

curl -X POST "https://api.voiceland.ai/v1/calls/dial" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": "appointment-reminder",
  "identity": "Maria",
  "to": "+30693XXXXXXX"
}'

Una risposta riuscita restituisce un CallsDialResponse.

Esempio di risposta

{
  "call_id": "call_…",
  "participant_id": "pa_…",
  "room": "room_…"
}

GET /v1/calls/{id}#

Get a call. Full call detail including recording URLs, cost, and quality (MOS). Recordings are kept for the number of days your plan states (recording_retention_days on the package). Once that window has passed the audio is deleted and the call carries recording_purged_at (RFC3339): every recording_url field is then absent for good and the recording stream answers 404 recording_purged. The call record itself, its transcript and its cost lines are not affected. Calls under a legal hold are never purged. When a representative took the conversation over, the takeover block says who and when: trigger is what asked for a person (llm the assistant's own judgement, visitor their button, console an operator), requested_at to claimed_at is how long they waited, claimed_by is the representative, and resolution is how it ended (resumed handed back to the assistant, closed finished by the person, abandoned the session ended first).

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "agent": "front-desk",
  "id": "call_…",
  "recording_url": "https://example.com/call.wav",
  "takeover": {
    "claimed_at": "2026-08-06T09:15:02Z",
    "claimed_by": "maria@acme.example",
    "human_turns": 4,
    "requested_at": "2026-08-06T09:14:31Z",
    "resolution": "resumed",
    "trigger": "visitor"
  }
}

GET /v1/calls/{id}/attestation#

Get a call attestation. A signed chain-of-custody statement for the call (RFC 9943). Requires the chain-of-custody capability; the plan is checked before the lookup, so an unentitled caller cannot learn whether an id exists.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}/attestation" \
  -H "Authorization: Bearer VL_API_KEY"

POST /v1/calls/{id}/cdr-export/retry#

Retry the CDR export. Re-attempts the CDR export delivery for this call. Requires the CDR webhook capability.

Parametri

Risposte

Esempio di richiesta

curl -X POST "https://api.voiceland.ai/v1/calls/{id}/cdr-export/retry" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "status": "delivered"
}

GET /v1/calls/{id}/graded-turns#

List the judge's verdicts for a call. The LLM judge's per-turn verdicts for this call, the rows the hallucination and grounded-answer rates on /me/kpis are folded from, one per judged agent turn. Join them to the transcript by turn_id (t<index>, the same turn identity the feedback surface uses); the answer text is NOT on this response, it is on /calls/{id}/transcript. groundedness is grounded, hallucination, or empty when the judge issued no grounding verdict (the turn cited nothing to check against), those turns are in neither side of the rate. PAGING: an empty next_cursor is the only signal that the listing is finished. This listing filters AFTER it queries, because the call id sits in the middle of the verdict row's sort key, so a page may legitimately return ZERO items with a cursor set, keep following next_cursor until it comes back empty, or you will report an unjudged call that was judged. scanned is how many rows the page crossed. Requires the full KPI dashboard capability, 402 without it.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}/graded-turns" \
  -H "Authorization: Bearer VL_API_KEY"

Una risposta riuscita restituisce un GradedTurnsResponse.

Esempio di risposta

{
  "call_id": "call_…",
  "items": [
    {
      "agent": "front-desk",
      "graded_at": "2026-08-01T10:00:00Z",
      "groundedness": "hallucination",
      "groundedness_score": 0.12,
      "judge_model": "gpt-4o-mini",
      "policy_ok": true,
      "relevance": 0.81,
      "sampled_at": "2026-08-01T10:00:00Z",
      "source_count": 0,
      "turn_id": "t3"
    }
  ],
  "next_cursor": "",
  "scanned": 214
}

GET /v1/calls/{id}/noise_suppression_stats#

Get noise-suppression stats. Per-second input/output levels + a summary for the call's caller-side noise suppression. Enterprise feature, 402 on lower tiers.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}/noise_suppression_stats" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "items": [],
  "summary": {}
}

GET /v1/calls/{id}/path#

Get the call path. The vendor-neutral routing/lifecycle timeline for the call. Enterprise feature, 402 on lower tiers.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}/path" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "items": []
}

GET /v1/calls/{id}/recording.wav#

Stream a call recording. Plays the call's WAV to the authenticated caller, the in-platform playback every plan keeps, with HTTP range support for <audio> scrubbing. This is not a link: it needs your API key and is never cached, so it is served whether or not your plan includes shareable recording links (recording_url on the call is the shareable form and is withheld without that capability). variant selects a mono channel or a transfer leg; the stereo mix is the default. The call must belong to your account.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}/recording.wav" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/calls/{id}/traces#

Get call traces. Per-call broker-level event timeline for debugging. Rows of kind: path (the vendor-neutral call path) are included only when your plan carries per_call_trace_export; the rest of the timeline is always served.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}/traces" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "items": []
}

GET /v1/calls/{id}/transcript#

Get a call transcript. Role-tagged utterances ordered by offset.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}/transcript" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "call_id": "call_…",
  "items": [
    {
      "offset_ms": 1200,
      "role": "caller",
      "text": "Hi"
    }
  ]
}

POST /v1/calls/{id}/webhook/retry#

Retry the call webhook. Re-attempts the post-call webhook delivery for this call.

Parametri

Risposte

Esempio di richiesta

curl -X POST "https://api.voiceland.ai/v1/calls/{id}/webhook/retry" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "attempts": 2,
  "status": "delivered"
}

GET /v1/calls/{id}/webhooks#

List webhook deliveries. The webhook/event delivery attempts recorded for this call, with the bodies as delivered. Recording links inside those bodies (audio_url*) are withheld unless your plan includes shareable recording links, and a delivery whose body is not JSON is omitted in that case rather than searched.

Parametri

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/calls/{id}/webhooks" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "items": []
}

POST /v1/calls/{id}/webhooks/retry#

Retry a delivery. Re-attempts one specific delivery, identified by delivery_id from the deliveries list. A post-call webhook row replays on every plan; a CDR export row needs the CDR webhook capability and an event row needs real-time event webhooks.

Parametri

Risposte

Esempio di richiesta

curl -X POST "https://api.voiceland.ai/v1/calls/{id}/webhooks/retry" \
  -H "Authorization: Bearer VL_API_KEY"

Esempio di risposta

{
  "status": "delivered"
}

GET /v1/me/dial-budget#

How much outbound calling is left today. What remains of your outbound allowance for the current UTC day, **without spending a call to find out**. The two dial bounds already publish themselves on every dial response, which helps a program that is already dialling and nobody else. This is the same numbers, readable at any time: it is strictly read-only, so polling it costs nothing and cannot move the figure it reports. Point a dashboard at it, or check it before starting a campaign. remaining_today is clamped at zero and resets_at is the exact instant it goes back to per_day, always UTC, so "today" does not depend on who is asking. warn_at is the number of dials that raises the approaching-cap alert, published so your own gauge turns amber where the alert actually fires rather than at a threshold you guessed. It reports the allowance, not permission: suspension, an exhausted minutes pool and the per-minute rate all sit beside this cap and none of them are visible here, so a dial can still be refused with budget left.

Risposte

Esempio di richiesta

curl "https://api.voiceland.ai/v1/me/dial-budget" \
  -H "Authorization: Bearer VL_API_KEY"

Una risposta riuscita restituisce un DialBudgetResponse.

Esempio di risposta

{
  "day": "2026-08-08",
  "dials_today": 37,
  "per_day": 200,
  "per_minute": 12,
  "remaining_today": 163,
  "resets_at": "2026-08-09T00:00:00Z",
  "tenant_slug": "acme",
  "warn_at": 160
}

Schemi#

CallsDialRequest#

Originate an outbound call from one of your agents.

CallsDialResponse#

DialBudgetResponse#

Error#

Error envelope returned for non-2xx responses.

GradedTurnItem#

GradedTurnsResponse#