Calls

A call is one phone conversation between one of your agents and one phone number. Jelliu creates a call record for every outbound call it places (from POST /api/calls, a campaign or the MCP server) and for every inbound call that reaches one of your numbers. The record follows the call from the moment it is queued until it ends, and then collects what happened on it: status, outcome, duration, summary, transcript, structured analysis and cost telemetry.

This page covers placing a call, the checks every outbound call must pass, the status lifecycle, outcomes, durations and time limits, recordings, live transfers, hanging up, and how inbound calls are routed.

How it works

Every outbound call, whether you place it directly or a campaign dials it, goes through the same sequence of checks before the phone rings. The first check that fails stops the call and returns an error; no call record is created for checks that run before the record is written.

After the provider accepts the call, the rest of the lifecycle is asynchronous. When the conversation ends, the voice provider reports the transcript and analysis to Jelliu, which closes the record, computes the outcome and sends your webhooks. A background reconciler runs every minute and closes any call whose end was not reported, so a record never stays open forever.

The call object

GET /api/calls and GET /api/calls/{callId} return the same shape. The list omits the heavier fields marked detail only. POST /api/calls returns the raw record right after dialing, without the computed fields analysis, has_recording, agent_name, campaign_name and contact_name.

Internal provider identifiers (the carrier call SID and the voice provider’s conversation id) are never returned.

Identity and routing

Lifecycle

Analysis

Telemetry

All telemetry fields are null when the provider did not report them.

Transfer

Status lifecycle

Terminal statuses never move back to a live status: a late or duplicated event cannot resurrect a closed call. The one upgrade that does happen is to completed: if a call was closed as failed, no-answer, busy or canceled and the provider later delivers a non-empty transcript for it, the status becomes completed because a conversation evidently took place.

Outcomes

outcome says what the call accomplished, independently of how it ended technically. It is null until analysis is available, which can be seconds or minutes after the call ends.

A call counts as successful when its outcome is a success outcome for its category:

Two outcomes are written outside the analysis:

• no_answer when a call ended without a transcript and never connected (status no-answer, busy, canceled or failed, or zero duration). A call that did connect but whose transcript is late keeps outcome: null until the analysis arrives.
• escalated_to_human on an escalation — see below.

Escalation

An escalation is a call handed to a person. Since 2026-09-15 there are two ways it happens, and both record the same outcome and fire the same event:

It never overwrites a more specific verdict. If the analysis already decided sale_closed, issue_resolved, rejected or any other outcome, that value stays: a transfer is the outcome of the AI’s part of the call, not of the call. The escalation is still announced on the call.escalated event either way. Retrying the admin completion is safe for the same reason.

Handing the conversation to another agent of your workspace is deliberately not an escalation: no person picked up, so the outcome is not written and no event fires. Both kinds of hand-off do appear in the agent action ledger, as transfer_to_number and transfer_to_agent.

An internal notification tool (the agent filing a note asking a person to look at something) is also not an escalation: nobody was handed the conversation.

Durations and time limits

• duration_seconds comes from the voice provider when the conversation ends, rounded to whole seconds. If you hang up a call whose carrier leg had already ended, the carrier’s duration is recorded right away; if you hang up a live call, the duration arrives with the post-call report a few seconds later.
• started_at is the conversation start reported by the provider (for inbound calls, the moment the record is created). ended_at is when Jelliu closed the record.

Every voice call has a hard ceiling after which the platform ends it with a short goodbye. The ceiling comes from the agent’s category, and the agent’s own maximum call duration setting (30 to 3600 seconds, see Agents) can only shorten it:

During a free trial, each call is additionally capped at the trial minutes you have left (never less than 60 seconds).

Transcripts

The detail endpoint returns transcript as an array of turns in order:

