Webhooks - Inkbox

Webhooks let you receive HTTP POST callbacks for phone events. Text events are delivered via the Webhook Subscriptions API — attach a subscription to the phone number with the subset of text.* events you want. The call-lifecycle event (call.ended) is delivered the same way, via a subscription on the agent identity. The incoming-call event stays a per-number control-plane callback, configured on the phone number resource via incoming_call_webhook_url.

Event types

Event	Description
`phone.incoming_call`	An inbound call hit a phone number with `incoming_call_action` set to `"webhook"`
`call.ended`	A call terminated — fired once per call, via an agent-identity subscription. See when it fires
`text.received`	An inbound SMS or MMS arrived on a phone number
`text.sent`	An outbound SMS or MMS was accepted by the carrier
`text.delivered`	The carrier confirmed delivery to the recipient handset
`text.delivery_failed`	The carrier reported a permanent delivery failure
`text.delivery_unconfirmed`	The carrier could not confirm delivery within the carrier’s reporting window

phone.incoming_call is not subscribable. Its handling is synchronous (your response decides whether Inkbox answers the call), so it can’t fan out. Configure it via incoming_call_webhook_url on the phone number resource. call.ended is owned by the agent identity rather than a phone number — a call may ride the identity’s shared iMessage line rather than a number you own, and the identity is the stable owner either way. Subscribe with agent_identity_id. Inbound texts rejected by a contact-rule block or by default-block in whitelist mode are retained for admin review but do not emit text.received webhooks.

Configuring incoming-call webhooks

PATCH /numbers/{phone_number_id}

To enable incoming-call webhooks, set incoming_call_action to "webhook" and provide an incoming_call_webhook_url on the phone number. This per-number callback does not support a delivery auth_token — that option exists only on webhook subscriptions.

Request body

Field	Type	Description
`incoming_call_action`	string	Set to `"webhook"` to enable webhook callbacks for incoming calls
`incoming_call_webhook_url`	string	HTTPS endpoint to receive incoming-call webhook POSTs

Request example

JSON

{
  "incoming_call_action": "webhook",
  "incoming_call_webhook_url": "https://your-agent.example.com/webhooks/inkbox/calls"
}

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/phone/numbers/PHONE_NUMBER_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "incoming_call_action": "webhook",
    "incoming_call_webhook_url": "https://your-agent.example.com/webhooks/inkbox/calls"
  }'

