iMessage Group Chat API: Create, Send, Read and Manage Groups

A lot of real coordination happens in group threads: a homeowner, a project manager and a crew lead; friends planning a trip; a team sorting out Saturday's game. This is a reference walkthrough of the group endpoints in the ZeroSettle group chats docs, with the request shapes as the docs give them. For the product side (when an assistant should speak, how to keep it quiet), read How to build an AI assistant for iMessage group chats alongside it.

The examples assume two shell variables: BASE=https://portal.zerosettle.io and TOKEN, your API token from the console.

Does my number support group chats?

Yes: group chats are on for every ZeroSettle number, current and new, and there is nothing to request or switch on. You can confirm it on the line itself:

curl -s -H "Authorization: Bearer $TOKEN" $BASE/api/imessage/line
# { ..., "group_chats": true, ... }   also on each entry in "lines" when you have several numbers

ZeroSettle can turn group chats off for an individual number. Such a number has no group_chats key at all, every group call on it is refused with 403 group_chats_not_enabled, and messages people send in a group that includes it carry no chat_id. So the safe check is "the key is present and true", not "the key isn't false".

A number that needs a software update before it can use group chats answers 409 client_update_required and sends nothing. Retry it later; it isn't permanent.

What is a chat_id?

A chat_id is the group's permanent name in the API: a string such as iMessage;+;chat123456789, at most 128 characters. Store it exactly as you receive it. It stays the same for the life of the group, through renames and membership changes, so it is the right primary key for anything you attach to a group in your own database (a job, a trip, a team).

Everywhere a 1:1 conversation is keyed by handle, a group is keyed by chat_id. A conversation on a line is either one contact or one group. In a URL, encode it: iMessage%3B%2B%3Bchat123456789.

A group lives on the line that is in it. Calls that name a chat_id act on that line, so you don't pass line or line_id even with several numbers. A chat_id that none of your lines has answers 404 unknown_chat.

How do I start a group?

Send POST /api/imessage/groups with the other members and a first message; the group is created by sending that message.

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"to": ["+18055559876", "+13105550000", "jane@example.com"],
       "text": "Welcome to the launch group!", "name": "Launch crew"}' \
  $BASE/api/imessage/groups

• to: 2 to 31 handles (phone numbers or emails, each as in /send). These are the other members. Your number is always in the group; don't list it.
• text (required): the first message, 1 to 4,000 characters after trimming.
• name (optional): up to 60 characters. Without one, Messages shows the members' names.
• line_id or line (optional, with more than one number): the number that creates the group. It must have group chats on.

Before anything is sent, every member is checked as if you were texting them 1:1. If any check fails, nothing is sent:

• STOP: a member who texted STOP to any of your numbers gives 403 recipient_opted_out, with error.handle naming them.
• New contacts: each member the line has never exchanged a message with (1:1 or in another of its groups) counts as one new contact toward the line's day. If they don't all fit, you get 429 new_contact_limit.
• On iMessage: each new member must be on iMessage, or the call answers 422 not_on_imessage with error.handle.

A successful response is the shape of a send plus the group:

{
  "ok": true, "status": "message_sent", "message": "…", "id": 70,
  "record": {"id": 70, "kind": "message", "direction": "out", "handle": "iMessage;+;chat123456789",
             "text": "Welcome to the launch group!", "status": "sent", "guid": "7B1D…",
             "ts_ms": 1757400200000, "chat_id": "iMessage;+;chat123456789"},
  "chat": {"chat_id": "iMessage;+;chat123456789", "name": "Launch crew",
           "participants": ["+18055559876", "+13105550000", "jane@example.com"]}
}

participants are always the other members, never your own number. With several numbers, chat also carries line and line_id.

How do I send into a group?

Use the normal POST /api/imessage/send with chat_id instead of to; pass exactly one of the two.

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"chat_id":"iMessage;+;chat123456789","text":"Doors open at 7"}' $BASE/api/imessage/send

Everything a 1:1 send takes works in a group: text, image_b64 or audio_b64, video_id or video_b64, poll, reply_to and effect. The response is a normal send response; its record carries chat_id and its handle is the chat id. A video into a group uses credits (1 per 3 MB) once per send, however many members the group has.

Two rules differ from 1:1 sends, and both are worth encoding in your client:

• STOP blocks the whole group. If any member has texted STOP, the send is refused with 403 recipient_opted_out and error.handle says who. Nothing is sent. Remove that member, or leave the group.
• Some 1:1 rules are skipped. The unanswered-message rule (awaiting_reply), the on-iMessage check and the automatic name-and-photo share are 1:1 rules, and a group send skips them.

The usual line rules still hold: a line sends one message at a time, so concurrent sends queue and can surface as 429 line_busy (retry after 2 seconds). The send a message docs and Send an iMessage from code cover the retry pattern.

How do I read groups and their messages?

GET /api/imessage/groups lists every group on your numbers that have group chats on:

