msgbubblesDocs

Conversations

Group creation reserves one monthly message slot before attempting its opening send. An attempted send retains the slot even after an error or timeout, because the message may already have been delivered. Exhaustion returns 429 monthly_quota_exceeded before the send attempt. An idempotent replay resolved before sending does not count again. SeeMonthly allowances.

A conversation is a thread between one of your numbers and a contact (or a group). Threads are created for you automatically on the first message in either direction — you only create one explicitly to start a group chat.

Browse threads

GET/v1/chats

GET/v1/chats/:id

The list paginates newest-first with limit (1–100, default 50) and before (ISO timestamp), returning { data, has_more, request_id } where each item in data is a chat object:

Chat object
{
  "id": "7f2c9e1b-…",
  "from_handle": "+18005551111",
  "remote_handle": "+15555550123",
  "is_group": false,
  "title": null,
  "opted_out_at": null,
  "last_message_at": "2026-06-11T18:21:04.000Z",
  "created_at": "2026-06-10T02:11:40.000Z",
  "updated_at": "2026-06-11T18:21:04.000Z"
}

opted_out_at is set while the recipient has opted out (replied STOP) on a shared number, and is always null on numbers that are yours alone. See Opt-outs.

To fetch a thread’s messages, pass its id as conversation_id on GET /v1/messages.

Create a group

POST/v1/chats

Create a group
curl -X POST https://api.msgbubbles.com/v1/chats \
  -H "Authorization: Bearer sk_live_…" \
  -H "content-type: application/json" \
  -d '{
    "from_handle": "+18005551111",
    "addresses": ["+15555550123", "+15555550124"],
    "message": "welcome to the group!",
    "title": "Launch crew"
  }'
  • from_handle — one of your iMessage/SMS numbers. WhatsApp numbers can’t create groups (400 invalid_from_handle).
  • addresses — 2 to 31 recipients (2+ remotes is what makes it a group).
  • message — required; groups are established by sending their first message.
  • title — optional display name, up to 100 characters. Naming is best-effort: if it doesn’t take, the group is still created and comes back with title: null — set it afterwards with PATCH /v1/chats/:id. Group MMS threads can’t be named, so a title on a mixed group is always dropped.

Pass an Idempotency-Key header to make retries safe: a repeated key returns the original group with 200 instead of creating a second one with 201.

If your number already has a group with exactly these addresses, no second group is created: the message is delivered into the existing one, and you get that group back with 200 (and its original id). A retry with the same Idempotency-Key returns it again without re-sending. In the rare case that group isn’t linked to your account, you get 409 chat_conflict — the message was delivered, so don’t retry.

The opening message is recorded like any other send: it appears in GET /v1/messages for the group and fires message.delivered and message.read as receipts come in. Send follow-ups into the group with conversation_id on POST /v1/messages.

SMS and mixed iMessage/Android groups

A group is either all-iMessage or a group MMS thread. The moment one non-iMessage (Android, green-bubble) member is in a group, the whole thread is group MMS — every member, including the iMessage ones, is on SMS/MMS. There’s no per-member split.

POST /v1/chats picks for you: it checks every address in addresses against iMessage and creates an iMessage group when all of them are on it, or a group MMS thread when any one isn’t. If the check can’t reach a verdict for an address, that address counts as iMessage. The request and response look the same either way.

Group MMS threads have a few limits: they can’t be named (a title comes back null), renamed, or have their members changed.

Groups someone else started work too: if one of your numbers is added to an existing group (iMessage, SMS, or mixed), that thread shows up in GET /v1/chats and you can reply to it with conversation_id on POST /v1/messages.

Receiving in groups

Any group one of your numbers is part of — iMessage, SMS/MMS, or WhatsApp — is tracked automatically the moment a message arrives: the thread shows up in GET /v1/chats with is_group: true (and the group’s title when it has one).

Inbound group messages are easy to tell apart. The message.received webhook carries is_group: true, and from is always the individual sender — the group itself is conversation_id. Each message also records its sender in metadata (sender_handle for iMessage/SMS, sender_jid for WhatsApp), so every message in the thread stays attributable when you read it back with GET /v1/messages. Title changes arrive as the conversation.renamed webhook event.

Several of your numbers in one group

When more than one of your numbers is a member of the same group, each number gets its own conversation for that group (same thread, different from_handle) — like two of your email addresses cc’d on one thread. Each conversation records its own copy of every group message and fires its own webhook events: one message.received per member number, distinguished by conversation_id and to. Receipts, edits, and reactions likewise arrive per conversation. Dedupe by conversation_id if you only want one copy.

WhatsApp groups

A WhatsApp group your number belongs to shows up in GET /v1/chats as soon as a message arrives in it. From then on you can reply with conversation_id on POST /v1/messages and react to its messages. You can’t create a WhatsApp group, rename one, or change its members from the API. Not every WhatsApp number supports groups; a send into a group from one that doesn’t returns 400 unsupported.

Manage a group

PATCH/v1/chats/:id

Rename: { "title": "New name" }.

POST/v1/chats/:id/participants

DELETE/v1/chats/:id/participants/:handle

Add with { "handle": "+15555550125" }; remove by handle in the path. Adding and removing members is temporarily unavailable: both endpoints return 503 without changing the group — participant_add_disabled for an add, participant_remove_disabledfor a remove. Retrying returns the same error until they’re available again.

Read receipts

POST/v1/chats/:id/read

Marks the thread read on your side, so the people messaging you see read receipts. Works for iMessage and WhatsApp threads.

Typing indicators

POST/v1/chats/:id/typing

{ "typing": true } shows the typing bubble on the recipient’s side; false hides it. It auto-expires on the recipient’s device, so don’t worry about cleanup if your process dies mid-conversation. Inbound typing from your contacts arrives as the conversation.typing webhook event.