This API is still in beta, and is subject to change at any time. Please consult with us before going into production.
Currently the group messaging api is only available to Sapphire plans and above.
- ✅ Sending iMessages to groups: supported
- ✅ Sending SMS to groups: supported
- ✅ Receiving iMessage in groups: supported
- ✅ Receiving SMS in groups: supported
- ✅ Sending MMS to groups: supported
- ✅ Receiving MMS in groups: supported
- ✅ Sending expressive messages: supported
- ✅ Adding people to groups: supported
- 🟡 Removing people from groups: Scheduled
- 🟡 Changing group names: Scheduled
- 🟡 Leaving groups: Scheduled
Sending group messages
The API request to send group messages is similar to the individual message request.
The API request should be made with the
application/json content type header. If the group does not exist during the request, it will be created automatically.
POST Body (JSON)
The group messaging API expects a slightly different json body than the individual message api. Here are the available fields:
|numbers||numbers is an array of |
|group_id||The group_id field is a uuid with which you can message groups that you have already created. This is the same as passing the same list of numbers as was passed in the initial request|
|media_url||A CDN link to a file which is publicly accessible which will be downloaded and sent to the group on our end|
|statusCallback||An endpoint which we can hit to notify your app of status updates for this message, see status callback for more info|
The API response will contain the assigned group_id, which is useful for correlating messages sent to a group and messages received from a group.
group_id that you receive in the response from
/api/send-group-message is the only way you will be able to correlate messages sent in a group to messages received from a group in your app.
See the example below to see what our response body looks like. Note that this API is still in Beta so the fields below are subject to change.
to_number fields will likely be renamed to
Receiving Group Messages
Receiving group messages is very straightforward. There will be a field called group_id which gets sent to your receive webhook.
Adding people to group chats
To add someone to your group chat, you can send a POST request to
This endpoint expects 3 parameters.
|group_id||The id of the group which you want to add a recipient to|
|modify_type||The modification type to perform|
|number||The E.164 standard format for the number that you want to add/remove from the group chat. (Ignored if |
🟡 = unsupported
Here is an example of the JSON post body:
Removing people from group chats (In progress)
This documentation is actively being updated