Group messages

This API is still in beta, and is subject to change at any time. Please consult with us before going into production.

Availability

Currently the group messaging API is only available on select plans. Contact us for access.

AI Agent (inbound-initiated) plans can only respond to group chats that the number has been added to — they cannot create new group chats. To create outbound group chats, upgrade to the Blue Ocean plan.

Roadmap

• ✅ 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
• ✅ Sending inline replies: supported on V2 iMessage lines
• ✅ Adding people to groups: supported
• ✅ Changing group names: supported on iMessage groups
• ✅ Removing people from groups: supported
• 🟡 Leaving groups: Scheduled

API response

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.

The 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.

Sending group messages

You can send messages using the /send-group-message endpoint.

To reply to a specific group message, include reply_to.message_handle. The target must belong to the supplied group_id and from_number. See iMessage inline replies.

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 and removing people in group chats

You can add an external participant to a group chat, or remove one from it, with the /api/modify-group endpoint.

POST /api/modify-group
{
  "group_id": "group_123456",
  "modify_type": "add_recipient",
  "number": "+19998887777",
  "from_number": "+15550001111"
}

• modify_type is add_recipient or remove_recipient.
• number is the external participant to add or remove. When adding, it must be able to receive iMessage. Your own Sendblue numbers cannot be added or removed.
• from_number selects which of your Sendblue numbers performs the change. It must already be a participant of the group. Free shared-line plans must provide it; other plans can omit it only when exactly one of their numbers is in the group. If none of your numbers participate, the request fails with line_not_registered; if multiple numbers participate, it fails with ambiguous_sending_line. Nothing changes in either case.

A 200 response means the requested membership state was verified on the device and Sendblue’s participant state was updated to match. This can be a real change or an idempotent no-op when the participant was already present or absent. Sendblue never reports success based on an unverified acknowledgement.

Requirements and limits

• Only iMessage group chats can be modified. SMS/MMS group chats are not supported.
• On free shared-line plans, a participant must be verified for the selected Sendblue number before you can add them.
• Removing someone requires the group to have at least four total members (including your number) before the removal. Apple enforces this; a smaller group returns group_too_small.
• You do not need to have created the group to remove a member.
• Adding someone who is already in the group, or removing someone who is already absent, succeeds without changing anything.
• Group member changes require an updated line. If your line has not updated yet, the request fails with worker_version_unsupported; retry later.

Error responses

Errors use the standard envelope with a machine-readable error field:

{
  "status": "ERROR",
  "group_id": "group_123456",
  "modify_type": "remove_recipient",
  "number": "+19998887777",
  "error": "group_too_small",
  "message": "Cannot remove from a group with 3 total members; Apple requires at least 4"
}

HTTP Status	Error	Description
400	invalid_request	Missing or invalid number, group_id, or modify_type
400	invalid_group	The group_id does not exist for this account
400	from_number_not_in_group	The from_number is not a participant of the group
400	ambiguous_sending_line	Multiple of your numbers are in the group; specify from_number
400	contact_not_verified	On a free shared-line plan, the participant is not verified for the selected Sendblue number
403	temporary_token_line_not_allowed	The temporary API token cannot use the selected Sendblue number
404	line_not_registered	The from_number is not registered to this account, or none of your numbers participate in the group
422	target_not_imessage	The target cannot receive iMessage, so it cannot be added
422	group_too_small	Removal from a group with fewer than four total members
422	group_not_found_on_line	The selected line has no matching iMessage group chat
422	modification_rejected	The device refused the change
422	unsupported_target	The target is one of your own Sendblue numbers
500	state_update_failed	The device change was confirmed, but Sendblue could not finish updating the group state; confirm membership before retrying
503	group_modification_in_progress	Another change for this group is still being processed; wait briefly, then retry. If the previous result was outcome_unknown, confirm membership first
503	worker_version_unsupported	The line has not updated to a build that can verify group changes; retry later
503	worker_unavailable	The line is disconnected or could not inspect the exact group; retry later
503	service_unavailable	Sendblue could not validate required account or group state before dispatch; retry later
504	outcome_unknown	The change may or may not have been applied; confirm the group’s membership before retrying

A 504 outcome_unknown response means Apple may have applied the change even though it could not be verified in time. Check the group’s membership before retrying — especially for removals — because Sendblue never replays the change automatically.

Changing group names

You can rename or clear the Apple-visible name of an iMessage group with the Group Names API. The change is verified on the device that serves the group before the API responds, and the verified name becomes the group’s group_name. If more than one of your Sendblue numbers is in the group, pass from_number to choose which number performs the change; the success response reports the number that acted.

Changing group photos

On supported lines you can set or clear the Apple-visible photo of an iMessage group with the Group Photos API. The change is verified on the device that serves the group before the API responds, and the verified photo’s metadata — including a direct image URL — is returned by GET /api/v2/groups/{group_id}.