---
title: Webhook Events | API Docs
description: Event types you can subscribe to, with a representative payload for each category.
---

Every webhook delivered by Linq shares a common envelope with a `data` field specific to the event type. This page lists the event types you can subscribe to and shows a representative payload per category. Each example is sourced directly from the OpenAPI spec — pick a version tab on any example and every other example on the page switches to that version too. For setup, signature verification, and delivery guarantees see [Webhooks](/channel/imessage/guides/webhooks/index.md); for subscription management see [Webhook Subscriptions](/channel/imessage/guides/webhooks/subscriptions/index.md).

> **Authoritative list of event types** (rendered from the OpenAPI spec): `message.sent` , `message.received` , `message.read` , `message.delivered` , `message.failed` , `message.edited` , `reaction.added` , `reaction.removed` , `poll.received` , `poll.failed` , `poll.sent` , `poll.delivered` , `poll.read` , `poll.updated` , `poll.vote.added` , `poll.vote.removed` , `poll.reaction.added` , `participant.added` , `participant.removed` , `chat.created` , `chat.group_name_updated` , `chat.group_icon_updated` , `chat.group_name_update_failed` , `chat.group_icon_update_failed` , `chat.background_updated` , `chat.background_update_failed` , `chat.typing_indicator.started` , `chat.typing_indicator.stopped` , `phone_number.status_updated` , `contact_card.received` , `call.initiated` , `call.ringing` , `call.answered` , `call.ended` , `call.failed` , `call.declined` , `call.no_answer` , `location.sharing.started` , `location.sharing.stopped` , `payment.succeeded` , `payment.canceled` , `payment.expired` , `payment.declined` , `payment.authorized` , `connection.created` , `connection.revoked` .
>
> Categories below describe the most common events. If a type appears in this canonical list but not in a category section, treat the canonical list as source of truth and refer to the [API Reference: Webhook Events](/channel/imessage/api/resources/webhooks/index.md) for the payload schema.

## Webhook envelope

