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.
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 for details.
Event summary
| Event | Description | Deduplicated |
|---|
call.received | Inbound call starts ringing | Yes |
call.triggered | Outbound call initiated | Yes |
call.completed | Call finished with full data | Yes |
tag.added | Tag added to a call | No |
tag.removed | Tag removed from a call | No |
sms.received | Inbound SMS received | Yes |
sms.sent | Outbound SMS sent | Yes |
contact.created | Contact created | Yes |
contact.updated | Contact updated | No |
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.
{
"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": "[email protected]",
"person": {
"id": "con_5MiGNHp2vI1AN6sTu4Cw",
"name": "Marie",
"last_name": "Dupont",
"email": "[email protected]",
"emails": ["[email protected]"],
"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 |
<property> | 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.
{
"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": "[email protected]",
"person": {
"id": "con_5MiGNHp2vI1AN6sTu4Cw",
"name": "Marie",
"last_name": "Dupont",
"email": "[email protected]",
"emails": ["[email protected]"],
"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. |
person, company, and deals objects use the same schema as call.received.
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.
{
"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": "[email protected]",
"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.
{
"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": "[email protected]"
}
}
| 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.
{
"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": "[email protected]"
}
}
| 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.
{
"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": "[email protected]"
}
}
| 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.
{
"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": "[email protected]"
}
}
| 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 |
Fired when a new contact is created.
{
"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": ["[email protected]"],
"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 |
Fired when an existing contact is modified.
{
"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": ["[email protected]", "[email protected]"],
"numbers": ["+33612345678", "+33698765432"]
}
}
contact.created. The data object contains the full contact state after the update.
