> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blujay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions

> Webhook payloads are versioned by date, so new fields never surprise an existing receiver.

Each subscription is pinned to a payload version with `webhook_version`. Blujay renders every event for that subscription in that version's shape, so your receiver keeps working when new versions ship. New subscriptions use the latest version unless you choose another.

## Versions

| Version | Adds |
| - | - |
| `2026-10-03` (latest, default) | `reply_to` on every message event, and typing events for iMessage group chats with a `participants` list. Group typing is sent only for your Dedicated numbers (`access_type: "dedicated"`); earlier versions never receive it. Otherwise the same as `2026-09-02`. |
| `2026-09-02` | `parts` on message events, including media with `attachment_id` and download details, and the media `failure_code` values on failed messages (`SENDER_RETIRED` is reported on every version). |
| `2026-08-20` | `requested_service` reports the service you asked for, and `service` reports only the service that was confirmed to carry the message. |
| `2026-08-01` | Full message details: `direction`, services, `sent_at`, `delivered_at`, `read_at`, `failed_at`, `failure` and `degradations`. |
| `2026-06-14` | The original minimal message payload. |

### The 2026-06-14 shape

On `2026-06-14`, a message event's `data` has four fields: `message_id`, `chat_id`, `phone_number_id` and `status`. A `message.failed` event adds `failure_code` only when your number was retired (`SENDER_RETIRED`); other failures have no reason. A `message.received` event adds `contact_id` (or `sender` in a group), `text`, and a `parts` list that holds the text only, never media. There is no `direction`, no service, no timestamps and no `failure` object. Reaction, typing, group, contact and phone number events have the same shape on every version. If you inherit a subscription on this version, read the message with `GET /v1/messages/{message_id}` for everything the event leaves out, or upgrade it.

Use the latest version for new integrations. Older versions remain supported for existing receivers. There is no sunset policy yet: Blujay will announce one, with notice, before retiring any version.

## Upgrade a subscription

1. Update your receiver to accept the new fields, and keep it accepting the old shape for a while: events created before the change keep their original shape, including when they are delivered again.

2. Change the version:

   ```bash theme={null}
   curl -X PATCH https://api.blujay.io/v1/webhook-subscriptions/whsub_abc123 \
     -H "Authorization: Bearer blu_your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"webhook_version": "2026-10-03"}'
   ```

3. New events use the new version from then on.

Every event says which version it uses in its `webhook_version` field, so your receiver can handle both shapes during the switch. A version string outside the table is rejected with `400` [`VALIDATION_ERROR`](/errors/validation-error).

## Limitations

* A version applies to the whole subscription. You can't pick a version per event type.
* An event keeps the version it was created with. Changing the version never re-renders events that already exist, including on replay.
* Group typing needs `2026-10-03` and a Dedicated number. No version adds group typing for Free Plan numbers; see [Plans](/plans.md).

## Next steps

> **[Events](/webhooks/events.md)**
>
> Every event type and its payload.

> **[Making requests](/making-requests.md#versioning)**
>
> What Blujay can and can't change within v1.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.