Allo

Event catalog

Full reference for all webhook event types and their payloads

Updated on

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

EventDescription
call.receivedInbound call starts ringing
call.triggeredOutbound call initiated
call.answeredCall answered on the other side
call.completedCall finished with full data
tag.addedTag added to a call
tag.removedTag removed from a call
sms.receivedInbound SMS received
sms.sentOutbound SMS sent
contact.createdContact created
contact.updatedContact updated
summary.updatedA call's summary was edited
conversation_note.createdInternal note added to a conversation
conversation_note.updatedConversation note edited
conversation_note.deletedConversation note deleted
contact_note.createdNote added to a person's CRM profile
contact_note.updatedPerson note edited
contact_note.deletedPerson note deleted
thread.createdDiscussion thread started on a conversation item
thread.comment.createdComment added to a thread
thread.comment.updatedThread comment edited
thread.resolvedThread marked as resolved
thread.unresolvedThread reopened
teammate_message.createdA 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.

Partners

EventDescription
partner.account.loginA reseller-provisioned account signed in for the first time

White label

EventDescription
partner.account.suspendedA partner suspended one of its accounts
partner.account.resumedA partner resumed one of its suspended accounts
partner.esim.readyAn eSIM a partner ordered is ready to install
partner.esim.failedAn eSIM a partner ordered could not be provisioned
partner.esim.data_lowAn eSIM a partner ordered has used 80% of its data this month
partner.esim.data_exhaustedAn eSIM a partner ordered has used all of its data this month
partner.sender_id.validatedAllo approved a sender ID a partner declared
partner.sender_id.failedAllo 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"
      }
    ]
  }
}
FieldTypeDescription
from_numberstringCaller's phone number
to_numberstringYour Allo phone number
started_atstringISO 8601 timestamp when the call started ringing
user_emailstringEmail of the Allo user assigned to the number
personobject or nullMatching contact person. Absent if no contact matches the caller's number.
companyobject or nullCompany linked to the contact. null if none.
dealsarray or nullDeals linked to the contact. null if none.

Person object

FieldTypeDescription
idstringUnique contact identifier
namestring or nullFirst name
last_namestring or nullLast name
emailstring or nullPrimary email address
emailsarray of stringsAll email addresses
numbersarray of stringsAll phone numbers
job_titlestring or nullJob title
<property>anyEach 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

FieldTypeDescription
idstringUnique company identifier
namestring or nullCompany name

Deal object

FieldTypeDescription
idstringUnique deal identifier
namestring or nullDeal name
statusstring or nullDeal stage or status
valuenumber or nullDeal monetary value
currencystring or nullCurrency code (e.g. EUR, USD)
close_datestring or nullExpected 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
  }
}
FieldTypeDescription
from_numberstringYour Allo phone number
to_numberstringRecipient's phone number
started_atstringISO 8601 timestamp when the call was initiated
user_emailstringEmail of the Allo user who placed the call
personobject or nullMatching contact person. Absent if no contact matches the recipient's number.
companyobject or nullCompany linked to the contact. null if none.
dealsarray or nullDeals 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
  }
}
FieldTypeDescription
from_numberstringCaller's phone number
to_numberstringRecipient's phone number
directionstringINBOUND or OUTBOUND
started_atstringISO 8601 timestamp when the call started ringing
answered_atstringISO 8601 timestamp when the call was answered
user_emailstringEmail of the Allo user on the call
personobject or nullMatching contact person. Absent if no contact matches the other party's number.
companyobject or nullCompany linked to the contact. null if none.
dealsarray or nullDeals 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

