Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

Send a group message

Send an iMessage or SMS to a group of 2 to 32 recipients. There is no create step — pass numbers every time. The same participant set resolves to the same thread.

POST/send-group-messageBearer token
All or nothing iMessage
A group is delivered as iMessage only when every participant is iMessage reachable. One participant on Android drops the entire thread to SMS.
Queued — service is always null here
status is always "queued" and service is always null on this endpoint. The send is never synchronous — whether the thread lands as iMessage or SMS is not known until the cron runs the all-participants availability probe. Read the resolved service from /get-messages-api.
No CRM sync
Group sends are not mirrored into HighLevel, HubSpot, or Close, unlike single recipient sends via /send-api-message.

Request body

numbersstring[]Required
Recipient phone numbers, 2 to 32 entries. Flexible formats accepted; normalized to E.164. Deduped after normalization. Passing the same set of participants again reuses the existing group thread.
messagestring
The text content of the message. Required unless an attachment is supplied.
More options 6 fields
mediaAttachmentUrlstring
URL to an image, video, or contact card attachment. Mutually exclusive with audioAttachmentUrl.
audioAttachmentUrlstring
URL to an audio file sent as a voice memo. Mutually exclusive with mediaAttachmentUrl.
enableAiVoiceMemoboolean
Generates a voice memo from message.
groupNamestring
Honored only when the group is created. Ignored on reuse.
lineIdstring (UUID v4)
From GET /get-lines. On reuse it must match the line the group already lives on. Rejected on trial accounts — see Trial Accounts. Group send itself is unavailable on trial.
idempotencyKeystring
1 to 200 characters. Values outside those bounds are silently ignored, not rejected.

groupStatus is "creating" until the chat exists on the sending line, then "active". created is true only when this call created the group. groupId is opaque and stable — do not parse it.

On a replayed or deduplicated request, groupId and devicePhoneNumber can be null, because the group did not exist yet when the claim was taken.

Group send is unavailable on trial accounts — see Trial accounts.

Status codes

200
Message queued successfully
400
Invalid request — missing message/attachment, both attachments, recipient count, email/chat handles, phone format, or lineId
401
Missing or invalid Authorization header / Invalid API key
403
Unavailable on trial (see Trial accounts) — e.g. Trial accounts cannot create group chats. Also: One or more recipients are blocked.
409
This group already exists on a different line.
429
Rate limit exceeded
500
Internal server error
API reference