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 when you complete a warm transfer, unless the call already had an outcome.

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.

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 timestamp-cursor pagination. 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": "2026-09-14T15:39:02.118Z"
  }
}

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:

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, 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.recording_ready and call.transcript_ready are accepted in subscriptions but are not sent yet. See Webhooks for payloads, signatures and retries.

Related