FieldTypeDescription
idstringUnique call identifier
start_datestringISO 8601 timestamp when the call started
recording_urlstring or nullURL 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_urlstring or nullSigned 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_atstring or nullISO 8601 timestamp when recording_download_url stops working, 48 hours after the event was built.
from_numberstringCaller's phone number
from_namestringCaller's name (from contacts) or your business name
tostringRecipient's phone number
to_namestringRecipient's name (from contacts) or your business name
length_in_minutesnumberCall duration in minutes (decimal)
lengthstringHuman-readable duration (e.g., "5m 30s")
tagstring or nullPrimary tag assigned to the call
tagsarray of stringsAll tags assigned to the call
summarystringAI-generated call summary
transcriptionsarrayCall transcript entries (see below)
concatenated_transcriptstringFull transcript as a single string
data_collectedobjectLegacy 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
typestringINBOUND or OUTBOUND
resultstringCall outcome (see values below). An outbound call that reached voicemail reports VOICEMAIL
integration_idstring or nullExternal CRM integration ID for the contact
transfer_fromobjectTransfer origin details (see below)
transfer_toobjectTransfer destination details (see below)
user_emailstringEmail of the Allo user who handled the call
original_to_numberstring or nullOriginal dialed number (if the call was routed)
original_to_namestring or nullOriginal recipient name
transfer_original_call_idstring or nullCall ID of the original call if this was a transfer
ivr_resultarrayIVR menu selections made during the call (see below)

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

ValueDescription
ANSWEREDA person answered the call. On outbound calls, detected_outbound_voicemail in the Conversations API tells a human from an answering machine
VOICEMAILThe call went to voicemail. On inbound calls, the caller reached your voicemail. On outbound calls, the other side's voicemail picked up
TRANSFERRED_AIThe AI receptionist handled the call
TRANSFERRED_EXTERNALThe call was forwarded to an external number
BLOCKEDThe call was blocked, for example a blocked or spam number
FAILEDThe call failed to connect
FAILED_EXTERNALForwarding to an external number failed. Only found on older calls
RECEIVEDAn inbound call that nobody answered, with no voicemail left
CLOSEDThe 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

FieldTypeDescription
sourcestringUSER (your side) or EXTERNAL (caller/recipient)
timestringISO 8601 timestamp of the transcription segment
textstringTranscribed text

Transfer object

FieldTypeDescription
numberstring or nullPhone number involved in the transfer
user_emailstring or nullEmail of the Allo user
user_namestring or nullName of the Allo user

IVR result entry

FieldTypeDescription
dtmf_keystring or nullDTMF digit pressed by the caller
text_keystring or nullMenu 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]"
  }
}
FieldTypeDescription
call_idstringID of the call the tag was added to
tag_keystringTag identifier
tag_namestringHuman-readable tag name
user_emailstring or nullEmail 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]"
  }
}
FieldTypeDescription
call_idstringID of the call the tag was removed from
tag_keystringTag identifier
tag_namestringHuman-readable tag name
user_emailstring or nullEmail 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"
      }
    ]
  }
}
FieldTypeDescription
idstringUnique message identifier
directionstringINBOUND
typestringSMS or MMS
contentstringMessage text
sent_atstringISO 8601 timestamp
from_numberstringSender's phone number
to_numberstringYour Allo phone number
from_namestringSender's name (from contacts)
to_namestringYour business name
user_emailstringEmail of the Allo user assigned to the number
attachmentsarrayPhotos 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:

FieldTypeDescription
file_namestringName of the file
content_typestringMIME type, for example image/jpeg
file_sizeinteger or nullSize in bytes
download_urlstring or nullSigned 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_atstring or nullISO 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": []
  }
}
FieldTypeDescription
idstringUnique message identifier
directionstringOUTBOUND
typestringSMS or MMS
contentstringMessage text
sent_atstringISO 8601 timestamp
from_numberstringYour Allo phone number
to_numberstringRecipient's phone number
from_namestringYour business name
to_namestringRecipient's name (from contacts)
user_emailstringEmail of the Allo user who sent the message
attachmentsarrayPhotos 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"]
  }
}
FieldTypeDescription
idstringUnique contact identifier
namestringFirst name
last_namestringLast name
companystring or nullCompany name
emailsarray of strings or nullEmail addresses
numbersarray of stringsPhone 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"
  }
}
FieldTypeDescription
call_idstringID of the call the summary belongs to (cll-*), as in call.completed and the Conversations API
template_keystringSummary template the summary was generated with, for example MARKDOWN_CLASSIC or one of your team's templates
contentstringThe full summary after the edit (Markdown)
versionintegerSummary version, incremented on each edit. Use it to ignore an older event that arrives late
updated_atstringISO 8601 timestamp of the edit
updated_by_emailstring or nullEmail of the user who made the edit
contact_namestring or nullName 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
  }
}
FieldTypeDescription
idstringUnique note identifier (not-*)
contentstringNote text, with mentions inline as @[Name](usr-...)
allo_numberstringThe Allo line the conversation belongs to
contact_numberstringThe contact's phone number
userobject or nullNote author (see below)
mentionsarrayUsers mentioned in the note (see below)
created_atstringISO 8601 timestamp when the note was created
updated_atstringISO 8601 timestamp of the last edit
deletedbooleanfalse on conversation_note.created and conversation_note.updated, true on conversation_note.deleted