curl -s -H "Authorization: Bearer $TOKEN" $BASE/api/imessage/groups
# {"groups": [{"chat_id": "iMessage;+;chat123456789", "name": "Launch crew",
#              "participants": ["+18055559876", "+13105550000", "jane@example.com"],
#              "created_at_ms": 1757400200000, "updated_at_ms": 1757400200000}]}

name is null when the group has none, and groups your number has left are not listed. With several numbers, each entry carries line and line_id.

Messages. A group message has the same shape as any other message, plus chat_id. A 1:1 message never has the key. For an inbound group message, handle is the member who sent it; for an outbound one, handle is the chat id.

# one group's messages (chat_id and handle can't be combined)
curl -s -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/imessage/messages?chat_id=iMessage%3B%2B%3Bchat123456789&after_id=0&limit=100"
# {"messages": [{"id": 71, "kind": "message", "direction": "in", "handle": "+13105550000",
#   "text": "See you there", "status": "received", "guid": "8C2E…", "ts_ms": 1757400230000,
#   "chat_id": "iMessage;+;chat123456789"}], "next_after_id": 71}

Be careful with filters: ?handle= returns only the 1:1 conversation with that contact, never their group messages. Without either filter you get everything, groups included, so a sync job that pages through all messages will see group rows and must branch on chat_id. Paging works as in the read messages docs: pass next_after_id back as after_id.

Conversations. GET /api/imessage/conversations lists each group as one entry next to the 1:1 ones, with chat_id, name, participants, count and last. When chat_id is present, the entry is a group and its handle is the chat id. A group your number has left, or was removed from, is still listed with its messages and "left": true; sending into it answers 404 unknown_chat.

Deleting. DELETE /api/imessage/conversations/{handle} with an encoded chat id deletes that group's stored messages. As with a 1:1 delete, nothing is unsent and nobody in the group is told.

How do I rename, add, remove or leave?

Renames and membership changes go through POST /api/imessage/groups/update, and leaving goes through POST /api/imessage/groups/leave.

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"chat_id": "iMessage;+;chat123456789", "name": "Launch crew 2026",
       "add": ["+16465550199"], "remove": ["jane@example.com"]}' \
  $BASE/api/imessage/groups/update
# {"ok": true, "chat": {"chat_id": …, "name": "Launch crew 2026", "participants": […]}}

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"chat_id": "iMessage;+;chat123456789"}' $BASE/api/imessage/groups/leave
# {"ok": true}

• name, add and remove are all optional; send only what changes. The response is the group after the change.
• Adding someone who has texted STOP is refused with 403 recipient_opted_out. Someone new to the line counts as a new contact on the day you add them, exactly as when you start a group.
• After /groups/leave, your number stops receiving the group's messages and the group drops out of GET /api/imessage/groups. The stored messages stay readable.

When a group send comes back recipient_opted_out, remove that member with /groups/update before your next send, and don't add them back unless they text START.

Do typing, reactions, replies and polls work in groups?

Yes, all four work in groups. Typing and polls take chat_id where a 1:1 call takes to, while reactions and replies point at a message that is already in the group:

A poll is the most useful of these in a group, because it turns "what night works for everyone?" from twenty bubbles into one tap each:

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"chat_id": "iMessage;+;chat123456789",
       "poll": {"question": "Which night works?", "options": ["Thu", "Fri", "Sat"]}}' \
  $BASE/api/imessage/send

Members on iOS 26 or later vote in the thread; older iPhones show "Sent a poll" and can't vote, so don't wait forever on a missing vote. What can an iMessage API send? and the typing indicators docs have the full shapes.

What do group webhooks and stream events look like?

Group messages arrive as the same events as 1:1 messages (message.received, message.sent, message.failed, reaction.*, poll.voted), each message carrying chat_id. Two things are new: group.event on the webhook, and group.updated on the live stream only.

group.event. A rename, a member added or removed, a member leaving and a new group photo are stored as a message of kind: "group_event" and delivered as their own event, with the header X-ZeroSettle-Event: group.event. They are never message.received, so an auto-responder that acts only on message.received never answers one. handle is who did it, text says what happened, and group_event holds the details:

{"id": 72, "kind": "group_event", "direction": "in", "handle": "+18055559876",
 "text": "Renamed the group “Launch crew 2026”", "status": "received", "guid": "9D3F…",
 "ts_ms": 1757400300000, "chat_id": "iMessage;+;chat123456789",
 "group_event": {"type": "renamed", "name": "Launch crew 2026"}}

group_event.type is renamed (with name), member_added or member_removed (with handle), member_left, or photo_changed. A member_removed without handle means your number was removed, and the group is then left, as with /groups/leave.

group.updated. Whenever a group's name or members change (you start or update it, or a group event changes it), the live stream gets an event: group message whose data is group.updated with the whole group as it is now. It is not sent to your webhook. A dashboard on the stream should keep the copy with the newest updated_at_ms; a backend on the webhook should re-read GET /api/imessage/groups or follow group.event messages.

