# 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](/docs/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 |
| `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.

**[Partners](/docs/partner/overview)**

| Event | Description |
|-------|-------------|
| `partner.account.login` | A reseller-provisioned account signed in for the first time |

**[White label](/docs/white-label/overview)**

| 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.

```json
{
  "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 |
| `<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.

```json
{
  "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
{
  "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
{
  "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": "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, 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-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](/docs/conversations/get-item) |
| `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](/docs/conversations/get-item-recording) 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.

```json
{
  "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
{
  "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
{
  "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": "john@acme.com",
    "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). |

### 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](/docs/conversations/get-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](/docs/conversations/get-item) with the message `id` to get them.

---

## sms.sent

Fired when an outbound SMS is sent.

```json
{
  "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",
    "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`](#message-attachments). |

---

## contact.created

Fired when a new contact is created.

```json
{
  "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
{
  "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.

---

## summary.updated

Fired when someone edits a call's summary, in the Allo apps or with [Update summary](/docs/conversations/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`](#callcompleted).

```json
{
  "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": "john@acme.com",
    "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](/docs/notes/overview). `conversation_note.created` events are deduplicated by note ID: you receive at most one per note.

```json
{
  "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": "john@acme.com"
    },
    "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`](#conversation_notecreated), 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`](#conversation_notecreated), 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](/docs/notes/overview). `contact_note.created` events are deduplicated by note ID: you receive at most one per note.

```json
{
  "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": "john@acme.com"
    },
    "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`](#conversation_notecreated).

---

## contact_note.updated

Fired when a person note's content is edited. The payload structure is identical to [`contact_note.created`](#contact_notecreated), 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`](#contact_notecreated), 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](/docs/threads/overview). Includes the thread's first comment. `thread.created` events are deduplicated by thread ID: you receive at most one per thread.

```json
{
  "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": "john@acme.com"
      },
      "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`](#conversation_notecreated).

---

## thread.comment.created

Fired when a comment is added to an existing thread. `data` is the comment object from [`thread.created`](#threadcreated). `thread.comment.created` events are deduplicated by comment ID: you receive at most one per comment.

```json
{
  "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": "jane@acme.com"
    },
    "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`](#threadcreated), 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`](#threadcreated) without the `comment` field. May be re-delivered. Deduplicate with the `webhook-id` header.

```json
{
  "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": "john@acme.com"
    },
    "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`](#threadresolved), 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.

```json
{
  "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": "john@acme.com"
    },
    "to_user": {
      "id": "usr-abc123",
      "name": "Jane Doe",
      "email": "jane@acme.com"
    },
    "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](#user-object)) |
| `to_user` | object | Recipient (see [User object](#user-object)) |
| `sent_at` | string | ISO 8601 timestamp when the message was sent |

---

## partner.account.login

Fired when a [reseller-provisioned account](/docs/partner/overview) 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.

```json
{
  "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": "owner@vibrantevents.com",
    "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](/docs/white-label/suspend-account). Delivered to the **partner's** webhook endpoint (not the account's). Suspending an account that is already suspended sends no second event.

```json
{
  "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](/docs/white-label/resume-account). Delivered to the **partner's** webhook endpoint (not the account's). The payload has the same fields as [`partner.account.suspended`](#partneraccountsuspended), with `status` set to the account's own status, for example `ACTIVE`. Resuming an account that is not suspended sends no event.

```json
{
  "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](/docs/white-label/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](/docs/white-label/get-esim-activation-code).

```json
{
  "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](/docs/white-label/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`](#partneresimready), with `status: FAILED`, `failure_code` set to the reason and `data` set to `null`.

```json
{
  "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](/docs/white-label/buy-esim-topup) or [upgrade the tier](/docs/white-label/change-esim-tier) before mobile data stops.

```json
{
  "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`](#partneresimready), 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](/docs/white-label/buy-esim-topup) or [upgrade the tier](/docs/white-label/change-esim-tier). Calls and SMS keep working, and the line is never billed for data beyond the allowance.

```json
{
  "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`](#partneresimready), 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](/docs/white-label/create-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`.

```json
{
  "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`](#partnersender_idvalidated), with `status: FAILED`.

```json
{
  "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](/docs/white-label/get-sender-id).