const response = await fetch(
  `https://inkbox.ai/api/v1/phone/numbers/${phoneNumberId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          incoming_call_action: "webhook",
          incoming_call_webhook_url: "https://your-agent.example.com/webhooks/inkbox/calls",
      }),
  }
);
const phoneNumber = await response.json();

import requests

response = requests.patch(
f"https://inkbox.ai/api/v1/phone/numbers/{phone_number_id}",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"incoming_call_action": "webhook",
"incoming_call_webhook_url": "https://your-agent.example.com/webhooks/inkbox/calls",
},
)
phone_number = response.json()

Configuring text webhooks

Text events are delivered via the Webhook Subscriptions API. Two steps:

Have a phone number provisioned (see Phone numbers).
Create a subscription naming that phone number, the HTTPS destination URL, and the subset of text.* event types you want delivered.

You can attach up to 20 active subscriptions per number — split events across URLs, or fan one URL out across many numbers from many subscription rows. Creating a 21st returns 409; delete an existing one first.

Request example

JSON

{
  "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://your-agent.example.com/webhooks/inkbox/texts",
  "event_types": [
    "text.received",
    "text.sent",
    "text.delivered",
    "text.delivery_failed",
    "text.delivery_unconfirmed"
  ]
}

Code examples

curl -X POST "https://inkbox.ai/api/v1/webhooks/subscriptions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://your-agent.example.com/webhooks/inkbox/texts",
    "event_types": [
      "text.received", "text.sent", "text.delivered",
      "text.delivery_failed", "text.delivery_unconfirmed"
    ]
  }'

const response = await fetch(
  "https://inkbox.ai/api/v1/webhooks/subscriptions",
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          phone_number_id: phoneNumberId,
          url: "https://your-agent.example.com/webhooks/inkbox/texts",
          event_types: [
              "text.received",
              "text.sent",
              "text.delivered",
              "text.delivery_failed",
              "text.delivery_unconfirmed",
          ],
      }),
  }
);
const subscription = await response.json();

import requests

response = requests.post(
"https://inkbox.ai/api/v1/webhooks/subscriptions",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"phone_number_id": phone_number_id,
"url": "https://your-agent.example.com/webhooks/inkbox/texts",
"event_types": [
"text.received",
"text.sent",
"text.delivered",
"text.delivery_failed",
"text.delivery_unconfirmed",
],
},
)
subscription = response.json()

See Webhook Subscriptions for the full CRUD surface, validation rules, and per-route error codes.

Configuring call-lifecycle webhooks

call.ended is delivered via the same Webhook Subscriptions API, but the subscription is owned by the agent identity — pass agent_identity_id instead of phone_number_id. A subscription carries one channel, so call.ended cannot share a row with imessage.* events; create a second subscription on the same identity if you want both.

Request example

JSON

{
  "agent_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
  "url": "https://your-agent.example.com/webhooks/inkbox/calls-ended",
  "event_types": ["call.ended"]
}

Delivery is fire-and-forget: the response status is logged but never affects call processing. See the Webhooks guide for SDK examples and typed handlers.

Incoming call webhook

When a phone.incoming_call event fires, Inkbox sends a signed POST request to the configured webhook URL. The payload is flat — there is no {event_type, timestamp, data} envelope, and contacts + agent_identities sit at the top level alongside the call fields. Your endpoint must respond with an action instructing Inkbox how to handle the call.

Payload shape

JSON

{
  "id": "3eafefd0-a22f-4e9b-9eb1-8d59e3d9b85f",
  "origin": "dedicated_number",
  "local_phone_number": "+14155550100",
  "remote_phone_number": "+14155550999",
  "direction": "inbound",
  "status": "initiated",
  "client_websocket_url": null,
  "use_inkbox_tts": null,
  "use_inkbox_stt": null,
  "hangup_reason": null,
  "started_at": null,
  "ended_at": null,
  "created_at": "2026-04-10T18:21:44.018Z",
  "updated_at": "2026-04-10T18:21:44.018Z",
  "rate_limit": {
    "calls_used": 4,
    "calls_remaining": 96,
    "calls_limit": 100,
    "minutes_used": 12.5,
    "minutes_remaining": 287.5,
    "minutes_limit": 300
  },
  "contacts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Doe",
      "memories": ["Prefers concise updates."]
    }
  ],
  "agent_identities": []
}

Payload fields

Field	Type	Description
`id`	UUID	Unique call identifier
`origin`	string	`"dedicated_number"`, `"shared_imessage_number"`, or `"dedicated_imessage_number"`
`local_phone_number`	string \| null	Your number that the call hit (E.164) for dedicated phone and dedicated iMessage calls. `null` for `shared_imessage_number` calls — the shared iMessage line is never surfaced to the webhook.
`remote_phone_number`	string	The caller (E.164)
`direction`	string	Always `"inbound"` for this webhook
`status`	string	Call status at the time the webhook fires (e.g. `"initiated"`, `"ringing"`)
`client_websocket_url`	string \| null	The phone number’s configured fallback WebSocket URL, if any
`use_inkbox_tts`	boolean \| null	Whether the call uses Inkbox-managed TTS
`use_inkbox_stt`	boolean \| null	Whether the call uses Inkbox-managed STT
`hangup_reason`	string \| null	Always `null` for inbound webhooks (call hasn’t ended yet)
`started_at`	string \| null	Always `null` for inbound webhooks
`ended_at`	string \| null	Always `null` for inbound webhooks
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp
`rate_limit`	object \| null	Optional rate-limit snapshot for the organization
`contacts`	array	Address-book matches for `remote_phone_number`, including active memories newest first. Always present, possibly empty. See Peer resolution below.
`agent_identities`	array	Internal-agent matches for `remote_phone_number`. Always present, possibly empty.

When origin is "shared_imessage_number", the inbound call arrived on the identity’s shared iMessage line and local_phone_number is null. A dedicated iMessage line uses "dedicated_imessage_number" and surfaces that line as local_phone_number. contacts and agent_identities are always present on the wire and possibly empty. A peer that’s both a contact and an internal agent appears once in each list. Blocked calls do not dispatch webhooks — receivers only ever see calls that survived the inbound filter.

Response

Your endpoint must respond with an action instructing Inkbox how to handle the call. client_websocket_url is optional — omit it (or send null) to fall back to the phone number’s configured client_websocket_url. Override the fallback by supplying a per-call URL:

JSON

{
  "action": "answer",
  "client_websocket_url": "wss://your-agent.example.com/stream"
}

Use the phone number’s configured fallback by omitting the field:

JSON

{
  "action": "answer"
}

Response fields

Field	Type	Required	Description
`action`	string	Yes	`"answer"` to accept the call, `"reject"` to decline.
`client_websocket_url`	string \| null	No	WebSocket URL (`wss://`) that Inkbox connects to for the call. Can carry text or audio, depending on how the connection is configured. Omit, or send `null`, to fall back to the phone number’s configured `client_websocket_url`. Ignored when `action` is `"reject"`.

Call-ended webhook

call.ended fires once per call, after a connected call terminates. Calls that never connect (unanswered, rejected, or failed before pickup) don’t emit the event — with one exception: Inkbox Voice AI calls report every terminal state, inbound and placed alike, so the event arrives even when the call never connected, with outcome saying what happened. A Voice AI call is never silent. The payload uses the standard {event_type, timestamp, data} envelope, plus a stable top-level id (evt_...) that survives retries and replays — use it as your idempotency key.

Payload shape

JSON

{
  "id": "evt_1c9a7e2f-4b6d-4f8e-91bf-71d2c2e4f0a1",
  "event_type": "call.ended",
  "timestamp": "2026-07-06T18:32:11.402Z",
  "data": {
    "call": {
      "id": "3eafefd0-a22f-4e9b-9eb1-8d59e3d9b85f",
      "origin": "dedicated_number",
      "local_phone_number": "+14155550100",
      "remote_phone_number": "+14155550999",
      "direction": "outbound",
      "status": "completed",
      "mode": "hosted_agent",
      "hosted_agent_authority_mode": "contact_scoped",
      "voicemail_detection": "enabled",
      "reason": "Call the dental office and book a cleaning next week, mornings preferred.",
      "hangup_reason": "remote",
      "started_at": "2026-07-06T18:29:36.104Z",
      "ended_at": "2026-07-06T18:32:10.882Z",
      "created_at": "2026-07-06T18:29:21.330Z",
      "updated_at": "2026-07-06T18:32:10.882Z",
      "duration_seconds": 154,
      "forwardings": []
    },
    "outcome": "completed",
    "post_call_action_items": [
      {
        "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
        "seq": 1,
        "action": "Confirm Tuesday 9:30am cleaning with the dental office",
        "details": "Pencilled in; front desk asked for a confirmation call Monday.",
        "status": "open"
      }
    ],
    "contacts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Jane Doe"
      }
    ],
    "agent_identities": [],
    "transcript": {
      "entries": [
        {"party": "remote", "text": "Good morning, dental office.", "ts_ms": 1230},
        {"party": "local", "text": "Hi, this is Ink calling to book a cleaning for next week — mornings work best.", "ts_ms": 2810},
        {"marker": "abridged", "omitted_turns": 18, "omitted_ms": 95400},
        {"party": "remote", "text": "You're all set for Tuesday at 9:30. See you then!", "ts_ms": 148020}
      ],
      "abridged": true,
      "url": "https://inkbox.ai/api/v1/phone/calls/3eafefd0-a22f-4e9b-9eb1-8d59e3d9b85f/transcripts"
    },
    "transcript_url": "https://inkbox.ai/api/v1/phone/calls/3eafefd0-a22f-4e9b-9eb1-8d59e3d9b85f/transcripts"
  }
}

