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 |
|---|---|
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 |
summary.updated | A call's summary was edited |
conversation_note.created | Internal note added to a conversation |
conversation_note.updated | Conversation note edited |
conversation_note.deleted | Conversation note deleted |
contact_note.created | Note added to a person's CRM profile |
contact_note.updated | Person note edited |
contact_note.deleted | Person note deleted |
thread.created | Discussion thread started on a conversation item |
thread.comment.created | Comment added to a thread |
thread.comment.updated | Thread comment edited |
thread.resolved | Thread marked as resolved |
thread.unresolved | Thread reopened |
teammate_message.created | A teammate sent a direct message to another teammate |
Partner events
Partner events go to the partner's own webhook endpoint, not to the account's.
| Event | Description |
|---|---|
partner.account.login | A reseller-provisioned account signed in for the first time |
| Event | Description |
|---|---|
partner.account.suspended | A partner suspended one of its accounts |
partner.account.resumed | A partner resumed one of its suspended accounts |
partner.esim.ready | An eSIM a partner ordered is ready to install |
partner.esim.failed | An eSIM a partner ordered could not be provisioned |
partner.esim.data_low | An eSIM a partner ordered has used 80% of its data this month |
partner.esim.data_exhausted | An eSIM a partner ordered has used all of its data this month |
partner.sender_id.validated | Allo approved a sender ID a partner declared |
partner.sender_id.failed | Allo rejected a sender ID a partner declared |
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. |
The person, company, and deals objects use the same schema as call.received.
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.
{
"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": "[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 | 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.
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",
"recording_download_url": "https://storage.withallo.com/object/sign/recordings/abc123.mp3?token=eyJhbGciOi...",
"recording_download_expires_at": "2025-03-17T14:45:30Z",
"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, and on accounts sold under a white-label partner's brand: use recording_download_url there. |
recording_download_url | string or null | Signed link that downloads the recording with no Allo login, valid for 48 hours. Set only on lines of accounts created by a partner, and never for a call on a HIPAA-enabled team. See Recording download link. |
recording_download_expires_at | string or null | ISO 8601 timestamp when recording_download_url stops working, 48 hours after the event was built. |
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 | Legacy field kept for compatibility. It is an empty object on current calls. The contact details the AI picks up during a call are in extracted_data, on the Conversations API |
type | string | INBOUND or OUTBOUND |
result | string | Call outcome (see values below). An outbound call that reached voicemail reports VOICEMAIL |
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) |
Recording download link
recording_download_url lets your server download the recording file without an Allo login. It stays valid for 48 hours, which covers the full webhook retry schedule, so a late retry still carries a working link. Download the file when you receive the event, or call Get recording download link later for a fresh link valid for 60 minutes.
Allo sets the link only on lines of accounts created by a partner. It is null on every other account, on calls without a recording, and on calls of a HIPAA-enabled team. Anyone who has the link can download the recording until it expires, so keep it on your server.
Call result values
| Value | Description |
|---|---|
ANSWERED | A person answered the call. On outbound calls, detected_outbound_voicemail in the Conversations API tells a human from an answering machine |
VOICEMAIL | The call went to voicemail. On inbound calls, the caller reached your voicemail. On outbound calls, the other side's voicemail picked up |
TRANSFERRED_AI | The AI receptionist handled the call |
TRANSFERRED_EXTERNAL | The call was forwarded to an external number |
BLOCKED | The call was blocked, for example a blocked or spam number |
FAILED | The call failed to connect |
FAILED_EXTERNAL | Forwarding to an external number failed. Only found on older calls |
RECEIVED | An inbound call that nobody answered, with no voicemail left |
CLOSED | The call ended before anyone answered, for example the caller hung up while it was ringing |
Handle unknown values gracefully: new outcomes may be added.
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": "MMS",
"content": "Here is a photo of the damage.",
"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]",
"attachments": [
{
"file_name": "IMG_0412.jpg",
"content_type": "image/jpeg",
"file_size": 245760,
"download_url": "https://...IMG_0412.jpg?X-Amz-Expires=1800&X-Amz-Signature=...",
"download_expires_at": "2025-03-15T16:30:00Z"
}
]
}
}
| 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 |
attachments | array | Photos and other files sent with the message. Empty for a message with no files. See Message attachments. |
Message attachments
Each item of attachments has these fields:
| Field | Type | Description |
|---|---|---|
file_name | string | Name of the file |
content_type | string | MIME type, for example image/jpeg |
file_size | integer or null | Size in bytes |
download_url | string or null | Signed link that downloads the file with no Allo login, valid for 30 minutes. null for a message on a HIPAA-enabled team, or when Allo could not sign the link. |
download_expires_at | string or null | ISO 8601 timestamp when download_url stops working |
Download the file as soon as the event arrives, and store the file rather than the link. A retried delivery can reach your endpoint after the link has expired: for a fresh link, call Get conversation item with the message id.
When Allo cannot load the attachments of a message, the event is still delivered, without the attachments field. Call Get conversation item with the message id to get them.
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]",
"attachments": []
}
}
| 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 |
attachments | array | Photos and other files sent with the message. Same format as in sms.received. |
contact.created
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 |
contact.updated
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"]
}
}
The payload structure is identical to contact.created. The data object contains the full contact state after the update.
summary.updated
Fired when someone edits a call's summary, in the Allo apps or with Update summary. Only edits to the summary Allo shows by default for that call trigger it: the number's default summary template, or the standard summary when the number has none. The AI-generated summary itself is delivered in call.completed.
{
"topic": "summary.updated",
"version": "2.0",
"timestamp": "2026-10-14T09:12:00.000Z",
"data": {
"call_id": "cll-2NfDKEm9sF8xK3pQr1Zt",
"template_key": "MARKDOWN_CLASSIC",
"content": "The customer asked about pricing and booked a demo for Thursday at 2pm.",
"version": 2,
"updated_at": "2026-10-14T09:12:00.123456",
"updated_by_email": "[email protected]",
"contact_name": "Marie Dupont"
}
}
| Field | Type | Description |
|---|---|---|
call_id | string | ID of the call the summary belongs to (cll-*), as in call.completed and the Conversations API |
template_key | string | Summary template the summary was generated with, for example MARKDOWN_CLASSIC or one of your team's templates |
content | string | The full summary after the edit (Markdown) |
version | integer | Summary version, incremented on each edit. Use it to ignore an older event that arrives late |
updated_at | string | ISO 8601 timestamp of the edit |
updated_by_email | string or null | Email of the user who made the edit |
contact_name | string or null | Name of the person the call was with, from your CRM. null when the number matches no person |
conversation_note.created
Fired when an internal note is added to a conversation, from the Allo apps or via the Notes API. conversation_note.created events are deduplicated by note ID: you receive at most one per note.
{
"topic": "conversation_note.created",
"version": "2.0",
"timestamp": "2026-07-13T10:00:00.000Z",
"data": {
"id": "not-2NyMabc123",
"content": "Escalate to @[Jane Doe](usr-abc123) tomorrow",
"allo_number": "+14155550100",
"contact_number": "+14155551234",
"user": {
"id": "usr-def456",
"name": "John Smith",
"email": "[email protected]"
},
"mentions": [
{
"user_id": "usr-abc123",
"name": "Jane Doe"
}
],
"created_at": "2026-07-13T10:00:00",
"updated_at": "2026-07-13T10:00:00",
"deleted": false
}
}
| Field | Type | Description |
|---|---|---|
id | string | Unique note identifier (not-*) |
content | string | Note text, with mentions inline as @[Name](usr-...) |
allo_number | string | The Allo line the conversation belongs to |
contact_number | string | The contact's phone number |
user | object or null | Note author (see below) |
mentions | array | Users mentioned in the note (see below) |
created_at | string | ISO 8601 timestamp when the note was created |
updated_at | string | ISO 8601 timestamp of the last edit |
deleted | boolean | false on conversation_note.created and conversation_note.updated, true on conversation_note.deleted |
User object
| Field | Type | Description |
|---|---|---|
id | string | Unique user identifier (usr-*) |
name | string or null | Display name |
email | string or null | Email address |
Mention entry
| Field | Type | Description |
|---|---|---|
user_id | string | ID of the mentioned user |
name | string or null | Display name of the mentioned user |
conversation_note.updated
Fired when a conversation note's content is edited. The payload structure is identical to conversation_note.created, with the updated content, mentions, and updated_at. Unlike *.created events, conversation_note.updated may be re-delivered. Deduplicate with the webhook-id header.
conversation_note.deleted
Fired when a conversation note is deleted. The payload structure is identical to conversation_note.created, with the note's final state and deleted: true. May be re-delivered. Deduplicate with the webhook-id header.
contact_note.created
Fired when a note is added to a person's CRM profile, from the Allo apps or via the Notes API. contact_note.created events are deduplicated by note ID: you receive at most one per note.
{
"topic": "contact_note.created",
"version": "2.0",
"timestamp": "2026-07-13T10:00:00.000Z",
"data": {
"id": "cno-abc123",
"contact_id": "con-abc123",
"person_id": "per-abc123",
"content": "Prefers email over calls. Intro by @[Jane Doe](usr-abc123).",
"user": {
"id": "usr-def456",
"name": "John Smith",
"email": "[email protected]"
},
"mentions": [
{
"user_id": "usr-abc123",
"name": "Jane Doe"
}
],
"created_at": "2026-07-13T10:00:00",
"updated_at": "2026-07-13T10:00:00",
"deleted": false
}
}
| Field | Type | Description |
|---|---|---|
id | string | Unique note identifier (cno-*) |
contact_id | string | ID of the underlying contact record (con-*), matching the ids in contact.created / contact.updated events |
person_id | string or null | ID of the person the note is on (per-*). null when the note belongs to a contact without a person. |
content | string | Note text, with mentions inline as @[Name](usr-...) |
user | object or null | Note author |
mentions | array | Users mentioned in the note |
created_at | string | ISO 8601 timestamp when the note was created |
updated_at | string | ISO 8601 timestamp of the last edit |
deleted | boolean | false on contact_note.created and contact_note.updated, true on contact_note.deleted |
The user and mentions objects use the same schema as conversation_note.created.
contact_note.updated
Fired when a person note's content is edited. The payload structure is identical to contact_note.created, with the updated content, mentions, and updated_at. May be re-delivered. Deduplicate with the webhook-id header.
contact_note.deleted
Fired when a person note is deleted. The payload structure is identical to contact_note.created, with the note's final state and deleted: true. May be re-delivered. Deduplicate with the webhook-id header.
thread.created
Fired when a discussion thread is started on a conversation item (a call, an SMS, or a conversation note), from the Allo apps or via the Threads API. Includes the thread's first comment. thread.created events are deduplicated by thread ID: you receive at most one per thread.
{
"topic": "thread.created",
"version": "2.0",
"timestamp": "2026-07-13T10:00:00.000Z",
"data": {
"id": "cth-abc123",
"entity_type": "CALL",
"entity_id": "cll-abc123",
"allo_number": "+14155550100",
"contact_number": "+14155551234",
"resolved": false,
"resolved_at": null,
"resolved_by": null,
"comment_count": 1,
"created_at": "2026-07-13T10:00:00",
"comment": {
"id": "thc-abc123",
"thread_id": "cth-abc123",
"content": "Can someone call them back today? @[Jane Doe](usr-abc123)",
"user": {
"id": "usr-def456",
"name": "John Smith",
"email": "[email protected]"
},
"mentions": [
{
"user_id": "usr-abc123",
"name": "Jane Doe"
}
],
"created_at": "2026-07-13T10:00:00",
"updated_at": "2026-07-13T10:00:00"
}
}
}
| Field | Type | Description |
|---|---|---|
id | string | Unique thread identifier (cth-*) |
entity_type | string | Type of the item the thread is attached to: CALL, TEXT_MESSAGE, or CONVERSATION_NOTE |
entity_id | string or null | ID of the conversation item (cll-*, msg-*, or not-*) |
allo_number | string | The Allo line the conversation belongs to |
contact_number | string | The contact's phone number |
resolved | boolean | Whether the thread is resolved |
resolved_at | string or null | ISO 8601 timestamp when the thread was resolved |
resolved_by | object or null | User who resolved the thread |
comment_count | number | Number of comments on the thread |
created_at | string | ISO 8601 timestamp when the thread was created |
comment | object | The thread's first comment (see below) |
Comment object
| Field | Type | Description |
|---|---|---|
id | string | Unique comment identifier (thc-*) |
thread_id | string | ID of the thread the comment belongs to |
content | string | Comment text, with mentions inline as @[Name](usr-...) |
user | object or null | Comment author |
mentions | array | Users mentioned in the comment |
created_at | string | ISO 8601 timestamp when the comment was created |
updated_at | string | ISO 8601 timestamp of the last edit |
The user, resolved_by, and mentions objects use the same schema as conversation_note.created.
thread.comment.created
Fired when a comment is added to an existing thread. data is the comment object from thread.created. thread.comment.created events are deduplicated by comment ID: you receive at most one per comment.
{
"topic": "thread.comment.created",
"version": "2.0",
"timestamp": "2026-07-13T10:05:00.000Z",
"data": {
"id": "thc-def456",
"thread_id": "cth-abc123",
"content": "On it.",
"user": {
"id": "usr-abc123",
"name": "Jane Doe",
"email": "[email protected]"
},
"mentions": [],
"created_at": "2026-07-13T10:05:00",
"updated_at": "2026-07-13T10:05:00"
}
}
thread.comment.updated
Fired when a thread comment's content is edited. data is the comment object from thread.created, with the updated content, mentions, and updated_at. May be re-delivered. Deduplicate with the webhook-id header.
thread.resolved
Fired when a thread is marked as resolved. data is the thread object from thread.created without the comment field. May be re-delivered. Deduplicate with the webhook-id header.
{
"topic": "thread.resolved",
"version": "2.0",
"timestamp": "2026-07-13T11:00:00.000Z",
"data": {
"id": "cth-abc123",
"entity_type": "CALL",
"entity_id": "cll-abc123",
"allo_number": "+14155550100",
"contact_number": "+14155551234",
"resolved": true,
"resolved_at": "2026-07-13T11:00:00",
"resolved_by": {
"id": "usr-def456",
"name": "John Smith",
"email": "[email protected]"
},
"comment_count": 2,
"created_at": "2026-07-13T10:00:00"
}
}
thread.unresolved
Fired when a resolved thread is reopened. The payload structure is identical to thread.resolved, with resolved: false and resolved_at / resolved_by set to null. May be re-delivered. Deduplicate with the webhook-id header.
teammate_message.created
Fired when a teammate sends a direct message to another teammate in the Allo apps. These messages are private: the event is only delivered to a webhook endpoint that belongs to the sender or the recipient and to no one else. An endpoint shared with the rest of the team, such as one a team admin set up for everyone, does not receive it.
{
"topic": "teammate_message.created",
"version": "2.0",
"timestamp": "2026-10-14T09:30:00.000Z",
"data": {
"id": "tmsg-2NyMabc123",
"content": "Can you call back Marie Dupont? She asked for you.",
"from_user": {
"id": "usr-def456",
"name": "John Smith",
"email": "[email protected]"
},
"to_user": {
"id": "usr-abc123",
"name": "Jane Doe",
"email": "[email protected]"
},
"sent_at": "2026-10-14T09:30:00"
}
}
| Field | Type | Description |
|---|---|---|
id | string | Unique message identifier (tmsg-*) |
content | string | Message text |
from_user | object | Sender (see User object) |
to_user | object | Recipient (see User object) |
sent_at | string | ISO 8601 timestamp when the message was sent |
partner.account.login
Fired when a reseller-provisioned account signs in on a device for the first time, the moment its number goes live. Delivered to the partner's webhook endpoint (not the account's), so resellers can track activation.
{
"topic": "partner.account.login",
"version": "2.0",
"timestamp": "2025-03-15T18:00:00.000Z",
"data": {
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"email": "[email protected]",
"name": "Vibrant Occasions Event Rentals"
}
}
| Field | Type | Description |
|---|---|---|
account_id | string | The provisioned account's user ID (usr-*) |
partner_client_ref | string or null | Your own reference, set when the account was created |
email | string | The account's email |
name | string | The account's name |
partner.account.suspended
Fired when you suspend one of your accounts with Suspend account. Delivered to the partner's webhook endpoint (not the account's). Suspending an account that is already suspended sends no second event.
{
"topic": "partner.account.suspended",
"version": "2.0",
"timestamp": "2026-10-27T09:30:00.000Z",
"data": {
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"status": "SUSPENDED"
}
}
| Field | Type | Description |
|---|---|---|
account_id | string | The provisioned account's user ID (usr-*) |
partner_client_ref | string or null | Your own reference, set when the account was created |
status | string | SUSPENDED on this event |
partner.account.resumed
Fired when you resume a suspended account with Resume account. Delivered to the partner's webhook endpoint (not the account's). The payload has the same fields as partner.account.suspended, with status set to the account's own status, for example ACTIVE. Resuming an account that is not suspended sends no event.
{
"topic": "partner.account.resumed",
"version": "2.0",
"timestamp": "2026-10-30T14:05:00.000Z",
"data": {
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"status": "ACTIVE"
}
}
Each event carries the status at the time of the change, so a quick suspend then resume delivers SUSPENDED then ACTIVE, even if both arrive after the resume.
partner.esim.ready
Fired when an eSIM you ordered with Order eSIM is ready, usually 5 to 15 minutes after the order. From that moment, calls to the number ring the eSIM. Delivered to the partner's webhook endpoint (not the account's). The payload never carries the activation code: get it with Get eSIM activation code.
{
"topic": "partner.esim.ready",
"version": "2.0",
"timestamp": "2026-10-14T10:17:00.000Z",
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"status": "ACTIVE",
"failure_code": null,
"data": {
"used_mb": 0,
"allowance_mb": 20480,
"remaining_mb": 20480,
"cycle_started_at": "2026-09-30T22:00:00",
"cycle_ends_at": "2026-10-31T23:00:00"
}
}
}
| Field | Type | Description |
|---|---|---|
esim_id | string | The eSIM ID (eso-*), as returned by Order eSIM |
account_id | string | The provisioned account's user ID (usr-*) |
partner_client_ref | string or null | Your own reference, set when the account was created |
phone_number | string | The number the eSIM carries |
tier | string | The tier code that was ordered |
status | string | PROVISIONING, ACTIVE or FAILED. ACTIVE on this event |
failure_code | string or null | null on this event |
data | object or null | Mobile data use this month: used_mb, allowance_mb, remaining_mb, cycle_started_at and cycle_ends_at, as returned by Get eSIM. On this event, the new allowance, with used_mb at 0 or null. null on partner.esim.failed |
partner.esim.failed
Fired when an eSIM you ordered could not be provisioned. Delivered to the partner's webhook endpoint (not the account's). The payload has the same fields as partner.esim.ready, with status: FAILED, failure_code set to the reason and data set to null.
{
"topic": "partner.esim.failed",
"version": "2.0",
"timestamp": "2026-10-14T10:20:00.000Z",
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"status": "FAILED",
"failure_code": "ESIM_STOCK_EMPTY",
"data": null
}
}
partner.esim.data_low
Fired when an eSIM you ordered has used 80% of its mobile data allowance for the month. Delivered to the partner's webhook endpoint (not the account's). The 80% threshold leaves a fifth of the allowance, 1 to 4 GB depending on the tier, to buy a top-up or upgrade the tier before mobile data stops.
{
"topic": "partner.esim.data_low",
"version": "2.0",
"timestamp": "2026-11-18T14:30:00.000Z",
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"status": "ACTIVE",
"failure_code": null,
"data": {
"used_mb": 16420,
"allowance_mb": 20480,
"remaining_mb": 4060,
"cycle_started_at": "2026-10-31T23:00:00",
"cycle_ends_at": "2026-11-30T23:00:00"
}
}
}
The payload has the same fields as partner.esim.ready, with data read at the time of the check.
partner.esim.data_exhausted
Fired when an eSIM you ordered has used all of its mobile data allowance for the month. Delivered to the partner's webhook endpoint (not the account's). Mobile data on the eSIM stops until the next month, or until you buy a top-up or upgrade the tier. Calls and SMS keep working, and the line is never billed for data beyond the allowance.
{
"topic": "partner.esim.data_exhausted",
"version": "2.0",
"timestamp": "2026-11-24T09:15:00.000Z",
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"status": "ACTIVE",
"failure_code": null,
"data": {
"used_mb": 20480,
"allowance_mb": 20480,
"remaining_mb": 0,
"cycle_started_at": "2026-10-31T23:00:00",
"cycle_ends_at": "2026-11-30T23:00:00"
}
}
}
The payload has the same fields as partner.esim.ready, with data read at the time of the check.
When the data events are sent
- Allo checks the data use of every active eSIM about every 15 minutes. An event can arrive up to about 15 minutes after the eSIM crosses the threshold.
- Each event is sent at most once per eSIM, per month and per allowance. A top-up or a tier upgrade raises the allowance, so both events can be sent again as the eSIM nears the new allowance.
- If the eSIM went from under 80% to 100% between two checks, only
partner.esim.data_exhaustedis sent. - The cycle is the calendar month in Paris time. A new month resets the use, and the events can be sent again.
partner.sender_id.validated
Fired when Allo approves a sender ID you declared with Declare sender ID. From that moment, the account can send SMS with it. Delivered to the partner's webhook endpoint (not the account's), once each time a sender ID moves to VALIDATED.
{
"topic": "partner.sender_id.validated",
"version": "2.0",
"timestamp": "2026-11-18T14:30:00.000Z",
"data": {
"id": "vsi-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"sender_id": "PLOMBMARTIN",
"status": "VALIDATED"
}
}
| Field | Type | Description |
|---|---|---|
id | string | The sender ID's ID (vsi-*), as returned by Declare sender ID |
account_id | string | The provisioned account's user ID (usr-*) |
partner_client_ref | string or null | Your own reference, set when the account was created |
sender_id | string | The name recipients see |
status | string | VALIDATED on this event |
partner.sender_id.failed
Fired when Allo rejects a sender ID you declared. Declare another name for the account. Delivered to the partner's webhook endpoint (not the account's), once each time a sender ID moves to FAILED. The payload has the same fields as partner.sender_id.validated, with status: FAILED.
{
"topic": "partner.sender_id.failed",
"version": "2.0",
"timestamp": "2026-11-18T14:30:00.000Z",
"data": {
"id": "vsi-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
"partner_client_ref": "client-4271",
"sender_id": "PLOMBMARTIN",
"status": "FAILED"
}
}
No webhook is sent when Allo disables a validated sender ID. Read its status with Get sender ID.