[
  { "role": "agent", "text": "Hola, ¿hablo con Ana?", "timestamp": "0s", "latency_ms": 820 },
  { "role": "user", "text": "Sí, ella habla.", "timestamp": "3s", "sentiment": 0.1 },
  {
    "role": "agent",
    "text": "Perfecto, le agendo para el jueves a las 10.",
    "timestamp": "41s",
    "tools": [
      { "name": "book_meeting", "type": "webhook", "ok": true, "action_id": "3f7a2c10-8b4e-4d61-9a0c-5e2f1b7d9c44" }
    ]
  }
]

Transcripts and summaries are kept for your plan’s retention window (7 days on Starter, 30 on Growth, 90 on Business, unlimited on Enterprise), or less if you set a shorter window. Messages from other channels live in Conversations.

Common tasks

Place an outbound call

curl -sS -X POST "https://api.jelliu.co/api/calls" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "phoneNumber": "+573001234567"
  }'

{
  "data": {
    "id": "5b0d2f7e-9a41-4c3e-8f0a-2c6d1e7b9a10",
    "tenant_id": "e2a4c6d8-1b3f-4a5c-9e7d-0f2b4d6a8c1e",
    "campaign_id": null,
    "contact_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "agent_id": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "phone_number": "+573001234567",
    "status": "ringing",
    "outcome": null,
    "duration_seconds": null,
    "transcript": null,
    "sentiment_score": null,
    "summary": null,
    "started_at": null,
    "ended_at": null,
    "call_direction": "outbound",
    "prompt_variant_id": null,
    "evaluation_criteria_results": {},
    "data_collection_results": {},
    "created_at": "2026-09-14T15:39:02.118Z",
    "updated_at": "2026-09-14T15:39:03.460Z",
    "deleted_at": null
  }
}

Request body

What Jelliu does with the destination

• Contact filing. The call is always filed under the contact that owns the dialed number. If you omit contactId, Jelliu reuses the oldest existing contact with that number, or creates a contact without a campaign. If you send a contactId whose number differs from phoneNumber, the call is filed under the contact at phoneNumber instead.
• Campaign consistency. With a campaignId and a phoneNumber that differs from the named contact’s, the number must itself be a contact of that campaign; otherwise the call is refused with 400 VALIDATION_FAILED: El número de destino no pertenece a esta campaña. Agrégalo como contacto de la campaña o haz la llamada sin campaña.
• Attempt counting. The contact’s call_attempts increases only after the provider accepts the call, so failures before dialing do not use up compliance attempts.
• Context. The agent receives the contact’s name and what earlier interactions with this person captured, on any channel, so it does not greet a returning customer as a stranger.
• Disclosures. When the destination requires it, a recording notice is added to the agent’s greeting. A greeting that already announces recording is left as it is.
• Caller ID. Calls are placed from your workspace’s own number when one is provisioned. During a trial without one, a shared platform number is used. On an active paid plan with no provisioned number the call fails with PHONE_NUMBER_REQUIRED; see Phone numbers.

Compliance checks

Every outbound call, including campaign calls, is checked against the compliance rules for the destination’s country. The country is read from the number’s prefix (+57 Colombia, +52 Mexico, +55 Brazil, +1 United States, +54 Argentina, +56 Chile, +51 Peru; anything else uses the default profile).

All of them return 403 COMPLIANCE_BLOCKED. You can change the per-country values in Settings → Compliance or through /api/compliance/configs.

Campaign calls. When the campaign dialer is refused, what happens to the contact depends on which rule refused it:

Only an opt-out or a do-not-call refusal marks the contact dnc. A refusal that does not match any of these rules marks it failed, never dnc. A missing opt-in is neither: nobody said no, so it is not dnc, and no call was attempted, so it is not failed — writing a consent record makes the contact dialable again. See Compliance.

Destination countries. Independently of the person being called, the destination itself must be allowed:

• Premium-rate and high-risk ranges (for example +1900, +53, satellite +881 to +883, and many Caribbean +1 area codes) are always refused: Calls to premium-rate or high-risk numbers are blocked (toll fraud protection).
• If you configured allowed calling destinations in Settings → Compliance, only those are reachable.
• Otherwise the allowed set is Colombia, Mexico, Brazil, United States and Canada (+1), Argentina, Chile, Peru and Spain, plus the country you chose at onboarding and the countries of your own voice numbers. Anything else is refused with This destination is outside the countries this workspace calls. Add it to the allowed calling destinations in Settings → Compliance.