Envelope fields

Field	Type	Description
`id`	string	Stable event identifier (`evt_...`). Identical across retries and replays — dedupe on it.
`event_type`	string	Always `"call.ended"`
`timestamp`	string	ISO 8601 dispatch timestamp
`data`	object	The event body — see below

`data.call` fields

The webhook wire shape of the call — the call object minus is_blocked (blocked calls never dispatch lifecycle webhooks) and the connection-config fields, plus a derived duration_seconds. Post-call action items don’t ride inside data.call — they arrive at data.post_call_action_items (below).

Field	Type	Description
`id`	UUID	Unique call identifier
`origin`	string	`"dedicated_number"`, `"shared_imessage_number"`, or `"dedicated_imessage_number"`
`local_phone_number`	string \| null	Your number (E.164) for dedicated phone and dedicated iMessage calls. `null` for `shared_imessage_number` calls — the shared line is never surfaced.
`remote_phone_number`	string	The other party’s number (E.164)
`direction`	string	`"inbound"` or `"outbound"`
`status`	string	Terminal status. `"completed"` for every connected call; `"canceled"` or `"failed"` when the call never connected
`mode`	string	Who drove the call: `"client_websocket"` or `"hosted_agent"`. Always present
`hosted_agent_authority_mode`	string	Authority snapshot for the call: `"contact_scoped"` or `"yolo"`. Always present
`voicemail_detection`	string	Whether voicemail detection was `"enabled"` or `"disabled"` for the call. Always present; legacy calls default to `"enabled"`
`reason`	string \| null	The voice agent’s task brief on outbound `hosted_agent` calls; `null` on inbound and `client_websocket` calls
`forwardings`	array	Ordered forwarding history. Always present; empty when the call was not forwarded. See the call object
`hangup_reason`	string \| null	Why the call ended: `"local"`, `"remote"`, `"max_duration"`, `"voicemail"`, `"rejected"`, or `"failed"`
`started_at`	string \| null	When the call was answered (ISO 8601); `null` when the call never connected
`ended_at`	string \| null	When the call ended (ISO 8601)
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last updated timestamp (ISO 8601)
`duration_seconds`	integer \| null	Whole seconds from `started_at` to `ended_at`