All webhook payloads share a common envelope:

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.received",
  "event_id": "2915e81c-5068-4796-ace2-21d2c94ad298",
  "created_at": "2026-02-05T19:31:13.736Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "your-partner-id",
  "data": { ... }
}
```

| Field             | Description                                    |
| ----------------- | ---------------------------------------------- |
| `api_version`     | API version (`v3`)                             |
| `webhook_version` | Payload version (`2025-01-01` or `2026-02-03`) |
| `event_type`      | Event type string                              |
| `event_id`        | Unique event ID (use for deduplication)        |
| `created_at`      | When the event was created                     |
| `trace_id`        | Trace ID for debugging                         |
| `partner_id`      | Your partner identifier                        |
| `data`            | Event-specific payload                         |

## Message events

| Event               | Description                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message.sent`      | Message successfully sent from your phone number                                                                                                     |
| `message.received`  | Incoming message received on your phone number                                                                                                       |
| `message.delivered` | Message delivered to recipient’s device                                                                                                              |
| `message.read`      | Message read by recipient                                                                                                                            |
| `message.failed`    | Message delivery failed                                                                                                                              |
| `message.edited`    | Message was edited (2026-02-03 version only) — see [Editing messages](/channel/imessage/guides/messaging/sending-messages#editing-messages/index.md) |

**Lifecycle timestamps** indicate the event stage:

- `sent_at` — set on `message.sent` and `message.received`
- `delivered_at` — set on `message.delivered`
- `read_at` — set on `message.read`

`message.edited` is only delivered to `2026-02-03` subscriptions.

There is no mention event. [Mentions](/channel/imessage/guides/messaging/mentions/index.md) come back as `mentions` on the text part — of `message.sent`, `message.delivered`, and `message.read` for one you sent, and of `message.received` when a participant mentions your line. The older `mention` / `mention_range` fields report only the first mention on a part and are deprecated on responses.

In `2026-02-03` payloads, the `chat` sub-object includes a `health_status` field — see [Chat Health](/channel/imessage/guides/chats/chat-health/index.md).

> **Note:** SMS and MMS sends **do not produce `message.delivered` or `message.read` webhooks** — neither receipt type exists on those protocols. You’ll still get `message.sent` (accepted for delivery) and `message.failed` (hard failure), but treat the absence of a `delivered` event on an SMS fallback as normal, not a bug. See [Protocol capabilities](/channel/imessage/guides/messaging/protocol-selection#protocol-capabilities/index.md) for the full matrix.

### `message.sent`

Outbound message confirmed as sent from your phone number. `delivered_at` and `read_at` are still null.

- [2026-02-03](#tab-panel-0-0)
- [2025-01-01](#tab-panel-0-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.sent",
  "event_id": "e20feb41-7f67-43f0-89c8-a985cff3b568",
  "created_at": "2026-02-05T19:52:18.101373886Z",
  "trace_id": "2eff5df5c6f688733c007523c4d61cd9",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "0c961e93-e7bf-4db2-bf7b-ea06826bcab4",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "8d79532a-f529-4244-a5cf-d443de051434",
        "is_me": true,
        "joined_at": "2026-01-21T21:59:45.191571Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      },
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/channel/imessage/guides/chats/chat-health#healthy",
        "updated_at": "2026-02-05T19:52:17.000Z"
      }
    },
    "id": "347d62c2-2170-4754-8d30-c76d0c727d96",
    "idempotency_key": null,
    "direction": "outbound",
    "sender_handle": {
      "handle": "+12025551234",
      "id": "8d79532a-f529-4244-a5cf-d443de051434",
      "is_me": true,
      "joined_at": "2026-01-21T21:59:45.191571Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "parts": [
      {
        "type": "text",
        "value": "Hello from Linq!"
      },
      {
        "filename": "photo.jpg",
        "id": "f13dda7d-ecac-49eb-b3fe-16fe286abf19",
        "mime_type": "image/jpeg",
        "size_bytes": 245678,
        "type": "media",
        "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/photo.jpg?signature=..."
      }
    ],
    "effect": null,
    "sent_at": "2026-02-05T19:52:17.219Z",
    "delivered_at": null,
    "read_at": null,
    "service": "iMessage",
    "preferred_service": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.sent",
  "event_id": "e20feb41-7f67-43f0-89c8-a985cff3b568",
  "created_at": "2026-02-05T19:52:18.101373886Z",
  "trace_id": "2eff5df5c6f688733c007523c4d61cd9",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "0c961e93-e7bf-4db2-bf7b-ea06826bcab4",
    "from": "+12025551234",
    "from_handle": {
      "handle": "+12025551234",
      "id": "8d79532a-f529-4244-a5cf-d443de051434",
      "is_me": true,
      "joined_at": "2026-01-21T21:59:45.191571Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "idempotency_key": null,
    "is_from_me": true,
    "is_group": false,
    "message": {
      "created_at": "2026-02-05T19:52:17.041183Z",
      "delivered_at": null,
      "id": "347d62c2-2170-4754-8d30-c76d0c727d96",
      "is_delivered": false,
      "is_read": false,
      "parts": [
        {
          "type": "text",
          "value": "Hello from Linq!"
        },
        {
          "filename": "photo.gif",
          "id": "f13dda7d-ecac-49eb-b3fe-16fe286abf19",
          "mime_type": "image/gif",
          "size_bytes": 2776819,
          "type": "media",
          "url": "https://cdn.linqapp.com/attachments/example/photo.gif"
        }
      ],
      "read_at": null,
      "sent_at": "2026-02-05T19:52:17.219Z",
      "updated_at": "2026-02-05T19:52:18.084038Z"
    },
    "preferred_service": null,
    "received_at": null,
    "recipient_handle": null,
    "recipient_phone": null,
    "service": "iMessage"
  }
}
```

### `message.received`

Inbound message from a participant. Contains the full message content and any attachments.

- [2026-02-03](#tab-panel-1-0)
- [2025-01-01](#tab-panel-1-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.received",
  "event_id": "2915e81c-5068-4796-ace2-21d2c94ad298",
  "created_at": "2026-02-05T19:31:13.736444093Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "8f392755-6865-4b18-880a-227f9d8b458f",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "6d6c617f-187a-4dcd-a0d5-988347a8c092",
        "is_me": true,
        "joined_at": "2026-01-04T05:48:51.321469Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      },
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/channel/imessage/guides/chats/chat-health#healthy",
        "updated_at": "2026-02-05T19:31:12.000Z"
      }
    },
    "id": "89e3566e-1d13-49e5-a8ee-48490d5bfeb7",
    "direction": "inbound",
    "sender_handle": {
      "handle": "+12025559876",
      "id": "e604375a-5913-483a-8278-c631e8f0ffda",
      "is_me": false,
      "joined_at": "2026-01-04T05:48:51.321469Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "parts": [
      {
        "type": "text",
        "value": "Hello!"
      }
    ],
    "effect": null,
    "reply_to": null,
    "sent_at": "2026-02-05T19:31:13.074Z",
    "delivered_at": null,
    "read_at": null,
    "service": "iMessage"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.received",
  "event_id": "2915e81c-5068-4796-ace2-21d2c94ad298",
  "created_at": "2026-02-05T19:31:13.736444093Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "8f392755-6865-4b18-880a-227f9d8b458f",
    "from": "+12025559876",
    "from_handle": {
      "handle": "+12025559876",
      "id": "e604375a-5913-483a-8278-c631e8f0ffda",
      "is_me": false,
      "joined_at": "2026-01-04T05:48:51.321469Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "idempotency_key": null,
    "is_from_me": false,
    "is_group": false,
    "message": {
      "created_at": "2026-02-05T19:31:12.892Z",
      "delivered_at": null,
      "id": "89e3566e-1d13-49e5-a8ee-48490d5bfeb7",
      "is_delivered": false,
      "is_read": false,
      "parts": [
        {
          "type": "text",
          "value": "Hello!"
        }
      ],
      "read_at": null,
      "sent_at": "2026-02-05T19:31:13.074Z",
      "updated_at": "2026-02-05T19:31:13.712Z"
    },
    "preferred_service": null,
    "received_at": "2026-02-05T19:31:13.074Z",
    "recipient_handle": {
      "handle": "+12025551234",
      "id": "6d6c617f-187a-4dcd-a0d5-988347a8c092",
      "is_me": true,
      "joined_at": "2026-01-04T05:48:51.321469Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "recipient_phone": null,
    "service": "iMessage"
  }
}
```

### `message.delivered`

Outbound message reached the recipient’s device. Fires on iMessage and RCS — not on SMS/MMS, which have no delivery receipt mechanism.

- [2026-02-03](#tab-panel-2-0)
- [2025-01-01](#tab-panel-2-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.delivered",
  "event_id": "67c4ad39-e9b0-47f6-82f8-64bdd8ceafa6",
  "created_at": "2026-02-05T19:52:22.593689073Z",
  "trace_id": "abde7f6248fba00f97e8c7dc4782d7e0",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "0c961e93-e7bf-4db2-bf7b-ea06826bcab4",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "8d79532a-f529-4244-a5cf-d443de051434",
        "is_me": true,
        "joined_at": "2026-01-21T21:59:45.191571Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      },
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/channel/imessage/guides/chats/chat-health#healthy",
        "updated_at": "2026-02-05T19:52:17.000Z"
      }
    },
    "id": "347d62c2-2170-4754-8d30-c76d0c727d96",
    "idempotency_key": null,
    "direction": "outbound",
    "sender_handle": {
      "handle": "+12025551234",
      "id": "8d79532a-f529-4244-a5cf-d443de051434",
      "is_me": true,
      "joined_at": "2026-01-21T21:59:45.191571Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "parts": [
      {
        "type": "text",
        "value": "Hello from Linq!"
      },
      {
        "filename": "photo.gif",
        "id": "f13dda7d-ecac-49eb-b3fe-16fe286abf19",
        "mime_type": "image/gif",
        "size_bytes": 2776819,
        "type": "media",
        "url": "https://cdn.linqapp.com/attachments/f13dda7d/photo.gif?signature=..."
      }
    ],
    "effect": null,
    "sent_at": "2026-02-05T19:52:17.219Z",
    "delivered_at": "2026-02-05T19:52:22.291Z",
    "read_at": null,
    "service": "iMessage",
    "preferred_service": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.delivered",
  "event_id": "67c4ad39-e9b0-47f6-82f8-64bdd8ceafa6",
  "created_at": "2026-02-05T19:52:22.593689073Z",
  "trace_id": "abde7f6248fba00f97e8c7dc4782d7e0",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "0c961e93-e7bf-4db2-bf7b-ea06826bcab4",
    "from": "+12025551234",
    "from_handle": {
      "handle": "+12025551234",
      "id": "8d79532a-f529-4244-a5cf-d443de051434",
      "is_me": true,
      "joined_at": "2026-01-21T21:59:45.191571Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "idempotency_key": null,
    "is_from_me": true,
    "is_group": false,
    "message": {
      "created_at": "2026-02-05T19:52:17.041183Z",
      "delivered_at": "2026-02-05T19:52:22.291Z",
      "id": "347d62c2-2170-4754-8d30-c76d0c727d96",
      "is_delivered": true,
      "is_read": false,
      "parts": [
        {
          "type": "text",
          "value": "Hello from Linq!"
        },
        {
          "filename": "photo.gif",
          "id": "f13dda7d-ecac-49eb-b3fe-16fe286abf19",
          "mime_type": "image/gif",
          "size_bytes": 2776819,
          "type": "media",
          "url": "https://cdn.linqapp.com/attachments/example/photo.gif"
        }
      ],
      "read_at": null,
      "sent_at": "2026-02-05T19:52:17.219Z",
      "updated_at": "2026-02-05T19:52:22.571Z"
    },
    "delivered_at": "2026-02-05T19:52:22.291Z",
    "message_id": "347d62c2-2170-4754-8d30-c76d0c727d96",
    "preferred_service": null,
    "received_at": null,
    "recipient_handle": null,
    "recipient_phone": null,
    "service": "iMessage"
  }
}
```

### `message.read`

Outbound message was read by the recipient. Fires on iMessage and RCS (not SMS/MMS), and requires the recipient to have read receipts enabled on their device.

- [2026-02-03](#tab-panel-3-0)
- [2025-01-01](#tab-panel-3-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.read",
  "event_id": "8fd42065-b998-482a-93b3-da855f8dad17",
  "created_at": "2026-02-05T19:13:58.833366566Z",
  "trace_id": "cbb93c08fa1a3f3c4c2efc161d67f36d",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "24e33345-e6cf-4f50-9d35-1d7fde8c9818",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "d31678e9-0442-48fd-b7ed-c898d245dd15",
        "is_me": true,
        "joined_at": "2026-01-18T03:38:41.442254Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      },
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/channel/imessage/guides/chats/chat-health#healthy",
        "updated_at": "2026-02-05T19:13:57.000Z"
      }
    },
    "id": "dc6d3f68-90df-48f0-a504-e65f239a383c",
    "idempotency_key": null,
    "direction": "outbound",
    "sender_handle": {
      "handle": "+12025551234",
      "id": "d31678e9-0442-48fd-b7ed-c898d245dd15",
      "is_me": true,
      "joined_at": "2026-01-18T03:38:41.442254Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "parts": [
      {
        "type": "text",
        "value": "Hello world!"
      }
    ],
    "effect": null,
    "sent_at": "2026-02-05T19:13:57.814Z",
    "delivered_at": "2026-02-05T19:13:57.948Z",
    "read_at": "2026-02-05T19:13:58.177Z",
    "service": "iMessage",
    "preferred_service": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.read",
  "event_id": "8fd42065-b998-482a-93b3-da855f8dad17",
  "created_at": "2026-02-05T19:13:58.833366566Z",
  "trace_id": "cbb93c08fa1a3f3c4c2efc161d67f36d",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "24e33345-e6cf-4f50-9d35-1d7fde8c9818",
    "from": "+12025551234",
    "from_handle": {
      "handle": "+12025551234",
      "id": "d31678e9-0442-48fd-b7ed-c898d245dd15",
      "is_me": true,
      "joined_at": "2026-01-18T03:38:41.442254Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "idempotency_key": null,
    "is_from_me": true,
    "is_group": false,
    "message": {
      "created_at": "2026-02-05T19:13:57.612Z",
      "delivered_at": "2026-02-05T19:13:57.948Z",
      "id": "dc6d3f68-90df-48f0-a504-e65f239a383c",
      "is_delivered": true,
      "is_read": true,
      "parts": [
        {
          "type": "text",
          "value": "Hello world!"
        }
      ],
      "read_at": "2026-02-05T19:13:58.177Z",
      "sent_at": "2026-02-05T19:13:57.814Z",
      "updated_at": "2026-02-05T19:13:58.811Z"
    },
    "message_id": "dc6d3f68-90df-48f0-a504-e65f239a383c",
    "preferred_service": null,
    "read_at": "2026-02-05T19:13:58.177Z",
    "received_at": null,
    "recipient_handle": null,
    "recipient_phone": null,
    "service": "iMessage"
  }
}
```

