# iBubbl

- [Overview](https://docs.ibubbl.com/introduction.md): Send iMessages from your own iBubbl line and get the replies on your server.
- [Quickstart](https://docs.ibubbl.com/quickstart.md): Create a key, send an iMessage to your own phone, check its status and receive the reply.
- [Authentication](https://docs.ibubbl.com/authentication.md): Authenticate every request with a Bearer API key.
- [Build with AI](https://docs.ibubbl.com/build-with-ai.md): Give your coding agent the iBubbl docs, the OpenAPI spec and a system prompt with the rules that matter.
- [Message lifecycle](https://docs.ibubbl.com/concepts/message-lifecycle.md): Every status an outbound message can have, which ones are final, which webhook fires for each, and how duplicates and retries behave.
- [Limits and queues](https://docs.ibubbl.com/concepts/limits.md): The exact send limits on every iBubbl line, what happens when you reach them, and how fast a line can send.
- [Lines and routing](https://docs.ibubbl.com/concepts/lines-and-routing.md): Which of your lines sends to a contact, and how iBubbl decides between iMessage and SMS.
- [Idempotency](https://docs.ibubbl.com/idempotency.md): Make sends retry-safe with idempotency keys.
- [Pagination](https://docs.ibubbl.com/concepts/pagination.md): How list endpoints page through results: newest first, a starting_after cursor, has_more, and the rules every list follows.
- [Working Hours & Scheduling](https://docs.ibubbl.com/concepts/working-hours.md): How iBubbl respects working hours for outbound sends.
- [After-Hours Auto-Reply](https://docs.ibubbl.com/concepts/after-hours-reply.md): Answer texts that arrive while you are closed, automatically.
- [Suppression & Opt-Outs](https://docs.ibubbl.com/concepts/suppression.md): How iBubbl handles opt-outs to keep you TCPA-compliant.
- [Group Conversations](https://docs.ibubbl.com/concepts/group-conversations.md): How iBubbl represents and routes iMessage group conversations.
- [Send messages](https://docs.ibubbl.com/guides/send-messages.md): Send to a phone number, a saved contact, an existing group or a new group, then track what happened.
- [Send attachments](https://docs.ibubbl.com/guides/attachments.md): Send photos, videos, PDFs and audio by URL, with an optional caption.
- [Tapbacks, Read Receipts & Typing Indicators](https://docs.ibubbl.com/guides/reactions-read-receipts-typing.md): React to messages, send read receipts and show the typing bubble, the way a person on an iPhone would.
- [Receive messages](https://docs.ibubbl.com/guides/receive-messages.md): Handle replies, group messages, attachments and opt-outs, and build an auto-reply that cannot loop.
- [Signature verification](https://docs.ibubbl.com/guides/webhook-signatures.md): Verify that a webhook came from iBubbl: HMAC-SHA256 over the timestamp and raw body, with reference verifiers, framework wiring and a test vector.
- [Test webhooks locally](https://docs.ibubbl.com/guides/test-webhooks-locally.md): Receive real iBubbl events on your laptop through a tunnel, and watch every delivery in the dashboard.
- [Retries and deduplication](https://docs.ibubbl.com/guides/webhook-retries.md): When iBubbl retries a webhook, why the same event can arrive twice or out of order, and how to de-duplicate.
- [Inbound events](https://docs.ibubbl.com/inbound-events/overview.md): Let a connected app start an iBubbl workflow.
- [Webhooks Overview](https://docs.ibubbl.com/webhooks/overview.md): Receive events on your server in real time instead of polling.
- [Webhook Events](https://docs.ibubbl.com/webhooks/events.md): Catalog of webhook event types with example payloads.
- [Send a message](https://docs.ibubbl.com/api-reference/messages/send.md): Send a message to one contact (`contact_id`, or `to` — an E.164 phone number; the contact is created on first use), into an existing group (`chat_guid`), or to a new group (`participant_phones`). Exactly one of the four is required.
- [List messages](https://docs.ibubbl.com/api-reference/messages/list.md): List your messages, inbound and outbound, newest first. Use it to catch up after your webhook endpoint was down, or to read a conversation's history.
- [Retrieve a message](https://docs.ibubbl.com/api-reference/messages/retrieve.md): Fetch a single message by its ID. Useful for polling the current delivery state when you can't subscribe to webhooks.
- [Add a tapback](https://docs.ibubbl.com/api-reference/messages/react.md): Send one of the six iMessage tapbacks (`love`, `like`, `dislike`, `laugh`, `emphasize`, `question`) on a message you received. It goes out over iMessage, or RCS for an Android contact; it can't go out by SMS.
- [Remove a tapback](https://docs.ibubbl.com/api-reference/messages/remove-reaction.md): Take back a tapback you sent. It's removed from the contact's phone, and `message.reaction.removed` fires when that happens. Only a tapback from you, on this message, can be removed.
- [Create or update a contact](https://docs.ibubbl.com/api-reference/contacts/upsert.md): Upsert a contact by E.164 phone number. Returns `201 Created` on a new contact, `200 OK` on an existing match. A number whose only match is a deleted contact creates a new contact.
- [List contacts](https://docs.ibubbl.com/api-reference/contacts/list.md): List your contacts, newest first. Deleted contacts are never listed.
- [Retrieve a contact](https://docs.ibubbl.com/api-reference/contacts/retrieve.md): Fetch a single contact by ID. Returns `404 not_found` for both missing contacts and contacts owned by a different customer — existence is not leaked across tenants.
- [Update a contact](https://docs.ibubbl.com/api-reference/contacts/update.md): Overwrite the fields you send. Fields you leave out are not touched; a field sent as `null` is cleared. Unlike the upsert, this replaces values a rep set.
- [Delete a contact](https://docs.ibubbl.com/api-reference/contacts/delete.md): Delete a contact. It disappears from the list and from `GET /v1/contacts/{id}`, and every endpoint that takes its `id` (including `POST /v1/messages` with `contact_id`) returns `404 not_found`. Deleting it again also returns `404`.
- [Add a tag to a contact](https://docs.ibubbl.com/api-reference/contacts/add-tag.md): Add one tag. Idempotent: a tag the contact already has answers `200` unchanged. The name matches an existing tag trimmed and case-insensitively; a new name creates the tag. A newly added tag can start workflows with a "Tag added" trigger.
- [Remove a tag from a contact](https://docs.ibubbl.com/api-reference/contacts/remove-tag.md): Remove a tag by name (URL-encode it), matched trimmed and case-insensitively. Idempotent: a tag the contact doesn't have answers `200` unchanged. Removing a tag starts no workflow.
- [Opt a contact out](https://docs.ibubbl.com/api-reference/contacts/opt-out.md): Record that this person opted out of messages, as a STOP reply does. **This can't be undone**, through the API or the dashboard: every later send to this number answers `422 contact_opted_out`, even after the contact is deleted and created again.
- [Block a contact](https://docs.ibubbl.com/api-reference/contacts/block.md): A block is yours, on this contact: sends to them return `422 contact_blocked` (group conversations they're in are not affected). Their inbound messages are still stored and still fire `message.inbound`, but don't mark the conversation unread, notify anyone or start workflows. Unlike an opt-out, a bl…
- [Unblock a contact](https://docs.ibubbl.com/api-reference/contacts/unblock.md): Undo a block: sends to this contact are accepted again. An opt-out is not affected.
- [Mark a conversation read](https://docs.ibubbl.com/api-reference/conversations/mark-read.md): Mark every message you've received in this conversation read. It clears the unread badge in the iBubbl inbox and, when read receipts are on for your account, sends the contact a read receipt: they see "Read" under their latest message on iMessage, and on RCS (Android). SMS has no read receipts.
- [Start typing](https://docs.ibubbl.com/api-reference/conversations/start-typing.md): Show the contact the typing bubble (the three dots) in this conversation. It lasts 10 seconds: call again every 5 seconds to keep it going. Sending a message clears it on the contact's phone; so does `DELETE`, or simply not calling again.
- [Stop typing](https://docs.ibubbl.com/api-reference/conversations/stop-typing.md): Stop showing the typing bubble. You don't need this before sending: a sent message clears it on its own. Some phones keep showing the bubble for up to a minute after a stop that isn't followed by a message.
- [Create a webhook subscription](https://docs.ibubbl.com/api-reference/webhooks/create.md): Register an HTTPS endpoint to receive events. The response includes the signing secret **once** — store it immediately; it cannot be retrieved again. Use the secret to verify incoming webhook signatures (see [Signature verification](/guides/webhook-signatures)).
- [List webhook subscriptions](https://docs.ibubbl.com/api-reference/webhooks/list.md): Returns all currently active webhook subscriptions for the authenticated customer. Revoked subscriptions are omitted — query them by ID directly (`GET /v1/webhooks/{id}`) if you need their history.
- [Retrieve a webhook subscription](https://docs.ibubbl.com/api-reference/webhooks/retrieve.md): Fetch a single subscription by ID. Returns the subscription regardless of revoked status (so you can inspect history). `404 not_found` is returned for both missing subscriptions and those owned by a different customer.
- [Revoke a webhook subscription](https://docs.ibubbl.com/api-reference/webhooks/revoke.md): Soft-revoke a subscription. After revocation, no further events are delivered to its URL. The row is retained for audit purposes; you can still fetch it with `GET /v1/webhooks/{id}` and see its `revoked_at` timestamp.
- [Receive an event](https://docs.ibubbl.com/api-reference/inbound-events/receive.md): Receive a webhook from a connected third-party app (for example Recharge) and start any workflow whose **Webhook received** trigger matches it.
- [Error Reference](https://docs.ibubbl.com/errors.md): Stable error codes and what they mean.
- [OpenAPI, Postman and Insomnia](https://docs.ibubbl.com/openapi.md): Import the iBubbl OpenAPI spec into Postman or Insomnia and authenticate with your API key.
- [Versioning](https://docs.ibubbl.com/versioning.md): How iBubbl evolves the API without breaking integrations.
- [Changelog](https://docs.ibubbl.com/changelog.md): Changes to the iBubbl API and these docs, newest first.
- [Support](https://docs.ibubbl.com/support.md): How to reach iBubbl, and what to include so we can answer quickly.

## OpenAPI Specs

- [public](/openapi/public.json)


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