> ## Documentation Index > Fetch the complete documentation index at: https://help.withallo.com/llms.txt > Use this file to discover all available pages before exploring further. # Event catalog > Full reference for all webhook event types and their payloads Events follow the `entity.action` naming convention. Allo delivers events at least once — your endpoint may receive the same event more than once. Use the `webhook-id` header to deduplicate. See [Best practices](/en/v2/api-reference/webhooks/best-practices) for details. ## Event summary | Event | Description | | ----------------- | ------------------------------- | | `call.received` | Inbound call starts ringing | | `call.triggered` | Outbound call initiated | | `call.answered` | Call answered on the other side | | `call.completed` | Call finished with full data | | `tag.added` | Tag added to a call | | `tag.removed` | Tag removed from a call | | `sms.received` | Inbound SMS received | | `sms.sent` | Outbound SMS sent | | `contact.created` | Contact created | | `contact.updated` | Contact updated | *** ## call.received Fired when an inbound call starts ringing, before the call is answered. When a matching contact is found, the event includes `person`, `company`, and `deals` objects with contact context. ```json theme={null} { "topic": "call.received", "version": "2.0", "timestamp": "2025-03-15T14:30:00.000Z", "data": { "from_number": "+33612345678", "to_number": "+33112345678", "started_at": "2025-03-15T14:30:00.000Z", "user_email": "john@acme.com", "person": { "id": "con_5MiGNHp2vI1AN6sTu4Cw", "name": "Marie", "last_name": "Dupont", "email": "marie.dupont@acme.com", "emails": ["marie.dupont@acme.com"], "numbers": ["+33612345678"], "job_title": "Head of Sales", "linkedin_url": "https://linkedin.com/in/mariedupont", "lead_source": "Inbound" }, "company": { "id": "com-a1b2c3d4e5f6", "name": "Acme Corp" }, "deals": [ { "id": "dea-x1y2z3w4v5u6", "name": "Enterprise Plan", "status": "qualified", "value": 25000.00, "currency": "EUR", "close_date": "2025-06-15T00:00:00" } ] } } ``` | Field | Type | Description | | ------------- | -------------- | -------------------------------------------------------------------------- | | `from_number` | string | Caller's phone number | | `to_number` | string | Your Allo phone number | | `started_at` | string | ISO 8601 timestamp when the call started ringing | | `user_email` | string | Email of the Allo user assigned to the number | | `person` | object or null | Matching contact person. Absent if no contact matches the caller's number. | | `company` | object or null | Company linked to the contact. `null` if none. | | `deals` | array or null | Deals linked to the contact. `null` if none. | ### Person object | Field | Type | Description | | ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | Unique contact identifier | | `name` | string or null | First name | | `last_name` | string or null | Last name | | `email` | string or null | Primary email address | | `emails` | array of strings | All email addresses | | `numbers` | array of strings | All phone numbers | | `job_title` | string or null | Job title | | `` | any | Each contact property you have defined appears as a top-level key (e.g. `linkedin_url`, `lead_source`). Only non-null values are included. | ### Company object | Field | Type | Description | | ------ | -------------- | ------------------------- | | `id` | string | Unique company identifier | | `name` | string or null | Company name | ### Deal object | Field | Type | Description | | ------------ | -------------- | --------------------------------- | | `id` | string | Unique deal identifier | | `name` | string or null | Deal name | | `status` | string or null | Deal stage or status | | `value` | number or null | Deal monetary value | | `currency` | string or null | Currency code (e.g. `EUR`, `USD`) | | `close_date` | string or null | Expected close date (ISO 8601) | *** ## call.triggered Fired when an outbound call is initiated. When a matching contact is found, the event includes `person`, `company`, and `deals` objects with contact context. ```json theme={null} { "topic": "call.triggered", "version": "2.0", "timestamp": "2025-03-15T14:35:00.000Z", "data": { "from_number": "+33112345678", "to_number": "+33612345678", "started_at": "2025-03-15T14:35:00.000Z", "user_email": "john@acme.com", "person": { "id": "con_5MiGNHp2vI1AN6sTu4Cw", "name": "Marie", "last_name": "Dupont", "email": "marie.dupont@acme.com", "emails": ["marie.dupont@acme.com"], "numbers": ["+33612345678"], "job_title": "Head of Sales" }, "company": { "id": "com-a1b2c3d4e5f6", "name": "Acme Corp" }, "deals": null } } ``` | Field | Type | Description | | ------------- | -------------- | ----------------------------------------------------------------------------- | | `from_number` | string | Your Allo phone number | | `to_number` | string | Recipient's phone number | | `started_at` | string | ISO 8601 timestamp when the call was initiated | | `user_email` | string | Email of the Allo user who placed the call | | `person` | object or null | Matching contact person. Absent if no contact matches the recipient's number. | | `company` | object or null | Company linked to the contact. `null` if none. | | `deals` | array or null | Deals linked to the contact. `null` if none. | The `person`, `company`, and `deals` objects use the same schema as [`call.received`](#callreceived). *** ## call.answered Fired the moment a call is answered on the other side, for both inbound and outbound calls — after `call.received` / `call.triggered` (ring) and before `call.completed` (hang-up). Use it to react in real time when the prospect picks up. When a matching contact is found, the event includes `person`, `company`, and `deals` objects with contact context. ```json theme={null} { "topic": "call.answered", "version": "2.0", "timestamp": "2025-03-15T14:30:08.000Z", "data": { "from_number": "+33612345678", "to_number": "+33112345678", "direction": "OUTBOUND", "started_at": "2025-03-15T14:30:00.000Z", "answered_at": "2025-03-15T14:30:08.000Z", "user_email": "john@acme.com", "person": { "id": "con_5MiGNHp2vI1AN6sTu4Cw", "name": "Marie", "last_name": "Dupont", "email": "marie.dupont@acme.com", "emails": ["marie.dupont@acme.com"], "numbers": ["+33612345678"], "job_title": "Head of Sales" }, "company": { "id": "com-a1b2c3d4e5f6", "name": "Acme Corp" }, "deals": null } } ``` | Field | Type | Description | | ------------- | -------------- | ------------------------------------------------------------------------------- | | `from_number` | string | Caller's phone number | | `to_number` | string | Recipient's phone number | | `direction` | string | `INBOUND` or `OUTBOUND` | | `started_at` | string | ISO 8601 timestamp when the call started ringing | | `answered_at` | string | ISO 8601 timestamp when the call was answered | | `user_email` | string | Email of the Allo user on the call | | `person` | object or null | Matching contact person. Absent if no contact matches the other party's number. | | `company` | object or null | Company linked to the contact. `null` if none. | | `deals` | array or null | Deals linked to the contact. `null` if none. | The `person`, `company`, and `deals` objects use the same schema as [`call.received`](#callreceived). *** ## call.completed Fired after a call ends. Includes the full call data: recording, transcript, summary, tags, and transfer details. This event is typically sent about 30 seconds after the call hangs up. ```json theme={null} { "topic": "call.completed", "version": "2.0", "timestamp": "2025-03-15T14:45:00.000Z", "data": { "id": "cll_2NfDKEm9sF8xK3pQr1Zt", "start_date": "2025-03-15T14:30:00.000Z", "recording_url": "https://storage.withallo.com/recordings/abc123.mp3", "from_number": "+33612345678", "from_name": "Marie Dupont", "to": "+33112345678", "to_name": "Support Acme", "length_in_minutes": 5.5, "length": "5m 30s", "tag": "support", "tags": ["support", "urgent"], "summary": "The customer called about a billing issue with their last invoice. The agent confirmed the charge was correct and explained the new pricing plan.", "transcriptions": [ { "source": "EXTERNAL", "time": "2025-03-15T14:30:05.000Z", "text": "Hi, I have a question about my last invoice." }, { "source": "USER", "time": "2025-03-15T14:30:12.000Z", "text": "Of course, let me pull up your account." } ], "concatenated_transcript": "Hi, I have a question about my last invoice.\nOf course, let me pull up your account.", "data_collected": { "account_number": "12345" }, "type": "INBOUND", "result": "ANSWERED", "integration_id": null, "transfer_from": { "number": null, "user_email": null, "user_name": null }, "transfer_to": { "number": null, "user_email": null, "user_name": null }, "user_email": "john@acme.com", "original_to_number": null, "original_to_name": null, "transfer_original_call_id": null, "ivr_result": [ { "dtmf_key": "2", "text_key": "Support" } ] } } ``` ### Fields | Field | Type | Description | | --------------------------- | ---------------- | --------------------------------------------------------------- | | `id` | string | Unique call identifier | | `start_date` | string | ISO 8601 timestamp when the call started | | `recording_url` | string or null | URL to the call recording (MP3). Null if recording is disabled. | | `from_number` | string | Caller's phone number | | `from_name` | string | Caller's name (from contacts) or your business name | | `to` | string | Recipient's phone number | | `to_name` | string | Recipient's name (from contacts) or your business name | | `length_in_minutes` | number | Call duration in minutes (decimal) | | `length` | string | Human-readable duration (e.g., `"5m 30s"`) | | `tag` | string or null | Primary tag assigned to the call | | `tags` | array of strings | All tags assigned to the call | | `summary` | string | AI-generated call summary | | `transcriptions` | array | Call transcript entries (see below) | | `concatenated_transcript` | string | Full transcript as a single string | | `data_collected` | object | Custom data collected during the call (e.g., from IVR) | | `type` | string | `INBOUND` or `OUTBOUND` | | `result` | string | Call outcome (see values below) | | `integration_id` | string or null | External CRM integration ID for the contact | | `transfer_from` | object | Transfer origin details (see below) | | `transfer_to` | object | Transfer destination details (see below) | | `user_email` | string | Email of the Allo user who handled the call | | `original_to_number` | string or null | Original dialed number (if the call was routed) | | `original_to_name` | string or null | Original recipient name | | `transfer_original_call_id` | string or null | Call ID of the original call if this was a transfer | | `ivr_result` | array | IVR menu selections made during the call (see below) | ### Call result values | Value | Description | | ---------------------- | ------------------------------------------ | | `ANSWERED` | Call was answered | | `VOICEMAIL` | Caller left a voicemail | | `TRANSFERRED_AI` | Call was handled by the AI agent | | `TRANSFERRED_EXTERNAL` | Call was transferred to an external number | | `BLOCKED` | Call was blocked | | `FAILED` | Call failed to connect | ### Transcription entry | Field | Type | Description | | -------- | ------ | --------------------------------------------------- | | `source` | string | `USER` (your side) or `EXTERNAL` (caller/recipient) | | `time` | string | ISO 8601 timestamp of the transcription segment | | `text` | string | Transcribed text | ### Transfer object | Field | Type | Description | | ------------ | -------------- | ------------------------------------- | | `number` | string or null | Phone number involved in the transfer | | `user_email` | string or null | Email of the Allo user | | `user_name` | string or null | Name of the Allo user | ### IVR result entry | Field | Type | Description | | ---------- | -------------- | -------------------------------- | | `dtmf_key` | string or null | DTMF digit pressed by the caller | | `text_key` | string or null | Menu label selected | *** ## tag.added Fired when a tag is added to a call. ```json theme={null} { "topic": "tag.added", "version": "2.0", "timestamp": "2025-03-15T15:00:00.000Z", "data": { "call_id": "cll_2NfDKEm9sF8xK3pQr1Zt", "tag_key": "urgent", "tag_name": "Urgent", "user_email": "john@acme.com" } } ``` | Field | Type | Description | | ------------ | -------------- | ----------------------------------- | | `call_id` | string | ID of the call the tag was added to | | `tag_key` | string | Tag identifier | | `tag_name` | string | Human-readable tag name | | `user_email` | string or null | Email of the user who added the tag | *** ## tag.removed Fired when a tag is removed from a call. ```json theme={null} { "topic": "tag.removed", "version": "2.0", "timestamp": "2025-03-15T15:05:00.000Z", "data": { "call_id": "cll_2NfDKEm9sF8xK3pQr1Zt", "tag_key": "urgent", "tag_name": "Urgent", "user_email": "john@acme.com" } } ``` | Field | Type | Description | | ------------ | -------------- | --------------------------------------- | | `call_id` | string | ID of the call the tag was removed from | | `tag_key` | string | Tag identifier | | `tag_name` | string | Human-readable tag name | | `user_email` | string or null | Email of the user who removed the tag | *** ## sms.received Fired when an inbound SMS is received. ```json theme={null} { "topic": "sms.received", "version": "2.0", "timestamp": "2025-03-15T16:00:00.000Z", "data": { "id": "msg_3KgELFn0tG9yL4qRs2Au", "direction": "INBOUND", "type": "SMS", "content": "Hi, I'd like to schedule an appointment.", "sent_at": "2025-03-15T16:00:00.000Z", "from_number": "+33612345678", "to_number": "+33112345678", "from_name": "Marie Dupont", "to_name": "Support Acme", "user_email": "john@acme.com" } } ``` | Field | Type | Description | | ------------- | ------ | --------------------------------------------- | | `id` | string | Unique message identifier | | `direction` | string | `INBOUND` | | `type` | string | `SMS` or `MMS` | | `content` | string | Message text | | `sent_at` | string | ISO 8601 timestamp | | `from_number` | string | Sender's phone number | | `to_number` | string | Your Allo phone number | | `from_name` | string | Sender's name (from contacts) | | `to_name` | string | Your business name | | `user_email` | string | Email of the Allo user assigned to the number | *** ## sms.sent Fired when an outbound SMS is sent. ```json theme={null} { "topic": "sms.sent", "version": "2.0", "timestamp": "2025-03-15T16:10:00.000Z", "data": { "id": "msg_4LhFMGo1uH0zM5rSt3Bv", "direction": "OUTBOUND", "type": "SMS", "content": "Your appointment is confirmed for tomorrow at 2pm.", "sent_at": "2025-03-15T16:10:00.000Z", "from_number": "+33112345678", "to_number": "+33612345678", "from_name": "Support Acme", "to_name": "Marie Dupont", "user_email": "john@acme.com" } } ``` | Field | Type | Description | | ------------- | ------ | ------------------------------------------- | | `id` | string | Unique message identifier | | `direction` | string | `OUTBOUND` | | `type` | string | `SMS` or `MMS` | | `content` | string | Message text | | `sent_at` | string | ISO 8601 timestamp | | `from_number` | string | Your Allo phone number | | `to_number` | string | Recipient's phone number | | `from_name` | string | Your business name | | `to_name` | string | Recipient's name (from contacts) | | `user_email` | string | Email of the Allo user who sent the message | *** ## contact.created Fired when a new contact is created. ```json theme={null} { "topic": "contact.created", "version": "2.0", "timestamp": "2025-03-15T17:00:00.000Z", "data": { "id": "con_5MiGNHp2vI1AN6sTu4Cw", "name": "Marie", "last_name": "Dupont", "company": "Acme Corp", "emails": ["marie.dupont@acme.com"], "numbers": ["+33612345678"] } } ``` | Field | Type | Description | | ----------- | ------------------------ | ------------------------- | | `id` | string | Unique contact identifier | | `name` | string | First name | | `last_name` | string | Last name | | `company` | string or null | Company name | | `emails` | array of strings or null | Email addresses | | `numbers` | array of strings | Phone numbers | *** ## contact.updated Fired when an existing contact is modified. ```json theme={null} { "topic": "contact.updated", "version": "2.0", "timestamp": "2025-03-15T17:05:00.000Z", "data": { "id": "con_5MiGNHp2vI1AN6sTu4Cw", "name": "Marie", "last_name": "Dupont", "company": "Acme Corp", "emails": ["marie.dupont@acme.com", "m.dupont@personal.com"], "numbers": ["+33612345678", "+33698765432"] } } ``` The payload structure is identical to `contact.created`. The `data` object contains the full contact state after the update.