### `message.failed`

Message delivery failed. `code` maps to an [error code](/channel/imessage/error/index.md); common causes are request timeouts, upstream processing errors, and service unavailability.

`service` is the transport on which the failure occurred (`iMessage`, `RCS`, or `SMS`). It is `null` when the message failed before a transport was established. `preferred_service` is the service requested for the send (`iMessage`, `RCS`, `SMS`, or `auto`). It is `null` when no preference was specified, which is the common case.

`detail_code`, when present, is an opaque diagnostic code identifying the specific failure class within `code`. Log it and include it in support requests, but do not branch application behavior on it; its values are not part of the stable error-code contract. Use `code` for programmatic error handling.

- [2026-02-03](#tab-panel-4-0)
- [2025-01-01](#tab-panel-4-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "code": 4006,
    "detail_code": 100001,
    "reason": "Message send timed out",
    "service": null,
    "preferred_service": "RCS",
    "failed_at": "2025-11-23T17:35:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "code": 4006,
    "detail_code": 100001,
    "reason": "Message send timed out",
    "service": null,
    "preferred_service": "RCS",
    "failed_at": "2025-11-23T17:35:00.000Z"
  }
}
```

### `message.edited`

A text part of a previously sent message was edited. Only delivered to subscriptions on `webhook_version: "2026-02-03"` — see [Editing messages](/channel/imessage/guides/messaging/sending-messages#editing-messages/index.md).

- [2026-02-03](#tab-panel-5-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.edited",
  "event_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "created_at": "2026-03-05T02:12:46.501Z",
  "trace_id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "8f392755-6865-4b18-880a-227f9d8b458f",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "6d6c617f-187a-4dcd-a0d5-988347a8c092",
        "is_me": true,
        "joined_at": "2026-01-04T05:48:51.321469Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      },
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/channel/imessage/guides/chats/chat-health#healthy",
        "updated_at": "2026-03-05T02:12:45.000Z"
      }
    },
    "id": "89e3566e-1d13-49e5-a8ee-48490d5bfeb7",
    "direction": "outbound",
    "sender_handle": {
      "handle": "+12025551234",
      "id": "6d6c617f-187a-4dcd-a0d5-988347a8c092",
      "is_me": true,
      "joined_at": "2026-01-04T05:48:51.321469Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "part": {
      "index": 0,
      "text": "This is the edited message content"
    },
    "edited_at": "2026-03-05T02:12:46.487Z"
  }
}
```