Here is the routing a receiver needs, after it has verified the signature and answered 200 (the webhooks docs and How to receive iMessages with a webhook cover signing, retries and dedupe):

type ZsMessage = {
  id: number; kind: string; direction: "in" | "out"; handle: string; text?: string;
  chat_id?: string; group_event?: { type: string; name?: string; handle?: string };
};

export function route(ev: { event: string; message: ZsMessage }) {
  const m = ev.message;
  if (ev.event === "group.event") return onGroupEvent(m);
  if (ev.event !== "message.received") return;       // your own sends echo back as message.sent
  if (m.chat_id) return onGroupMessage(m.chat_id, m); // m.handle is the member who wrote it
  return onDirectMessage(m.handle, m);
}

function onGroupEvent(m: ZsMessage) {
  const e = m.group_event!;
  if (e.type === "member_removed" && !e.handle) return markLeft(m.chat_id!); // your number was removed
  return refreshGroup(m.chat_id!);                   // re-read GET /api/imessage/groups
}

Queue work per conversation key (chat_id for groups, handle for 1:1) so a group's messages are handled in order, and never key group work on the member's handle: the same person can be in a 1:1 thread and three groups with you at once.

Which MCP tools handle groups?

When at least one of your numbers has group chats on, the ZeroSettle MCP connector adds group support to its tools, so Claude, Claude Code or Cursor can work with groups directly:

list_conversations shows each group by its name, or by its members when it has none. The hosted iMessage MCP server covers setup for each client.

Does the hosted AI agent answer in groups?

Yes: with no server at all, a number managed by ZeroSettle's hosted AI agent answers inside its groups too. It reads the group's recent messages (each labeled with who wrote it) and knows the group's name and members. It replies into the group, never in a 1:1 chat, and only when a message is meant for it or asks something it can help with; it stays silent when people are talking to each other.

• No triggers in groups: its follow-ups and daily texts never fire into a group.
• Not woken by everything: tapbacks, poll votes and the group's own events (a rename, someone joining or leaving) don't wake it.
• Never another ZeroSettle number: it never answers one of ZeroSettle's own iMessage numbers, so two agents can't keep texting each other. When several of your numbers with the agent on share a group, only one of them answers.
• Credits: each text it sends uses one credit, as anywhere else.

To run your own code instead, set the number to managed_by: "api" so inbound texts reach your webhook (see the AI agent docs), and read When should an AI speak in a group chat? before your agent says anything.

Should I use a group or a broadcast?

Use a group when the members should see each other and talk to each other; use a broadcast when each person should get the same message privately. POST /api/imessage/broadcast never creates or uses a group chat.

A quick test: if a recipient's reply might hold something the others shouldn't see (a price, an address, a complaint), use a broadcast, not a group.

Which errors should my code handle?

Group calls use the same JSON error shape as the rest of the API: branch on error.code and show error.message to a person. These are the group-specific ones:

The full list, including line_busy and the 503 codes to retry with backoff, is in the errors, limits and compliance docs.

What limits and consent rules apply?

The same per-number limits as 1:1 messaging, applied to every member. Three rules matter most in groups:

• Each new person is a new contact. Starting a group, or adding someone to one, counts every member the line has never exchanged a message with as a new contact: 5 a day on Pro, 50 a day per number on Growth (and 3 per 15 minutes). After that, members are known contacts, and a 1:1 text to one of them is not new. People who text your number first are never limited.
• STOP from any member blocks the group. A STOP blocks that person on every number of the account, as always, and sends into any group they are in are refused until they are removed or text START. How STOP and opt-outs work has the details.
• Consent covers everyone. A group message reaches every member, and each of them must have agreed to hear from you. Adding someone to a group is texting them.

Each number allows 10,000 messages a day, sent and received, with known contacts (people who texted it first or it already has a conversation with). In practice, the new-contact cap is what limits how many unfamiliar people you can put in a group at once. A group of 20 people the line has never messaged can't be started in one call on Pro or Growth: Pro allows 5 new contacts a day, and Growth allows 50 a day per number but 3 per 15 minutes, so the call answers 429 new_contact_limit and nothing is sent. Start with people who have already texted the number, or start small and add the rest over time with /groups/update. For high volume and compliance needs, Enterprise has custom pricing through sales (book a demo).

What isn't covered?

Four things are outside the group API today, and it's better to know them before you design around them:

• Broadcast is not a group. POST /api/imessage/broadcast still sends each recipient their own 1:1 message.
• Only messages your number sends through ZeroSettle are recorded from your side: the API, MCP and the console.
• CRMs: group messages are not logged in Close or HubSpot. If your team works from a CRM, log group activity yourself from the webhook; the CRM integrations docs describe what is logged for 1:1 threads.
• Chat backgrounds set in a group are not reported.

For what people actually build with this, see one iMessage group per job for homeowners, project managers and crews, a group trip planner, and a coordinator for teams, clubs and communities.