Errors worth branching on

curl -X POST "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155552671",
  "from_phone_number_id": "pn_4711",
  "recording_consent": true,
  "sdp_offer": "v=0\r\no=- 481568 2 IN IP4 127.0.0.1\r\n..."
}'

{
  "data": {
    "ok": true,
    "meta_call_id": "wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg",
    "wa_call_log_id": "waCall_2f6b8d1a4c7e9032",
    "from": "+14155550101",
    "to": "+14155552671",
    "country_code": "US",
    "recording_consent_mode": "explicit",
    "recording_status": "granted",
    "ai_disclosure_preroll_active": false,
    "via_shared_waba": false
  },
  "meta": {
    "request_id": "req_whatsappcalling",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

curl -X POST "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155552671",
  "from_phone_number_id": "pn_4711",
  "recording_consent": true,
  "sdp_offer": "v=0\r\no=- 481568 2 IN IP4 127.0.0.1\r\n..."
}'

{
  "data": {
    "ok": true,
    "meta_call_id": "wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg",
    "wa_call_log_id": "waCall_2f6b8d1a4c7e9032",
    "from": "+14155550101",
    "to": "+14155552671",
    "country_code": "US",
    "recording_consent_mode": "explicit",
    "recording_status": "granted",
    "ai_disclosure_preroll_active": false,
    "via_shared_waba": false
  },
  "meta": {
    "request_id": "req_whatsappcalling",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

These failures cover every phase of the WhatsApp Business Calling lifecycle — the outbound initiate (POST /api/v1/whatsapp/calling/calls), the media update (PATCH /api/v1/whatsapp/calling/calls/:id/session), the hangup (DELETE /api/v1/whatsapp/calling/calls/:id), and the disposition tag (POST /api/v1/whatsapp/calling/calls/:id/disposition). Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_whatsappa1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_whatsappa1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "to", "value": "+1 555 0123", "expected": "an E.164 MSISDN with no spaces" }
    },
    "meta": {
      "request_id": "req_whatsappb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with the MSISDN in E.164 form instead of blind-retrying the same body.

422 — Call permission not granted

  {
    "error": {
      "code": "WHATSAPP_CALLING_NO_PERMISSION",
      "message": "Recipient has not granted WhatsApp call permission. Send a call-permission template first.",
      "status": 422,
      "details": { "waba_id": "waba_0192", "phone_number_id": "pn_4711" }
    },
    "meta": {
      "request_id": "req_whatsappb3",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

The capability gate — fired when the recipient is not a known contact, the permission expired, or the recipient revoked it. A blind retry repeats the same 422; send a call-permission template from the thread first, or surface the dashboard’s grant CTA, then retry only after the recipient grants.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_whatsappc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two. The initiate pre-flight also rejects with WHATSAPP_CALLING_DAILY_CAP_EXCEEDED (429) once the tenant’s daily calling cap is crossed — same branch, different window.

402 — Feature gate

  {
    "error": {
      "code": "WHATSAPP_CALLING_NOT_ENABLED",
      "message": "WhatsApp calling is not enabled on this WABA sender.",
      "status": 402,
      "details": { "waba_id": "waba_0192" }
    },
    "meta": {
      "request_id": "req_whatsappd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Surface the WABA enablement screen; the voice fallback still works for the number. The same 402 envelope carries WHATSAPP_CALLING_INSUFFICIENT_BALANCE when the wallet is below the worst-case per-minute estimate at initiate pre-flight — top up the wallet, then retry.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
422 `WHATSAPP_CALLING_NO_PERMISSION`	recipient has not granted call permission (capability gate)	Fix, then resend intentionally. Send a call-permission template first; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`WHATSAPP_CALLING_NOT_ENABLED` (402 feature gate)	page-specific gating	Branch on `error.code`. Surface the WABA enablement screen; the voice fallback still works for the number.

Worked request and response samples

Copy the request as written, substitute your own ids, and compare the response envelope — a success in the same shape the error sections spell out. The chain below walks one call end to end: initiate → webhook → media update → hang up + disposition → history and cost roll-up.

1. Start a WhatsApp voice call

POST /api/v1/whatsapp/calling/calls

The recipient must already be a contact with an active call-permission grant — the 422 capability gate above is what this route answers with otherwise. Send the recipient as E.164, your WABA sender as from_phone_number_id, and the SDP offer when your media bridge already has one; omit sdp_offer and the callee side exchanges its offer via the accept step instead. The tenant’s own recording-consent and callback-context fields are optional. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155552671",
  "from_phone_number_id": "pn_4711",
  "recording_consent": true,
  "sdp_offer": "v=0\r\no=- 481568 2 IN IP4 127.0.0.1\r\n..."
}'

{
  "data": {
    "ok": true,
    "meta_call_id": "wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg",
    "wa_call_log_id": "waCall_2f6b8d1a4c7e9032",
    "from": "+14155550101",
    "to": "+14155552671",
    "country_code": "US",
    "recording_consent_mode": "explicit",
    "recording_status": "granted",
    "ai_disclosure_preroll_active": false,
    "via_shared_waba": false
  },
  "meta": {
    "request_id": "req_whatsappcalling",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

The returned meta_call_id is the session id — the webhook events, the media update, and the hangup all join on it.

2. Webhook event on ring

Subscribe to whatsapp.call.connected — it fires when the recipient’s client rings, one per call leg, and includes the same meta_call_id so you join it to the initiate response. The sibling lifecycle events whatsapp.call.accepted (media path live) and whatsapp.call.terminated (call ended) carry the same payload shape.

{
  "event": "whatsapp.call.connected",
  "data": {
    "meta_call_id": "wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg",
    "wa_call_log_id": "waCall_2f6b8d1a4c7e9032",
    "direction": "outbound",
    "from": "+14155550101",
    "to": "+14155552671",
    "status": "ringing"
  },
  "meta": {
    "request_id": "req_whatsappcalling_ring",
    "timestamp": "2026-09-08T12:00:30Z"
  }
}

3. Update session media

PATCH /api/v1/whatsapp/calling/calls/:meta_call_id/session

Flip the outbound audio track while the call is in progress — mute an agent microphone, restore it, or gate the track on a recording-consent withdrawal. The route echoes the session back so the dashboard can render the new track state without a re-fetch. Request

curl -X PATCH "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls/wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg/session" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "audio": { "enabled": false } }'

{
  "data": {
    "meta_call_id": "wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg",
    "session": {
      "audio": { "enabled": false }
    }
  },
  "meta": {
    "request_id": "req_whatsappcalling_media",
    "timestamp": "2026-09-08T12:01:40Z"
  }
}

4. Hang up and tag a disposition

Two steps — end the call, then file the tenant-owned outcome code your dialer or QA workflow reports on. Hang up

DELETE /api/v1/whatsapp/calling/calls/:meta_call_id

Request

curl -X DELETE "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls/wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "ok": true,
    "meta_call_id": "wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg",
    "status": "completed",
    "duration_seconds": 187,
    "end_reason": "hangup"
  },
  "meta": {
    "request_id": "req_whatsappcalling_hangup",
    "timestamp": "2026-09-08T12:03:37Z"
  }
}

Apply a disposition code

POST /api/v1/whatsapp/calling/calls/:meta_call_id/disposition

Disposition codes are tenant-owned strings — define them in the dialer’s disposition-code registry and apply them after hangup (or while the call is live) so history queries group on them. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls/wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg/disposition" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "disposition": "resolved_first_contact" }'

{
  "data": {
    "ok": true,
    "meta_call_id": "wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg",
    "disposition": "resolved_first_contact"
  },
  "meta": {
    "request_id": "req_whatsappcalling_dispo",
    "timestamp": "2026-09-08T12:03:39Z"
  }
}

5. Call history and cost roll-up

Per-call cost rides on each history row (cost_amount_cents / cost_currency); the working-day aggregate for a destination or WABA comes from the analytics endpoint. Per-call history

GET /api/v1/whatsapp/calling/calls

Request

curl -X GET "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls?direction=outbound&status=completed&start=2026-09-08T00:00:00Z&end=2026-09-08T23:59:59Z&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "waCall_2f6b8d1a4c7e9032",
      "conversation_id": "conv_9d1e2f3a4b5c6d7e",
      "waba_id": "waba_0192",
      "phone_number_id": "pn_4711",
      "from_number": "+14155550101",
      "to_number": "+14155552671",
      "direction": "outbound",
      "meta_call_id": "wamid.HBgLGUAMT4xsk_CNkTrKjxEohVg",
      "status": "completed",
      "started_at": "2026-09-08T12:00:00Z",
      "answered_at": "2026-09-08T12:00:31Z",
      "ended_at": "2026-09-08T12:03:37Z",
      "duration_seconds": 187,
      "end_reason": "hangup",
      "cost_amount_cents": 9,
      "cost_currency": "USD",
      "recording_url": null,
      "recording_consent_status": "granted",
      "metadata": { "disposition": "resolved_first_contact" },
      "contact": {
        "id": "ct_7a1b2c3d4e5f6g7h",
        "name": "Dana Example",
        "email": null,
        "phone": "+14155552671"
      },
      "created_at": "2026-09-08T12:00:00Z",
      "updated_at": "2026-09-08T12:03:39Z"
    }
  ],
  "meta": {
    "request_id": "req_whatsappcalling_hist",
    "timestamp": "2026-09-08T13:00:00Z",
    "cursor": "2026-09-08T12:00:00.000Z|waCall_2f6b8d1a4c7e9032",
    "has_more": false
  }
}

Window totals

GET /api/v1/whatsapp/calling/analytics

Request

curl -X GET "https://api.orbit.devotel.io/api/v1/whatsapp/calling/analytics?waba_id=waba_0192&days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "window_days": 30,
    "totals": {
      "total_calls": 412,
      "answered_calls": 301,
      "declined_calls": 44,
      "missed_calls": 38,
      "failed_calls": 29,
      "avg_duration_seconds": 142,
      "total_cost_cents": 18461,
      "cost_currency": "USD"
    },
    "trend": [
      { "day": "2026-09-07", "calls": 18, "answered": 13, "declined": 2 },
      { "day": "2026-09-08", "calls": 21, "answered": 15, "declined": 3 }
    ]
  },
  "meta": {
    "request_id": "req_whatsappcalling_agg",
    "timestamp": "2026-09-08T13:00:00Z"
  }
}

Scope either query to a single destination by filtering history on q (free text matches phone columns, contact name, and conversation id); sum cost_amount_cents over the matching rows for a per-destination roll-up, or read totals.total_cost_cents for the WABA-wide 30-day number.

API Reference

All Endpoints

Errors worth branching on