## Reaction events

| Event              | Description                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `reaction.added`   | Reaction (tapback) added to a message — see [Reactions](/channel/imessage/guides/messaging/reactions/index.md) |
| `reaction.removed` | Reaction removed from a message — see [Reactions](/channel/imessage/guides/messaging/reactions/index.md)       |

Both events share the `ReactionEventBase` shape and are identical across versions. The `reaction_type` field indicates the kind of reaction:

- **Tapback** — one of `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`
- **Custom emoji** — `reaction_type: "custom"`, emoji in `custom_emoji`
- **Sticker** — `reaction_type: "sticker"`, details in a `sticker` object — see [Sticker attachments](/channel/imessage/guides/messaging/reactions#sticker-attachments/index.md)

### `reaction.added`

A standard tapback (`love`) added to a message part.

- [2026-02-03](#tab-panel-6-0)
- [2025-01-01](#tab-panel-6-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "reaction.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2025-11-23T17:35:00.000Z",
    "sticker": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "reaction.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2025-11-23T17:35:00.000Z",
    "sticker": null
  }
}
```

### `reaction.removed`

Same shape as `reaction.added` — `reacted_at` is when the reaction was taken off.

- [2026-02-03](#tab-panel-7-0)
- [2025-01-01](#tab-panel-7-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "reaction.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2025-11-23T17:35:00.000Z",
    "sticker": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "reaction.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2025-11-23T17:35:00.000Z",
    "sticker": null
  }
}
```

## Poll events

| Event                 | Description                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `poll.received`       | A participant sent a poll to your line — see [Polls](/channel/imessage/guides/messaging/polls/index.md) |
| `poll.sent`           | A poll you created left the device                                                                      |
| `poll.delivered`      | That poll reached the recipient                                                                         |
| `poll.read`           | The recipient read it                                                                                   |
| `poll.updated`        | Options were added to an existing poll                                                                  |
| `poll.failed`         | An outbound poll or poll action failed to send                                                          |
| `poll.vote.added`     | A participant voted for an option                                                                       |
| `poll.vote.removed`   | A participant took a vote back                                                                          |
| `poll.reaction.added` | Someone reacted to the poll message                                                                     |

Poll events are delivered to `2026-02-03` subscriptions. Throughout, `message_id` is the poll-definition message — the same id you pass to the poll endpoints. `poll.sent`, `poll.delivered`, and `poll.read` share one shape whose timestamps fill in as the poll progresses (`null` means not yet).

### `poll.received`

A participant sent your line a poll. Carries the full snapshot at receipt time — options present, no voters yet.

- [2026-02-03](#tab-panel-8-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.received",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "inbound",
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": {
        "id": "550e8400-e29b-41d4-a716-446655440092",
        "handle": "+12025551234",
        "is_me": true,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2026-07-01T05:48:51.321Z",
        "left_at": null
      }
    },
    "sender_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T17:30:00.000Z",
      "left_at": null
    },
    "created_at": "2026-07-08T17:35:00.000Z",
    "updated_at": "2026-07-08T17:35:00.000Z",
    "poll": {
      "options": [
        {
          "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
          "text": "Tacos",
          "can_be_edited": true,
          "creator_handle": {
            "id": "550e8400-e29b-41d4-a716-446655440011",
            "handle": "+14155559876",
            "is_me": false,
            "service": "iMessage",
            "status": "active",
            "joined_at": "2026-07-01T17:30:00.000Z",
            "left_at": null
          },
          "voters": []
        },
        {
          "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3302",
          "text": "Sushi",
          "can_be_edited": true,
          "creator_handle": null,
          "voters": []
        }
      ],
      "total_voters": 0
    },
    "service": "iMessage",
    "received_at": "2026-07-08T17:35:00.000Z"
  }
}
```

### `poll.sent`

A poll your line created left the device. `delivered_at` and `read_at` are `null` until the matching events fire.

- [2026-02-03](#tab-panel-9-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.sent",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "outbound",
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": null
    },
    "sender_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440092",
      "handle": "+12025551234",
      "is_me": true,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T05:48:51.321Z",
      "left_at": null
    },
    "created_at": "2026-07-08T17:35:00.000Z",
    "updated_at": "2026-07-08T17:35:00.000Z",
    "poll": {
      "options": [
        {
          "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
          "text": "Tacos",
          "can_be_edited": true,
          "creator_handle": null,
          "voters": []
        }
      ],
      "total_voters": 0
    },
    "service": "iMessage",
    "sent_at": "2026-07-08T17:35:00.000Z",
    "delivered_at": null,
    "read_at": null
  }
}
```

