iMessage group chat API

Our iMessage group chat API lets your business number start a group with 2 to 31 other people, send into it, read it, rename it, add or remove members and leave it. Group chats are on for every number, and Pro is $49/month per number.

Pro is $49/month per number. Limits apply to every group.

Kitchen remodel3 people
Your tile arrives Tuesday. Mike installs Wednesday.
Dana
Perfect, I will be home.

Start a group with one request.

List the other members, name it and send the first message. Pick a group and the request changes with it.

Group messages reach your server.

A group message arrives as message.received with a chat_id, and handle is who wrote it. A rename or a member change is its own group.event.

Your server
// pick something to happen in the group

Run the whole group from code.

Rename it, add or remove members, list your groups and read one back. Send into it with chat_id in place of to.

Rename and change members
POST /api/imessage/groups/update
{"chat_id": "iMessage;+;chat123456789",
 "name": "Launch crew 2026"}
Send into the group
POST /api/imessage/send
{"chat_id": "iMessage;+;chat123456789",
 "text": "Doors open at 7"}
Read and leave
GET  /api/imessage/groups
GET  /api/imessage/messages?chat_id=...
POST /api/imessage/groups/leave
Dinner FridayRosa’s Kitchen and 2 more
Jo
Friday still works for me.

Pick a message to see what the agent does.

The agent speaks when spoken to.

On a number our hosted AI agent manages, it replies in the group only when a message is for it. Its follow-up and daily triggers never fire into a group.

How it works

  1. Your number is a member. It is in the group like any other person. You start a group with one request that lists the other members and sends the first message.
  2. The group gets a chat_id. A string such as iMessage;+;chat123456789. It does not change when the group is renamed or its members change.
  3. You address the group by it. Use chat_id in place of to on POST /api/imessage/send. The message goes to everyone in the group.
Start a group, then send into it
POST /api/imessage/groups
{"to": ["+18055559876", "+13105550000", "jane@example.com"],
 "text": "Welcome to the launch group!",
 "name": "Launch crew"}

// later sends use the group's chat_id
POST /api/imessage/send
{"chat_id": "iMessage;+;chat123456789", "text": "Doors open at 7"}
to takes 2 to 31 other members as phone numbers or emails. name is optional, up to 60 characters. The full reference is in our group chats docs.

What you can do in a group

Add a number

Your number starts the group with POST /api/imessage/groups, or someone adds your number. Groups your number is added to by someone else work the same way, and their messages reach your webhook with a chat_id.

Send

Text, photos, voice messages, videos, polls, inline replies and effects, with chat_id in place of to. You can show typing in a group and send and receive tapbacks.

Manage

POST /api/imessage/groups/update renames the group and adds or removes members. POST /api/imessage/groups/leave leaves it, and the stored messages stay readable.

Read

GET /api/imessage/groups lists groups. GET /api/imessage/messages?chat_id= reads one group’s messages.

MCP

Do all of it from an AI client over MCP: create_group_chat, list_group_chats and update_group_chat, plus chat_id on send_imessage, list_messages and show_typing.

Your code or the agent

On a number you manage by API, your server handles group events. On a number managed by the hosted AI agent, the agent answers in the group too. It never replies to another number we run, and some lines need an update before the agent can answer in groups.

Limits and plans

2 to 31 members

A group takes 2 to 31 other members when you start it. Your own number is always in it and is not listed.

429 new_contact_limit

Each member your number has never exchanged a message with counts as a new contact when you start the group or add them. A Pro number can reach 5 new contacts a day, and Growth raises the daily limit.

403 recipient_opted_out

A STOP from any member blocks sends into every group they are in, until you remove them or they text START. Every member must have agreed to hear from you, because a group message reaches all of them.

422 not_on_imessage

A new member who is not on iMessage.

404 unknown_chat

A chat_id none of your numbers has. A line that needs an update returns 409 client_update_required.

A broadcast is not a group

A broadcast sends each recipient their own 1:1 message. Use a group when members should see each other.

CRMs

Group messages are not logged in Close or HubSpot.

Plans

Group chats are on for every number at no extra cost. Pro is $49/month per number, with 5 new contacts a day per number. Growth has 25+ new contacts a day per number and starts at $199/month per number. Videos and texts from our hosted agent use credits, and a video sent into a group is charged once per send. Details are on the iMessage API page.

Questions

Is there an iMessage group chat API?

Yes. POST /api/imessage/groups starts an iMessage group from your number with 2 to 31 other members and a first message. Later sends use the group’s chat_id.

How do I add a business number to an iMessage group?

Start the group from the number with the API, or have a member add the number. Groups your number is added to by someone else work the same way, and their messages reach your webhook with a chat_id.

How many people can be in a group?

When you start one, the to list takes 2 to 31 other members, and your own number is always in the group and is not listed.

Do group members count toward my new-contact limit?

Only members your number has never exchanged a message with. Each counts as one new contact when you start the group or add them. Pro includes 5 new contacts a day per number, and Growth raises the daily limit.

Can the AI agent answer in a group?

On a number managed by the hosted AI agent, yes. It replies in the group only when a message is for it, and its follow-up and daily triggers never fire into a group.

Do group chats cost extra?

No. Group chats are on for every number. Videos and texts from our hosted agent use credits, and a video sent into a group is charged once per send, however many members it has.

Put your number in a group

Get a number, start a group with a friend and send into it with the chat_id.