`data` fields

Field	Type	Description
`call`	object	The terminated call — see above
`outcome`	string \| null	How an Inkbox Voice AI call turned out: `"completed"`, `"no_answer"`, `"declined"`, or `"failed"`. `null` on `client_websocket` calls — see below
`post_call_action_items`	array	Action items the voice agent recorded during the call, in order. Always present, empty for `client_websocket` calls and Voice AI calls with no items — see below
`contacts`	array	Address-book matches for `remote_phone_number`. Always present, possibly empty. See Peer resolution.
`agent_identities`	array	Internal-agent matches for `remote_phone_number`. Always present, possibly empty.
`transcript`	object \| null	Inline abridged transcript block, present when the call has transcribed turns at dispatch time; `null` otherwise
`transcript_url`	string	Always present. Points at `GET /phone/calls/{call_id}/transcripts` — the authoritative verbatim record (requires an API key).

`outcome` values

outcome describes how an Inkbox Voice AI call turned out; it is null whenever data.call.mode is "client_websocket".

Value	Meaning
`completed`	The call connected and ran to a normal end. A call that reaches voicemail also reports `completed` — the transcript shows what happened
`no_answer`	The call was never answered — an outbound call rang out, or an inbound caller hung up before the agent picked up
`declined`	The call was rejected, or the line was busy
`failed`	The Voice AI session hit an error and the call was torn down, or the call could not be completed at all — e.g. an undeliverable destination or a dial that failed before ringing

`post_call_action_items` items

Ordered by seq, ascending. Items the agent canceled during the call are omitted from the payload. The call.ended event delivers the items atomically with the transcript and outcome — and like every webhook it carries a stable ID and is replayable, so a missed delivery can be re-fetched. The same open items are also readable off the call object (post_call_action_items) at any time.

Field	Type	Description
`id`	UUID	Unique action-item identifier
`seq`	integer	Stable 1-based ordering within the call
`action`	string	Short imperative title of the action item
`details`	string \| null	Free-form context — amounts, dates, verbatim quotes
`status`	string	Always `"open"` in the payload (canceled items are omitted)

`transcript` block

entries is an ordered mix of transcript turns and, when the transcript was cut to fit the size budget, a single middle-cut marker:

Entry	Fields	Description
Turn	`party`, `text`, `ts_ms`	One transcribed turn. `party` is `"local"` (your agent) or `"remote"` (the other party); `ts_ms` is milliseconds from the start of the call.
Marker	`marker`, `omitted_turns`, `omitted_ms`	`marker` is always `"abridged"`; `omitted_turns` / `omitted_ms` count the turns and milliseconds cut from the middle.

Field	Type	Description
`entries`	array	Ordered turns, with at most one `{"marker": "abridged"}` entry where the middle was cut
`abridged`	boolean	`true` when anything was omitted
`url`	string	Same value as `data.transcript_url`

The inline block reads transcripts as of dispatch time and may lag the very last turn — treat transcript_url as the source of truth when you need the complete transcript. mode, hosted_agent_authority_mode, voicemail_detection, reason, outcome, and post_call_action_items are additive — consumers written before they existed keep parsing unchanged.

Text webhooks

All five text.* events share the standard {event_type, timestamp, data} envelope. data.text_message carries the stored text-message record. Two parallel peer-resolution lists ride alongside it: All five events share the standard {event_type, timestamp, data} envelope. data.text_message carries the stored text-message record. For 1:1 traffic, the legacy remote_phone_number field stays populated. For outbound group lifecycle events, remote_phone_number is null; use data.recipient_phone_number for the recipient this event is about and data.text_message.recipients[] for the full per-recipient state. On text.received, a subscription that configures conversation context also receives an additive data.context block; it is absent otherwise.