Each refusal is written to your audit log with the masked number.

Abuse protection. A workspace can call the same number at most 5 times per hour (429 CALL_SPAM_DETECTED, Phone number called 6 times in the last hour (max 5)), and place at most 500 calls per hour in total. Trial workspaces calling a number already called by other trial workspaces can be refused with 403 TRIAL_ABUSE_DETECTED.

List calls

GET /api/calls uses cursor pagination: pass nextCursor back unchanged as cursor. Filter with agentId and campaignId.

curl -sS "https://api.jelliu.co/api/calls?limit=50&campaignId=0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": {
    "calls": [
      {
        "id": "5b0d2f7e-9a41-4c3e-8f0a-2c6d1e7b9a10",
        "agent_id": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
        "agent_name": "Valentina",
        "campaign_id": "0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90",
        "campaign_name": "Webinar follow-up",
        "contact_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "contact_name": "Ana Gómez",
        "phone_number": "+573001234567",
        "call_direction": "outbound",
        "status": "completed",
        "outcome": "callback_scheduled",
        "duration_seconds": 184,
        "sentiment_score": 0.6,
        "summary": "La clienta pidió que la llamen el jueves en la mañana.",
        "termination_reason": "end_call tool was called.",
        "main_language": "es",
        "cost_usd": "0.3912",
        "has_recording": true,
        "analysis": {
          "summary": "La clienta pidió que la llamen el jueves en la mañana.",
          "outcome": "callback_scheduled",
          "sentiment": "positive",
          "sentiment_score": 0.6,
          "key_topics": [],
          "qualification": {
            "score": 85,
            "interest": "high",
            "answered": true,
            "next_step": "Llamar el jueves a las 10:00",
            "objections": [],
            "reasons": ["Interes high.", "Quedo un siguiente paso concreto: Llamar el jueves a las 10:00."]
          }
        },
        "started_at": "2026-09-14T15:39:05.000Z",
        "ended_at": "2026-09-14T15:42:09.771Z",
        "created_at": "2026-09-14T15:39:02.118Z",
        "updated_at": "2026-09-14T15:42:11.034Z"
      }
    ],
    "total": 1284,
    "limit": 50,
    "offset": 0,
    "nextCursor": "MjAyNi0wOS0xNFQxNTozOTowMi4xMTgwMDBafDViMGQyZjdlLTlhNDEtNGMzZS04ZjBhLTJjNmQxZTdiOWExMA"
  }
}

Get one call

curl -sS "https://api.jelliu.co/api/calls/5b0d2f7e-9a41-4c3e-8f0a-2c6d1e7b9a10" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

The response is { "data": { ... } } with every field in the call object, including transcript.

Download the recording

GET /api/calls/{callId}/audio streams the recording as binary audio (Content-Type from the provider, audio/mpeg by default). Check has_recording first: it is true once the call is over and has audio to play.

curl -sS -f -o call.mp3 \
  "https://api.jelliu.co/api/calls/5b0d2f7e-9a41-4c3e-8f0a-2c6d1e7b9a10/audio" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

A missing recording is always a 404 with code CALL_NOT_FOUND. The X-Recording-Status response header tells the two common cases apart:

Audio is retained by the voice provider for your plan’s window: 7 days on Starter, 30 on Growth, 90 on Business, and until you delete it on Enterprise. Download recordings you need to keep. Responses carry Cache-Control: private, max-age=300.

Hang up a call

POST /api/calls/{callId}/hangup ends a live call. It is idempotent: calling it on a call that has already ended does nothing and still returns 200.

curl -sS -X POST "https://api.jelliu.co/api/calls/5b0d2f7e-9a41-4c3e-8f0a-2c6d1e7b9a10/hangup" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": { "success": true }
}