### `poll.delivered`

Same shape as `poll.sent`, with `delivered_at` populated.

- [2026-02-03](#tab-panel-10-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.delivered",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:35:02.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "outbound",
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": null
    },
    "sender_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440092",
      "handle": "+12025551234",
      "is_me": true,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T05:48:51.321Z",
      "left_at": null
    },
    "created_at": "2026-07-08T17:35:00.000Z",
    "updated_at": "2026-07-08T17:35:02.000Z",
    "poll": {
      "options": [
        {
          "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
          "text": "Tacos",
          "can_be_edited": true,
          "creator_handle": null,
          "voters": []
        }
      ],
      "total_voters": 0
    },
    "service": "iMessage",
    "sent_at": "2026-07-08T17:35:00.000Z",
    "delivered_at": "2026-07-08T17:35:02.000Z",
    "read_at": null
  }
}
```

### `poll.read`

The recipient read the poll. Requires read receipts on their side, and is not available in group chats.

- [2026-02-03](#tab-panel-11-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.read",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:36:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "outbound",
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": null
    },
    "sender_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440092",
      "handle": "+12025551234",
      "is_me": true,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T05:48:51.321Z",
      "left_at": null
    },
    "created_at": "2026-07-08T17:35:00.000Z",
    "updated_at": "2026-07-08T17:36:00.000Z",
    "poll": {
      "options": [
        {
          "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
          "text": "Tacos",
          "can_be_edited": true,
          "creator_handle": null,
          "voters": []
        }
      ],
      "total_voters": 0
    },
    "service": "iMessage",
    "sent_at": "2026-07-08T17:35:00.000Z",
    "delivered_at": "2026-07-08T17:35:02.000Z",
    "read_at": "2026-07-08T17:36:00.000Z"
  }
}
```