User object

FieldTypeDescription
idstringUnique user identifier (usr-*)
namestring or nullDisplay name
emailstring or nullEmail address

Mention entry

FieldTypeDescription
user_idstringID of the mentioned user
namestring or nullDisplay 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
  }
}
FieldTypeDescription
idstringUnique note identifier (cno-*)
contact_idstringID of the underlying contact record (con-*), matching the ids in contact.created / contact.updated events
person_idstring or nullID of the person the note is on (per-*). null when the note belongs to a contact without a person.
contentstringNote text, with mentions inline as @[Name](usr-...)
userobject or nullNote author
mentionsarrayUsers mentioned in the note
created_atstringISO 8601 timestamp when the note was created
updated_atstringISO 8601 timestamp of the last edit
deletedbooleanfalse 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"
    }
  }
}
FieldTypeDescription
idstringUnique thread identifier (cth-*)
entity_typestringType of the item the thread is attached to: CALL, TEXT_MESSAGE, or CONVERSATION_NOTE
entity_idstring or nullID of the conversation item (cll-*, msg-*, or not-*)
allo_numberstringThe Allo line the conversation belongs to
contact_numberstringThe contact's phone number
resolvedbooleanWhether the thread is resolved
resolved_atstring or nullISO 8601 timestamp when the thread was resolved
resolved_byobject or nullUser who resolved the thread
comment_countnumberNumber of comments on the thread
created_atstringISO 8601 timestamp when the thread was created
commentobjectThe thread's first comment (see below)

Comment object

FieldTypeDescription
idstringUnique comment identifier (thc-*)
thread_idstringID of the thread the comment belongs to
contentstringComment text, with mentions inline as @[Name](usr-...)
userobject or nullComment author
mentionsarrayUsers mentioned in the comment
created_atstringISO 8601 timestamp when the comment was created
updated_atstringISO 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"
  }
}
FieldTypeDescription
idstringUnique message identifier (tmsg-*)
contentstringMessage text
from_userobjectSender (see User object)
to_userobjectRecipient (see User object)
sent_atstringISO 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"
  }
}
FieldTypeDescription
account_idstringThe provisioned account's user ID (usr-*)
partner_client_refstring or nullYour own reference, set when the account was created
emailstringThe account's email
namestringThe 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"
  }
}
FieldTypeDescription
account_idstringThe provisioned account's user ID (usr-*)
partner_client_refstring or nullYour own reference, set when the account was created
statusstringSUSPENDED 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"
    }
  }
}
FieldTypeDescription
esim_idstringThe eSIM ID (eso-*), as returned by Order eSIM
account_idstringThe provisioned account's user ID (usr-*)
partner_client_refstring or nullYour own reference, set when the account was created
phone_numberstringThe number the eSIM carries
tierstringThe tier code that was ordered
statusstringPROVISIONING, ACTIVE or FAILED. ACTIVE on this event
failure_codestring or nullnull on this event
dataobject or nullMobile 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_exhausted is 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"
  }
}
FieldTypeDescription
idstringThe sender ID's ID (vsi-*), as returned by Declare sender ID
account_idstringThe provisioned account's user ID (usr-*)
partner_client_refstring or nullYour own reference, set when the account was created
sender_idstringThe name recipients see
statusstringVALIDATED 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.