Jelliu first asks the carrier for the call’s real state, then records the right terminal status:

Read live concurrency

GET /api/calls/concurrency (added 2026-09-15) tells you how many voice calls your workspace has up right now and the ceiling the next call is refused at. Use it before dialing a burst, or to render a capacity indicator.

curl -sS "https://api.jelliu.co/api/calls/concurrency" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": { "active": 2, "max": 5 }
}

• active is the live counter the admission gate itself reads, so this number and the one that decides whether your next POST /api/calls connects can never disagree.
• max is the effective ceiling: the lower of the platform ceiling and your plan’s concurrency limit. That is the value a call is actually refused at with 429 MAX_CONCURRENT_CALLS_REACHED; reporting your plan limit alone would promise capacity the gate does not grant.
• The workspace comes from your credential. There is no tenant parameter, and one workspace cannot read another’s.
• read scope, and available on every plan — it is deliberately not behind the live-monitor feature, because every workspace is entitled to see its own capacity.

Transfer a live call to a person

A warm transfer brings a person into a live call. The caller is moved into a conference, Jelliu dials the person you name from your workspace’s number, and both end up on the line. You then either complete the transfer (the person keeps the call) or cancel it (the person’s leg is hung up and the AI agent picks the conversation back up).

These three endpoints are admin operations and require a key with the full scope.

curl -sS -X POST "https://api.jelliu.co/api/calls/5b0d2f7e-9a41-4c3e-8f0a-2c6d1e7b9a10/transfer" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "transfer_to": "+5716012345" }'

{
  "data": {
    "transferId": "CA8f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c",
    "conferenceId": "CF1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
  }
}

# The person keeps the call
curl -sS -X POST "https://api.jelliu.co/api/calls/5b0d2f7e-9a41-4c3e-8f0a-2c6d1e7b9a10/transfer/complete" \
  -H "Authorization: Bearer $JELLIU_API_KEY"
# Or: hang up the person's leg and give the call back to the agent
curl -sS -X POST "https://api.jelliu.co/api/calls/5b0d2f7e-9a41-4c3e-8f0a-2c6d1e7b9a10/transfer/cancel" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{ "success": true, "message": "Transfer completed — AI agent disconnected" }

{ "success": true, "message": "Transfer canceled — AI agent resumed" }

What each step does to the call:

• Complete does not hang up anyone. It sets outcome to escalated_to_human if the call had no outcome yet, sends a call.escalated event with transferredTo set to the destination and no escalatedBy key, and the record closes normally when the caller hangs up.
• Cancel hangs up the person’s leg, starts a new agent conversation on the caller’s line and clears transferred_to, transferred_at and transfer_call_sid. It fails if the call’s agent is paused or no longer provisioned.

Inbound calls

When someone calls one of your numbers, Jelliu admits the call only if your workspace is not suspended, your plan allows calls and a concurrency slot is free. Then it picks the agent:

1. The agent assigned to the number. If that agent is paused, the call is not passed to another agent: pausing the assigned agent stops that number from answering.
2. Routing among your agents, choosing the least busy provisioned agent that is not paused.
3. Your oldest provisioned, unpaused agent, as a last resort.

Numbers that were removed (soft-deleted) never route calls. An IVR menu, when enabled on the number, is played before routing. Inbound call records are created with call_direction: "inbound", status in-progress and no campaign. Assign agents and configure IVR on the number; see Phone numbers.

Retries

Standalone calls placed with POST /api/calls are never retried. Calls that belong to a campaign and end no-answer, busy, or without connecting are re-dialed according to the campaign’s maxRetryAttempts and retryIntervalMinutes, and each retry passes all the checks on this page again. See Campaigns.

Errors

All errors use the standard error envelope. Codes you can receive from the calls endpoints:

Limits

Webhooks

call.started, call.answered, call.transferred and call.analysis_updated are also available; the catalog describes their fields. The transcript is not included in any event: retrieve it with GET /api/calls/{callId}. See Webhooks for payloads, signatures and retries.

Related