### `poll.updated`

Options were added. `added_options` carries only the new ones — fetch [`GET /v3/messages/{messageId}/poll`](/channel/imessage/guides/messaging/polls#read-the-tally/index.md) for the full poll.

- [2026-02-03](#tab-panel-12-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:40:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "inbound",
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": null
    },
    "sender_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T17:30:00.000Z",
      "left_at": null
    },
    "added_options": [
      {
        "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3303",
        "text": "Pizza",
        "can_be_edited": true,
        "creator_handle": {
          "id": "550e8400-e29b-41d4-a716-446655440011",
          "handle": "+14155559876",
          "is_me": false,
          "service": "iMessage",
          "status": "active",
          "joined_at": "2026-07-01T17:30:00.000Z",
          "left_at": null
        },
        "voters": []
      }
    ],
    "service": "iMessage"
  }
}
```

### `poll.failed`

An outbound poll or poll action failed to send. `sender_handle` is `null` because the send never landed. Error codes match [`message.failed`](#message-events).

- [2026-02-03](#tab-panel-13-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:35:05.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "outbound",
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": null
    },
    "sender_handle": null,
    "poll": {
      "options": [
        {
          "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
          "text": "Tacos",
          "can_be_edited": true,
          "creator_handle": null,
          "voters": []
        }
      ],
      "total_voters": 0
    },
    "service": "iMessage",
    "error": {
      "code": 4001,
      "message": "Message send failed"
    },
    "failed_at": "2026-07-08T17:35:05.000Z"
  }
}
```

### `poll.vote.added`

A participant voted for one option. Votes toggle per option, so a voter picking three options produces three events.

- [2026-02-03](#tab-panel-14-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.vote.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:38:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "inbound",
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": null
    },
    "sender_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T17:30:00.000Z",
      "left_at": null
    },
    "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
    "service": "iMessage"
  }
}
```

### `poll.vote.removed`

A participant took a vote back. Identical shape to `poll.vote.added`.

- [2026-02-03](#tab-panel-15-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.vote.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:39:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "inbound",
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": null
    },
    "sender_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T17:30:00.000Z",
      "left_at": null
    },
    "option_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
    "service": "iMessage"
  }
}
```

### `poll.reaction.added`

Someone reacted to the poll message. Same shape as [`reaction.added`](#reaction-events), with `message_id` pointing at the poll-definition message. Poll reactions are stickers, which cannot be removed, so there is no removal counterpart.

- [2026-02-03](#tab-panel-16-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "poll.reaction.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-08T17:41:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2026-07-08T17:41:00.000Z",
    "sticker": null
  }
}
```

## Chat events

| Event                           | Description                                                                                                                       |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `chat.created`                  | New chat created — fires for DMs and group chats                                                                                  |
| `chat.group_name_updated`       | Group chat display name changed                                                                                                   |
| `chat.group_icon_updated`       | Group chat icon changed                                                                                                           |
| `chat.group_name_update_failed` | Group name update failed                                                                                                          |
| `chat.group_icon_update_failed` | Group icon update failed                                                                                                          |
| `chat.background_updated`       | Chat transcript background set, changed, or removed — see [Chat Backgrounds](/channel/imessage/guides/chats/backgrounds/index.md) |
| `chat.background_update_failed` | Background set or removal failed                                                                                                  |
| `chat.typing_indicator.started` | Participant started typing — see [Typing Indicators](/channel/imessage/guides/chats/typing-indicators/index.md)                   |
| `chat.typing_indicator.stopped` | Participant stopped typing — see [Typing Indicators](/channel/imessage/guides/chats/typing-indicators/index.md)                   |

Chat-level events use a consistent shape across versions.

### `chat.created`

The `data` block mirrors the `GET /v3/chats/{chatId}` response. In `2026-02-03` payloads, `health_status` is included — see [Chat Health](/channel/imessage/guides/chats/chat-health/index.md).

- [2026-02-03](#tab-panel-17-0)
- [2025-01-01](#tab-panel-17-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.created",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "display_name": "+14155551234, +14155559876",
    "service": "iMessage",
    "handles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "handle": "+14155551234",
        "is_me": true,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-11-23T17:30:00.000Z",
        "left_at": null
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440011",
        "handle": "+14155559876",
        "is_me": false,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-11-23T17:30:00.000Z",
        "left_at": null
      }
    ],
    "is_group": false,
    "created_at": "2025-11-23T17:30:00.000Z",
    "updated_at": "2025-11-23T17:30:00.000Z",
    "health_status": {
      "status": "HEALTHY",
      "doc_url": "https://docs.linqapp.com/channel/imessage/guides/chats/chat-health#healthy",
      "updated_at": "2025-11-23T17:30:00.000Z"
    }
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.created",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "display_name": "+14155551234, +14155559876",
    "service": "iMessage",
    "handles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "handle": "+14155551234",
        "is_me": true,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-11-23T17:30:00.000Z",
        "left_at": null
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440011",
        "handle": "+14155559876",
        "is_me": false,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-11-23T17:30:00.000Z",
        "left_at": null
      }
    ],
    "is_group": false,
    "created_at": "2025-11-23T17:30:00.000Z",
    "updated_at": "2025-11-23T17:30:00.000Z"
  }
}
```

