## Send a group message

`POST /send-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.

> **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

- `numbers` (string[], 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.

- `message` (string) — The text content of the message. Required unless an attachment is supplied.

- `mediaAttachmentUrl` (string) — URL to an image, video, or contact card attachment. Mutually exclusive with audioAttachmentUrl.

- `audioAttachmentUrl` (string) — URL to an audio file sent as a voice memo. Mutually exclusive with mediaAttachmentUrl.

- `enableAiVoiceMemo` (boolean) — Generates a voice memo from message.

- `groupName` (string) — Honored only when the group is created. Ignored on reuse.

- `lineId` (string (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.

- `idempotencyKey` (string) — 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](https://api.tryprojectblue.com/#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

**Request — New group**

groupName is honoured only when the group is created.

```bash
curl -X POST https://api.tryprojectblue.com/send-group-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+16025551234", "+14808405291"],
    "message": "Hey both, following up on the walkthrough.",
    "groupName": "Elm St walkthrough"
  }'
```

**Request — Same group again**

Same numbers resolve to the same thread — no groupId needed.

```bash
curl -X POST https://api.tryprojectblue.com/send-group-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+16025551234", "+14808405291"],
    "message": "Confirming 2pm Thursday."
  }'
```

**Response — 200 OK**

```json
{
  "success": true,
  "status": "queued",
  "groupId": "pbg_...",
  "created": true,
  "groupStatus": "creating",
  "service": null,
  "recipients": ["+16025551234", "+14808405291"],
  "devicePhoneNumber": "+15559876543",
  "mediaAttachmentUrl": null,
  "audioAttachmentUrl": null
}
```

**Response — 409**

```json
{
  "error": "This group already exists on a different line.",
  "devicePhoneNumber": "+15559876543"
}
```

**Response — 403**

```json
{
  "error": "Trial accounts cannot create group chats."
}
```

**Response — 400**

```json
{
  "error": "numbers must be an array of 2 to 32 phone number strings."
}
```