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.
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.
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.
POST /api/imessage/groups/update
{"chat_id": "iMessage;+;chat123456789",
"name": "Launch crew 2026"}POST /api/imessage/send
{"chat_id": "iMessage;+;chat123456789",
"text": "Doors open at 7"}GET /api/imessage/groups
GET /api/imessage/messages?chat_id=...
POST /api/imessage/groups/leavePick 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
- 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.
- The group gets a
chat_id. A string such asiMessage;+;chat123456789. It does not change when the group is renamed or its members change. - You address the group by it. Use
chat_idin place oftoonPOST /api/imessage/send. The message goes to everyone in the group.
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.