### `chat.group_name_updated`

`new_value` is `null` when the name was removed; `old_value` is `null` when no previous name existed.

- [2026-02-03](#tab-panel-18-0)
- [2025-01-01](#tab-panel-18-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.group_name_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "old_value": "Old Group Name",
    "new_value": "New Group Name",
    "changed_by_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "updated_at": "2025-11-23T17:50:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.group_name_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "old_value": "Old Group Name",
    "new_value": "New Group Name",
    "changed_by_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "updated_at": "2025-11-23T17:50:00.000Z"
  }
}
```

### `chat.group_icon_updated`

Same shape as `chat.group_name_updated`; `old_value` and `new_value` are image URLs (null when absent).

- [2026-02-03](#tab-panel-19-0)
- [2025-01-01](#tab-panel-19-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.group_icon_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "old_value": "https://example.com/old-icon.png",
    "new_value": "https://example.com/new-icon.png",
    "changed_by_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "updated_at": "2025-11-23T17:50:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.group_icon_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "old_value": "https://example.com/old-icon.png",
    "new_value": "https://example.com/new-icon.png",
    "changed_by_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "updated_at": "2025-11-23T17:50:00.000Z"
  }
}
```

### `chat.group_name_update_failed`

Fires when a `PUT /v3/chats/{chatId}` request to change the display name couldn’t be applied. `error_code` follows the standard [error code](/channel/imessage/error/index.md) list.

- [2026-02-03](#tab-panel-20-0)
- [2025-01-01](#tab-panel-20-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.group_name_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 3007,
    "failed_at": "2025-11-23T17:55:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.group_name_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 3007,
    "failed_at": "2025-11-23T17:55:00.000Z"
  }
}
```

### `chat.group_icon_update_failed`

Identical shape to `chat.group_name_update_failed`, fired when the group icon update couldn’t be applied.

- [2026-02-03](#tab-panel-21-0)
- [2025-01-01](#tab-panel-21-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.group_icon_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 3007,
    "failed_at": "2025-11-23T17:55:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.group_icon_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 3007,
    "failed_at": "2025-11-23T17:55:00.000Z"
  }
}
```

### `chat.background_updated`

A chat’s transcript background was set, changed, or removed — see [Chat Backgrounds](/channel/imessage/guides/chats/backgrounds/index.md). `background` is `null` on removal. `actor_handle.is_me` distinguishes your own change from a participant’s, so a subscription sees both directions.

- [2026-02-03](#tab-panel-22-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.background_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-14T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_group": false,
      "owner_handle": {
        "id": "550e8400-e29b-41d4-a716-446655440092",
        "handle": "+12025551234",
        "is_me": true,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2026-07-01T05:48:51.321Z",
        "left_at": null
      }
    },
    "background": { "type": "dynamic", "style": "water", "variant": "dark" },
    "actor_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-07-01T17:30:00.000Z",
      "left_at": null
    }
  }
}
```

### `chat.background_update_failed`

The terminal failure counterpart of `chat.background_updated`, fired when setting or removing a background couldn’t be applied. `error_code` follows the standard [error code](/channel/imessage/error/index.md) list. An accepted request normally ends in one of the two, but a command that exhausts its internal retries emits neither — time out rather than wait indefinitely.

- [2026-02-03](#tab-panel-23-0)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.background_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-07-30T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 4001,
    "failed_at": "2026-07-30T17:35:00.000Z"
  }
}
```

### `chat.typing_indicator.started`

Fires when a participant starts typing, in one-to-one and group chats alike — see [Typing Indicators](/channel/imessage/guides/chats/typing-indicators/index.md). The payload identifies the chat, not the participant, so in a group it tells you someone is typing but not who.