Inbound — `text.received`

JSON

{
  "event_type": "text.received",
  "timestamp": "2026-04-10T18:24:17.038Z",
  "data": {
    "text_message": {
      "id": "7b3c6e3d-5c20-41ee-8cde-9b1ad1d4e9c0",
      "direction": "inbound",
      "local_phone_number": "+14155550100",
      "remote_phone_number": "+14155550999",
      "text": "Hi, is anyone there?",
      "type": "sms",
      "media": null,
      "is_read": false,
      "delivery_status": null,
      "origin": "user_initiated",
      "error_code": null,
      "error_detail": null,
      "sent_at": null,
      "delivered_at": null,
      "failed_at": null,
      "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
      "sender_phone_number": "+14155550999",
      "recipients": null,
      "created_at": "2026-04-10T18:24:16.912Z",
      "updated_at": "2026-04-10T18:24:16.912Z"
    },
    "contacts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Jane Doe"
      }
    ],
    "agent_identities": [],
    "recipient_phone_number": null
  }
}

On inbound rows, sender_phone_number carries the remote sender (same value as remote_phone_number); recipients is null; data.recipient_phone_number is null. The four outbound events share the same envelope and message shape as text.received. The headline value of these events is the delivery-state block. For 1:1 messages, delivery_status, error_code, error_detail, sent_at, delivered_at, and failed_at are mirrored on text_message; for group messages, delivery_status is a message-level rollup while per-recipient lifecycle details live in text_message.recipients[]. For groups, the top-level text_message.delivery_status is a rollup across recipients[] — the lowest lifecycle rank present, with "delivered" preferred at the terminal tier on mixed-outcome ties. Outbound events fan out one webhook per per-recipient transition, so a text.delivered event for one leg can fire while other legs are still "sent" — the rollup will still read "sent" until every leg reaches a terminal state. Treat recipients[].delivery_status as authoritative per-leg; use the rollup only for at-a-glance UI. The four outbound events share the same envelope and message shape as text.received. The headline value is the delivery-state block — delivery_status, error_code, error_detail, sent_at, delivered_at, failed_at — which lets receivers act on outbound failures without a follow-up API call. On 1:1 outbound rows, those fields are hoisted out of recipients[0] for back-compat. Example: text.delivery_failed on a 1:1 outbound send.

JSON

{
  "event_type": "text.delivery_failed",
  "timestamp": "2026-04-10T18:26:02.501Z",
  "data": {
    "text_message": {
      "id": "7b3c6e3d-5c20-41ee-8cde-9b1ad1d4e9c0",
      "direction": "outbound",
      "local_phone_number": "+14155550100",
      "remote_phone_number": "+14155550999",
      "text": "Thanks for reaching out!",
      "type": "sms",
      "media": null,
      "is_read": false,
      "delivery_status": "delivery_failed",
      "origin": "user_initiated",
      "error_code": "30007",
      "error_detail": "Message filtered by carrier",
      "sent_at": "2026-04-10T18:25:01.118Z",
      "delivered_at": null,
      "failed_at": "2026-04-10T18:26:02.402Z",
      "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
      "sender_phone_number": null,
      "recipients": [
        {
          "recipient_phone_number": "+14155550999",
          "delivery_status": "delivery_failed",
          "carrier": "Example Wireless",
          "line_type": "mobile",
          "error_code": "30007",
          "error_detail": "Message filtered by carrier",
          "sent_at": "2026-04-10T18:25:01.118Z",
          "delivered_at": null,
          "failed_at": "2026-04-10T18:26:02.402Z"
        }
      ],
      "created_at": "2026-04-10T18:25:00.842Z",
      "updated_at": "2026-04-10T18:26:02.402Z"
    },
    "contacts": [],
    "agent_identities": [],
    "recipient_phone_number": null
  }
}

Example: outbound group text.delivered for one recipient.

JSON

