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

# Changelog

> Changes to the iBubbl API and these docs, newest first.

**Type** says what changed: **New** is a new API capability, **Changed** is a change in how the API behaves, **Correction** means the docs were wrong and now match the API, and **Docs** is new or reorganised documentation with no API change.

| Date | Change | Type |
| - | - | - |
| 2026-11-11 | New endpoints for the things a person does in a conversation: [Add a tapback](https://docs.ibubbl.com/api-reference/messages/react.md) and [Remove a tapback](https://docs.ibubbl.com/api-reference/messages/remove-reaction.md) (`POST` / `DELETE /v1/messages/{id}/reactions`, the six iMessage tapbacks, one per message), [Mark a conversation read](https://docs.ibubbl.com/api-reference/conversations/mark-read.md) (sends a read receipt), and [Start](https://docs.ibubbl.com/api-reference/conversations/start-typing.md) / [Stop typing](https://docs.ibubbl.com/api-reference/conversations/stop-typing.md) (the typing dots, 10 seconds per call). New errors `invalid_target`, `sms_not_supported`, `target_unsent`, `target_partly_unsent` and `503 opt_out_check_unavailable`. New guide: [Tapbacks, read receipts and typing](https://docs.ibubbl.com/guides/reactions-read-receipts-typing.md), including typing while your AI writes a reply. | New |
| 2026-11-11 | New webhook event [`message.reaction.failed`](https://docs.ibubbl.com/webhooks/events#message-reaction-failed): a tapback you sent, or its removal, couldn't be sent, with `action` and `failed_reason`. A subscription without an `event_types` filter receives it. | New |
| 2026-11-11 | Every `message.*` and `message.reaction.*` webhook now carries `conversation_id`, the ID the new read and typing endpoints take. See [The `conversation_id` field](https://docs.ibubbl.com/webhooks/events#the-conversation_id-field). | New |
| 2026-11-11 | The tapback, read and typing endpoints have their own rate limit: 300 requests per 60 seconds per account, separate from the 120 for lists, with `429 rate_limited` and `Retry-After` over it. See [Rate limits](https://docs.ibubbl.com/concepts/limits.md#rate-limits). | New |
| 2026-11-11 | Marking a group conversation read, in the dashboard, no longer sends a read receipt. It used to land in one participant's one-to-one chat instead of the group. | Changed |
| 2026-11-11 | New endpoints complete the contacts API: [List contacts](https://docs.ibubbl.com/api-reference/contacts/list.md) (`GET /v1/contacts`, paginated like [List messages](https://docs.ibubbl.com/api-reference/messages/list.md), with `search`, `tag`, `opted_out` and `blocked` filters), [Delete a contact](https://docs.ibubbl.com/api-reference/contacts/delete.md) (`204`), [Opt a contact out](https://docs.ibubbl.com/api-reference/contacts/opt-out.md) (permanent; fires `contact.opted_out` with `source: "api"`), and [Block](https://docs.ibubbl.com/api-reference/contacts/block.md) / [Unblock](https://docs.ibubbl.com/api-reference/contacts/unblock.md) a contact. Every contact now has `blocked` and `blocked_at`. See [Block or opt out](https://docs.ibubbl.com/concepts/suppression.md#block-or-opt-out). | New |
| 2026-11-11 | [Send a message](https://docs.ibubbl.com/api-reference/messages/send.md) with the `contact_id` of a deleted contact now returns `404 not_found`; before, it sent. A new contact for a number that opted out earlier (for example after deleting the old contact) now starts with `opted_out: true`; before, it showed `false` while its sends were already refused. | Changed |
| 2026-11-11 | Send files: [`POST /v1/messages`](https://docs.ibubbl.com/api-reference/messages/send) takes `attachments`, up to 10 `https` URLs of photos, GIFs, videos, PDFs or audio, for one-to-one sends (not with `effect` or `reply_to_message_id`). iBubbl downloads them when the request arrives; `body` becomes optional and is the caption, but the first message to a contact still needs one. New errors: `attachment_fetch_failed`, `attachment_too_large`, `unsupported_attachment`, `attachment_combination_not_supported` and `first_message_needs_text`. The URLs are part of the idempotency payload. See [Send attachments](https://docs.ibubbl.com/guides/attachments.md). | New |
| 2026-11-11 | Every message object ([Send](https://docs.ibubbl.com/api-reference/messages/send.md), [Retrieve](https://docs.ibubbl.com/api-reference/messages/retrieve.md), [List](https://docs.ibubbl.com/api-reference/messages/list.md)) now has `attachments`: the files it carries, sent or received, as `kind`, `mime_type` and `size_bytes`; `[]` when there are none. | New |
| 2026-11-11 | A send with `attachments` can get `429 rate_limited` with `Retry-After: 5` when iBubbl is already downloading as many attachment sends as it can. Text sends are still never rate limited. See [Rate limits](https://docs.ibubbl.com/concepts/limits.md#rate-limits). | Changed |
| 2026-11-11 | List endpoints are rate limited: 120 requests per 60 seconds per account, shared by all your API keys and all lists. Over that, [List messages](https://docs.ibubbl.com/api-reference/messages/list.md) answers `429 rate_limited` with a `Retry-After` header in seconds. Wait that long and send the same request again; the [pagination loops](https://docs.ibubbl.com/concepts/pagination.md#read-every-page) now do this. Sends are still never rate limited. See [Rate limits](https://docs.ibubbl.com/concepts/limits.md#rate-limits). | Changed |
| 2026-11-11 | New endpoint: [List messages](https://docs.ibubbl.com/api-reference/messages/list.md) (`GET /v1/messages`) returns your inbound and outbound messages, newest first, with filters for contact, conversation, group, direction, status and creation time. Results are paginated with `starting_after` and `has_more`; see [Pagination](https://docs.ibubbl.com/concepts/pagination.md). New error `invalid_cursor`. New recipe: [Recover from downtime](https://docs.ibubbl.com/guides/webhook-retries.md#recover-from-downtime) after missed webhooks. | New |
| 2026-11-11 | Every message object ([Send](https://docs.ibubbl.com/api-reference/messages/send.md), [Retrieve](https://docs.ibubbl.com/api-reference/messages/retrieve.md), [List](https://docs.ibubbl.com/api-reference/messages/list.md)) now has `direction` (`inbound` or `outbound`) and `created_at` (when iBubbl recorded it, UTC with microseconds). | New |
| 2026-11-11 | Webhooks now carry `channel` (`imessage` or `sms`): `message.sent`, `message.delivered`, `message.read`, `message.failed`, `message.cancelled` and `message.inbound`. [Retrieve a message](https://docs.ibubbl.com/api-reference/messages/retrieve.md) now returns `channel` for inbound messages too, where it was always `null`. See [The `channel` field](https://docs.ibubbl.com/webhooks/events#the-channel-field). | New |
| 2026-11-11 | A `queued` message that expires now fires [`message.failed`](https://docs.ibubbl.com/webhooks/events#message-failed), with `status: "expired"` and `failed_reason: "queue_expired"`; before, it fired no webhook. A queued message the queue's retry fails also fires `message.failed` now. | Changed |
| 2026-11-11 | Every API response carries an `X-Request-Id` header, and a request can send its own. Quote it to support instead of a timestamp and request body. See [Request IDs](https://docs.ibubbl.com/errors.md#request-ids). | New |
| 2026-11-10 | [Send a message](https://docs.ibubbl.com/api-reference/messages/send.md) takes two optional fields: `reply_to_message_id`, to send an inline reply that quotes an earlier message in the same conversation, and `effect`, one of 13 iMessage effects. Both are iMessage only, not allowed when creating a group, and echoed in the response. New errors `reply_target_not_found`, `reply_target_unsent` and `reply_target_partly_unsent`. See [Reply and send with effects](https://docs.ibubbl.com/guides/send-messages.md#reply-to-a-message-and-send-with-effects). | New |
| 2026-11-10 | API keys work only on `/v1` endpoints. The dashboard's internal send and retry routes no longer accept an API key; they answer `401 invalid_token`. Nothing documented changed. | Changed |
| 2026-11-10 | Every [API reference](https://docs.ibubbl.com/api-reference/messages/send.md) page now has cURL, TypeScript and Python examples, with a success and an error response beside them, and the guides, concepts and [Quickstart](https://docs.ibubbl.com/quickstart.md) share one sample style: the key from `IBUBBL_API_KEY`, a 10-second timeout, a new `idempotency_key` per send, and `detail.error` read on failure. New page: [OpenAPI, Postman and Insomnia](https://docs.ibubbl.com/openapi.md). The send example now shows `sent_at` set on acceptance. | Docs |
| 2026-11-10 | New guides: [Send messages](https://docs.ibubbl.com/guides/send-messages.md), [Receive messages](https://docs.ibubbl.com/guides/receive-messages.md) (with an auto-reply that can't loop), [Test webhooks locally](https://docs.ibubbl.com/guides/test-webhooks-locally.md) and [Retries and deduplication](https://docs.ibubbl.com/guides/webhook-retries.md). [Signature verification](https://docs.ibubbl.com/guides/webhook-signatures.md) moved to Guides (the old `/webhooks/signatures` URL redirects) and now has a test vector, the header-case rules and raw-body wiring for Express, FastAPI and Next.js. Each retried delivery is signed with a new timestamp. | Docs |
| 2026-11-10 | New concept pages: [Message lifecycle](https://docs.ibubbl.com/concepts/message-lifecycle.md) (every status, which are final, which webhook fires, and how duplicates and retries behave), [Limits and queues](https://docs.ibubbl.com/concepts/limits.md) (the exact per-line limits, rate limits and pacing) and [Lines and routing](https://docs.ibubbl.com/concepts/lines-and-routing.md) (which line sends, and iMessage versus SMS). The [Build with AI](https://docs.ibubbl.com/build-with-ai.md) system prompt now includes the limits. | Docs |
| 2026-11-10 | `cold_cap_exhausted` means 50 new contacts per line per day, and `daily_cap_exhausted` means 1,000 messages per line per day; there is no warm-up ramp. `hourly_cap_hit` and `followup_cap_exhausted` are legacy codes no current line returns. A `cancelled` message does not release its `idempotency_key`. Two simultaneous requests with one key can return `500` for one of them. | Correction |
| 2026-11-10 | The docs are reorganised into Get started, Concepts, Guides, Webhooks, API reference and Resources. New pages: [Quickstart](https://docs.ibubbl.com/quickstart.md), [Build with AI](https://docs.ibubbl.com/build-with-ai.md) (with a system prompt for coding agents), [Support](https://docs.ibubbl.com/support.md) and this changelog. No page moved, so existing links keep working. | Docs |
| 2026-11-10 | The [error catalog](https://docs.ibubbl.com/errors.md) now lists every code `/v1` returns, including `contact_blocked`, `no_eligible_line`, `unresponsive_contact`, `group_not_found` and `rate_limited`. Removed the `503` entries, which iBubbl never returns. Also corrected: a queued message that expires fires no webhook; `held_reason` can be `hourly_limit`; the unanswered limit is 6 in a row. | Correction |
| 2026-11-10 | The API is at `https://api.ibubbl.com` and these docs at `https://docs.ibubbl.com`. The previous hosts keep working. | Changed |
| 2026-11-05 | Contacts: create and upsert take `email`, `city`, `state` and `tags`; new endpoints to [update a contact](https://docs.ibubbl.com/api-reference/contacts/update.md), [add a tag](https://docs.ibubbl.com/api-reference/contacts/add-tag.md) and [remove a tag](https://docs.ibubbl.com/api-reference/contacts/remove-tag.md). The contacts endpoints now reject unknown body fields with `422 validation_error`. | New |
| 2026-11-05 | A busy calendar no longer holds sends. `held_reason` is `working_hours` or `hourly_limit`. | Changed |
| 2026-11-05 | Every API reference page now shows each status code it can return, with a real example. `403 forbidden` means a suspended or cancelled account; `500 no_owner_rep` is documented. | Docs |
| 2026-11-05 | New page: [After-hours auto-reply](https://docs.ibubbl.com/concepts/after-hours-reply.md). | Docs |
| 2026-11-04 | Line breaks in a message `body`: send `\n`, not `\r\n`. A retry with the same `idempotency_key` must send the identical body. | Changed |
| 2026-10-23 | Daily send caps reset at midnight ET (America/New\_York). | Changed |
| 2026-10-20 | The webhook catalog is complete: `message.delivered` and `message.read`, ordering and duplicates, inbound attachments. The reference signature verifiers no longer crash on a missing or malformed header. | Correction |
| 2026-10-20 | API keys are `ib_pk_` plus 64 hex characters. Idempotency keys never expire, and a key whose message failed or expired is released for a new send. There is no test mode. | Correction |
| 2026-10-20 | Group conversations: get `chat_guid` from [Retrieve a message](https://docs.ibubbl.com/api-reference/messages/retrieve.md); it changes when someone is added to the group. | Correction |
| 2026-10-20 | Corrections to suppression, contact timezones, inbound events and versioning. New enum values are not breaking changes. | Correction |
| 2026-10-16 | A message that failed with an `imessage_*` reason can move to `delivered` or `read` if Apple later confirms it. | Changed |
| 2026-10-15 | `message.failed` can follow `message.sent`. New `failed_reason` values `imessage_undeliverable` and `imessage_error:<code>`. | New |
| 2026-10-13 | New `cancelled` status and `message.cancelled` event, for a waiting message that is cancelled before it is sent. | New |
| 2026-10-08 | Waiting messages carry `held_until` and `held_reason`. New default sending hours: Monday to Saturday 9 AM–8 PM, Sunday 12–8 PM. A message waiting for sending hours is `pending`, not `queued`. | New |
| 2026-10-06 | `failed_reason: mac_send_failed` also covers a send not confirmed within 10 minutes. | Changed |
| 2026-10-05 | A contact's phone number is stored in the form it was first seen. | Correction |
| 2026-10-03 | New `failed_reason` value `line_inactive`. | New |
| 2026-10-01 | [Inbound events](https://docs.ibubbl.com/inbound-events/overview.md) from any app through a secret URL, iBubbl-signed sources, and a log of recent events. | New |
| 2026-09-22 | [Inbound events](https://docs.ibubbl.com/inbound-events/overview.md): `POST /v1/events/{token}` lets a connected app, such as Recharge, start an iBubbl workflow. | New |
| 2026-09-22 | The OpenAPI spec now includes the group-send fields. | Correction |
| 2026-05-31 | [Group conversations](https://docs.ibubbl.com/concepts/group-conversations.md): send into an existing group with `chat_guid`, or start one with `participant_phones`. | New |
| 2026-05-29 | Webhook signatures use `X-iBubbl-Signature: t=<unix>,v1=<hex>`, with a 5-minute replay window. | Changed |
| 2026-05-17 | First public API docs: messages, contacts and webhooks. | New |


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