- [2026-02-03](#tab-panel-24-0)
- [2025-01-01](#tab-panel-24-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.typing_indicator.started",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.typing_indicator.started",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### `chat.typing_indicator.stopped`

Counterpart to `chat.typing_indicator.started`. Also fires automatically when the participant sends the message they were typing.

- [2026-02-03](#tab-panel-25-0)
- [2025-01-01](#tab-panel-25-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.typing_indicator.stopped",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.typing_indicator.stopped",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## Participant events

| Event                 | Description                           |
| --------------------- | ------------------------------------- |
| `participant.added`   | Participant added to a group chat     |
| `participant.removed` | Participant removed from a group chat |

Participant events share the same shape across versions.

### `participant.added`

Fires when a new participant joins a group chat.

- [2026-02-03](#tab-panel-26-0)
- [2025-01-01](#tab-panel-26-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "participant.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "handle": "+14155559876",
    "participant": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:40:00.000Z",
      "left_at": null
    },
    "added_at": "2025-11-23T17:40:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "participant.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "handle": "+14155559876",
    "participant": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:40:00.000Z",
      "left_at": null
    },
    "added_at": "2025-11-23T17:40:00.000Z"
  }
}
```

### `participant.removed`

Fires when a participant leaves or is removed from a group chat. The `participant` object’s `status` is `removed` and `left_at` is set.

- [2026-02-03](#tab-panel-27-0)
- [2025-01-01](#tab-panel-27-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "participant.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "handle": "+14155559876",
    "participant": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "removed",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": "2025-11-23T17:45:00.000Z"
    },
    "removed_at": "2025-11-23T17:45:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "participant.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "handle": "+14155559876",
    "participant": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "removed",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": "2025-11-23T17:45:00.000Z"
    },
    "removed_at": "2025-11-23T17:45:00.000Z"
  }
}
```

## Phone number events

| Event                         | Description                                                                                                                                                                                                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phone_number.status_updated` | Phone number `status` (`ACTIVE` ↔ `FLAGGED`) or `reputation` (`HEALTHY` / `AT_RISK` / `CRITICAL`) changed — see [Phone Numbers](/channel/imessage/guides/phone-numbers/index.md) and [Phone Reputation](/channel/imessage/guides/phone-numbers/phone-reputation/index.md) |

### `phone_number.status_updated`

Fires when a phone number’s service `status` (`ACTIVE` ↔ `FLAGGED`) or `reputation` (`HEALTHY` / `AT_RISK` / `CRITICAL`) changes. Every payload carries both pairs of fields, so you can react to either signal from the same event.

- [2026-02-03](#tab-panel-28-0)
- [2025-01-01](#tab-panel-28-1)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "phone_number.status_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-02-18T18:35:05.363Z",
  "trace_id": "b66e67c5c6b2c20e41d53c51698db27a",
  "partner_id": "your-partner-id",
  "data": {
    "phone_number": "+12025551234",
    "previous_status": "ACTIVE",
    "new_status": "FLAGGED",
    "previous_reputation": "AT_RISK",
    "new_reputation": "CRITICAL",
    "changed_at": "2026-02-18T18:35:05.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "phone_number.status_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-02-18T18:35:05.363Z",
  "trace_id": "b66e67c5c6b2c20e41d53c51698db27a",
  "partner_id": "your-partner-id",
  "data": {
    "phone_number": "+12025551234",
    "previous_status": "ACTIVE",
    "new_status": "FLAGGED",
    "previous_reputation": "AT_RISK",
    "new_reputation": "CRITICAL",
    "changed_at": "2026-02-18T18:35:05.000Z"
  }
}
```

## Location events

| Event                      | Description                                                                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `location.sharing.started` | A participant started sharing their location with you — see [Location Sharing](/channel/imessage/guides/location-sharing/index.md) |
| `location.sharing.stopped` | A participant stopped sharing their location                                                                                       |

Both payloads carry `shared_by` (their phone number — or Apple ID email if they shared from the standalone Find My app, see [Location Sharing](/channel/imessage/guides/location-sharing/index.md)), `shared_with` (your number), `began_at`, and `chat_id`. On `location.sharing.started`, `ends_at` is always present — a timestamp when the share is time-boxed, `null` when the contact shares indefinitely. On `location.sharing.stopped`, `began_at` and `ended_at` bound the session that just ended, so its duration comes from that event alone. After a `started` event, call [Read shared locations](/channel/imessage/guides/location-sharing#read-shared-locations/index.md) to pull the current coordinates. These events fire only when sharing begins or ends — there is no webhook for coordinate updates.

### `location.sharing.started`

Fires when a participant starts sharing their location with you.

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "location.sharing.started",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-02-04T12:00:00Z",
  "trace_id": "2eff5df5c6f688733c007523c4d61cd9",
  "partner_id": "your-partner-id",
  "data": {
    "shared_by": "+15551234567",
    "shared_with": "+15559876543",
    "began_at": "2026-02-04T12:00:00Z",
    "ends_at": "2026-02-04T13:00:00Z",
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### `location.sharing.stopped`

Fires when a participant stops sharing their location.

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "location.sharing.stopped",
  "event_id": "660f9500-f30c-52e5-b827-557766551111",
  "created_at": "2026-02-04T18:45:00Z",
  "trace_id": "3bff6ef6d7g799844d118634d5e72de0",
  "partner_id": "your-partner-id",
  "data": {
    "shared_by": "+15551234567",
    "shared_with": "+15559876543",
    "began_at": "2026-02-04T12:00:00Z",
    "ended_at": "2026-02-04T18:45:00Z",
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## Related

- [Webhooks](/channel/imessage/guides/webhooks/index.md) — setup, signature verification, delivery guarantees
- [Webhook Subscriptions](/channel/imessage/guides/webhooks/subscriptions/index.md) — manage which events each subscription receives
- [API Reference: Webhook Events](/channel/imessage/api/resources/webhooks/index.md) — complete payload schemas for every event type