{
  "event_type": "text.delivered",
  "timestamp": "2026-04-10T18:26:02.501Z",
  "data": {
    "text_message": {
      "id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
      "direction": "outbound",
      "local_phone_number": "+14155550100",
      "remote_phone_number": null,
      "text": "The appointment moved to 3:30.",
      "type": "mms",
      "media": null,
      "is_read": true,
      "delivery_status": "sent",
      "origin": "user_initiated",
      "error_code": null,
      "error_detail": null,
      "sent_at": null,
      "delivered_at": null,
      "failed_at": null,
      "conversation_id": "e0bc45d2-7478-4b3b-9b7c-cfc73f1ba201",
      "sender_phone_number": null,
      "recipients": [
        {
          "recipient_phone_number": "+15551234567",
          "delivery_status": "delivered",
          "carrier": "Example Wireless",
          "line_type": "mobile",
          "error_code": null,
          "error_detail": null,
          "sent_at": "2026-04-10T18:25:01.118Z",
          "delivered_at": "2026-04-10T18:26:02.402Z",
          "failed_at": null
        },
        {
          "recipient_phone_number": "+12125550199",
          "delivery_status": "sent",
          "carrier": "Example Mobile",
          "line_type": "mobile",
          "error_code": null,
          "error_detail": null,
          "sent_at": "2026-04-10T18:25:01.118Z",
          "delivered_at": null,
          "failed_at": null
        }
      ],
      "created_at": "2026-04-10T18:25:00.842Z",
      "updated_at": "2026-04-10T18:26:02.402Z"
    },
    "contacts": [
      {
        "id": "f0a13e5f-13ee-4d3a-a2b6-8a512f8d0ed5",
        "name": "Jordan Lee"
      }
    ],
    "agent_identities": [],
    "recipient_phone_number": "+15551234567"
  }
}

The three other outbound events have the same shape with different terminal fields:

text.sent — carrier accepted the message. delivery_status is "sent", sent_at is populated, delivered_at and failed_at are null.
text.delivered — carrier confirmed handset delivery. delivery_status is "delivered", both sent_at and delivered_at are populated.
text.delivery_unconfirmed — carrier could not confirm delivery within its reporting window. delivery_status is "delivery_unconfirmed", sent_at and failed_at are populated, delivered_at is null.

Outbound group lifecycle (group MMS)

When you send a group MMS (2+ recipients), each lifecycle event fires once per recipient, with data.recipient_phone_number identifying which leg the event is about. The text_message row carries remote_phone_number: null (no single remote party) and a top-level delivery_status rollup; legacy top-level timestamp/error fields stay null, and per-leg state lives in recipients[]. Example: text.delivered for one leg of a 3-recipient group send.

JSON

{
  "event_type": "text.delivered",
  "timestamp": "2026-04-10T18:30:11.220Z",
  "data": {
    "text_message": {
      "id": "9d4c2e0b-4a18-49a3-bd61-ea6e9d7c8910",
      "direction": "outbound",
      "local_phone_number": "+14155550100",
      "remote_phone_number": null,
      "text": "Heads up — meeting moved to 3pm",
      "type": "mms",
      "media": null,
      "is_read": true,
      "delivery_status": "sent",
      "origin": "user_initiated",
      "error_code": null,
      "error_detail": null,
      "sent_at": null,
      "delivered_at": null,
      "failed_at": null,
      "conversation_id": "8b1d2f3c-9012-4abc-9c1f-3211ee44aabb",
      "sender_phone_number": null,
      "recipients": [
        {
          "recipient_phone_number": "+14155550999",
          "delivery_status": "delivered",
          "carrier": "ExampleMobile",
          "line_type": "mobile",
          "error_code": null,
          "error_detail": null,
          "sent_at": "2026-04-10T18:29:55.001Z",
          "delivered_at": "2026-04-10T18:30:11.150Z",
          "failed_at": null
        },
        {
          "recipient_phone_number": "+14155550211",
          "delivery_status": "sent",
          "carrier": "ExampleMobile",
          "line_type": "mobile",
          "error_code": null,
          "error_detail": null,
          "sent_at": "2026-04-10T18:29:55.077Z",
          "delivered_at": null,
          "failed_at": null
        },
        {
          "recipient_phone_number": "+14155550342",
          "delivery_status": "sent",
          "carrier": "ExampleMobile",
          "line_type": "mobile",
          "error_code": null,
          "error_detail": null,
          "sent_at": "2026-04-10T18:29:55.115Z",
          "delivered_at": null,
          "failed_at": null
        }
      ],
      "created_at": "2026-04-10T18:29:54.512Z",
      "updated_at": "2026-04-10T18:30:11.150Z"
    },
    "contacts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Jane Doe"
      }
    ],
    "agent_identities": [],
    "recipient_phone_number": "+14155550999"
  }
}

Receivers should detect group outbound by text_message.direction === "outbound" && text_message.remote_phone_number === null, then read data.recipient_phone_number to identify the leg and find the matching entry in text_message.recipients[] for that leg’s delivery state.

Per-recipient × per-subscription fan-out

A 3-recipient group send with 2 active text subscriptions produces 6 POSTs per lifecycle stage — one per recipient leg, per subscription. Each POST carries the full group state in text_message.recipients[] plus the leg-identifying data.recipient_phone_number. Per-URL POSTs are independent: a slow receiver doesn’t block delivery to the others. See Phone texts for the API surface around sending into a conversation_id or addressing a group send.

`text_message` field reference

Field	Type	Description
`id`	UUID	Unique text-message identifier
`direction`	string	`"inbound"` or `"outbound"`
`local_phone_number`	string	Your phone number (E.164)
`remote_phone_number`	string \| null	The other party (E.164). Populated on inbound and 1:1 outbound; `null` on group outbound (no single remote party).
`text`	string \| null	Message body. May be `null` for media-only MMS.
`type`	string	`"sms"` or `"mms"`
`media`	array \| null	Attached media items on MMS
`delivery_status`	string \| null	Latest lifecycle status (`"queued"`, `"sent"`, `"delivered"`, `"delivery_failed"`, `"delivery_unconfirmed"`). `null` on inbound. On group outbound this is a rollup across `recipients[]`; treat `recipients[].delivery_status` as authoritative per leg.
`error_code` / `error_detail`	string \| null	Carrier error details when delivery failed (1:1 only)
`sent_at` / `delivered_at` / `failed_at`	string \| null	Lifecycle timestamps (1:1 only)
`conversation_id`	UUID \| null	Parent conversation thread
`sender_phone_number`	string \| null	The sender (inbound only; outbound rows have no sender — implicit from `local_phone_number`)
`recipients`	array \| null	Per-recipient delivery rows. `null` on inbound; one entry on outbound 1:1 (with per-leg fields hoisted to the top-level lifecycle fields for back-compat); ≥2 entries on group outbound.

`recipients[i]` shape

Field	Type	Description
`recipient_phone_number`	string	The recipient (E.164)
`delivery_status`	string \| null	Lifecycle status for this leg
`carrier`	string \| null	Carrier reported by the upstream MNO lookup
`line_type`	string \| null	E.g. `"mobile"`, `"landline"`
`error_code` / `error_detail`	string \| null	Per-leg carrier error details
`sent_at` / `delivered_at` / `failed_at`	string \| null	Per-leg lifecycle timestamps

Conversation context

When a subscription sets context_config, text.received payloads gain an additive data.context object keyed by the configured classes (email, texts, calls). The texts class is conversation-scoped (the triggering conversation, with SMS and iMessage merged); email and calls resolve contact-scoped history through the matched contact. Delivery-status events never carry context. The block shape — per-class fields, item shapes, transcript abridgment, skip reasons, and the 256 KB cap — is documented on the Mail webhooks page, and the configuration shape on the Webhook Subscriptions page.

Peer resolution

Inbound-call payloads carry top-level contacts and agent_identities. Text and call-ended payloads carry data.contacts and data.agent_identities. Both are lists — always present and possibly empty — never null.

Field shapes: contacts are { "id": "<uuid>", "name": "<preferred name> | null", "memories": ["<active memory>"] }; agent identities are { "id": "<uuid>", "agent_handle": "<handle>", "display_name": "<name or null>" }. Contact memories are newest first and may be absent on older replayed payloads. name is null when the contact has no name on file — a contact created automatically from an inbound call or text has an id and memories before anyone gives it a name. It never falls back to the phone number, so check it before addressing someone by name.
Scope: contact matches follow the receiving identity’s permissions. Profile controls whether a match is included; Memories can further hide memory text. Ordinary webhook enrichment stays scoped even when a hosted call uses YOLO. Agent-identity matches include active identities in the same organization.
Inbound calls: match key is top-level remote_phone_number.
Call-ended events: match key is data.call.remote_phone_number.
Inbound texts: match key is data.text_message.remote_phone_number, also available as data.text_message.sender_phone_number.
Outbound 1:1 text lifecycle events: match key is data.text_message.remote_phone_number; data.recipient_phone_number is null.
Outbound group text lifecycle events: match key is data.recipient_phone_number, the recipient this lifecycle event is about. Use data.text_message.recipients[] to inspect every recipient in the conversation send.
Tiebreak (contacts): if multiple contacts share the same phone, the oldest by created_at wins. Receivers needing disambiguation can call GET /contacts/lookup.
Hydration: feed contacts[i].id into GET /api/v1/contacts/{contact_id}. Agent-scoped credentials can discover peer identities through GET /api/v1/identities/a2a/directory; GET /api/v1/identities/{agent_handle} resolves only the caller’s own identity for those credentials.

Both lists are always present on the wire. Treat empty lists as “no matches,” never as errors.

Verifying webhook signatures

Inkbox signs every webhook payload with the agent identity’s signing key — specifically, the key for the identity that owns the phone number the subscription (or incoming-call callback) is on, or, for call-lifecycle subscriptions, the identity that owns the subscription itself. Create or rotate that key via the Signing Keys guide. Three signature headers are included with each request:

Header	Description
`X-Inkbox-Request-ID`	Unique request identifier
`X-Inkbox-Timestamp`	Unix timestamp (seconds)
`X-Inkbox-Signature`	`sha256=<hex_digest>` HMAC-SHA256 signature

When a subscription sets an auth_token, its deliveries additionally carry Authorization: Bearer <token> — the bearer token authenticates Inkbox to your endpoint, while the signature headers prove the payload. The per-number phone.incoming_call callback does not support auth_token. See Authenticating to your endpoint. The signature input is: {request_id}.{timestamp}.{raw_body} To verify a webhook:

Check the timestamp is within 300 seconds of the current time
Reconstruct the signed message: {X-Inkbox-Request-ID}.{X-Inkbox-Timestamp}.{raw_body}
Compute the HMAC-SHA256 using the agent identity’s signing key
Compare the hex digest with the sha256=... value from the header

Python verification example

Python

import hashlib
import hmac
import time

def verify_webhook(
    request_id: str,
    timestamp: str,
    raw_body: bytes,
    signature_header: str,
    signing_key: str,
) -> bool:
    # Reject stale requests (older than 5 minutes)
    if abs(time.time() - int(timestamp)) > 300:
        return False

    # Reconstruct the signed message
    message = f"{request_id}.{timestamp}.{raw_body.decode()}"

    # Compute the expected signature
    expected = hmac.new(
        signing_key.encode(),
        message.encode(),
        hashlib.sha256,
    ).hexdigest()

    # Compare with the provided signature
    provided = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, provided)

Disabling webhooks

To stop receiving text or call-lifecycle webhooks at a URL, delete the subscription that owns it. Delivery stops immediately. To stop receiving incoming-call webhooks, update the phone number to clear the URL and switch the action:

JSON

{
  "incoming_call_action": "auto_reject",
  "incoming_call_webhook_url": null
}

curl -X PATCH "https://inkbox.ai/api/v1/phone/numbers/PHONE_NUMBER_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "incoming_call_action": "auto_reject",
    "incoming_call_webhook_url": null
  }'

await fetch(
  `https://inkbox.ai/api/v1/phone/numbers/${phoneNumberId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          incoming_call_action: "auto_reject",
          incoming_call_webhook_url: null,
      }),
  }
);

import requests

requests.patch(
f"https://inkbox.ai/api/v1/phone/numbers/{phone_number_id}",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"incoming_call_action": "auto_reject",
"incoming_call_webhook_url": None,
},
)

​Event types

​Configuring incoming-call webhooks

​Request body

​Request example

​Code examples

​Configuring text webhooks

​Request example

​Code examples

​Configuring call-lifecycle webhooks

​Request example

​Incoming call webhook

​Payload shape

​Payload fields

​Response

​Response fields

​Call-ended webhook

​Payload shape

​Envelope fields

​data.call fields

​data fields

​outcome values

​post_call_action_items items

​transcript block

​Text webhooks

​Inbound — text.received

​Outbound group lifecycle (group MMS)

​Per-recipient × per-subscription fan-out

​text_message field reference

​recipients[i] shape

​Conversation context

​Peer resolution

​Verifying webhook signatures

​Python verification example

​Disabling webhooks

Event types

Configuring incoming-call webhooks

Request body

Request example

Code examples

Configuring text webhooks

Request example

Code examples

Configuring call-lifecycle webhooks

Request example

Incoming call webhook

Payload shape

Payload fields

Response

Response fields

Call-ended webhook

Payload shape

Envelope fields

`data.call` fields

`data` fields

`outcome` values

`post_call_action_items` items

`transcript` block

Text webhooks

Inbound — `text.received`

Outbound group lifecycle (group MMS)

Per-recipient × per-subscription fan-out

`text_message` field reference

`recipients[i]` shape

Conversation context

Peer resolution

Verifying webhook signatures

Python verification example

Disabling webhooks