<!-- https://missblue.dev/docs/groups -->

# Group conversations

Native iMessage groups use the same number ownership boundary as one-to-one sends. Every mutation returns a refreshed group, so an integration can store exactly what Messages accepted instead of guessing.

Base URL: `https://api.missblue.dev`

Every request carries `Authorization: Bearer $MISS_BLUE_KEY`.

### POST /v1/groups

Create a native iMessage group and send its first message.

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `number_id` | `uuid` | yes | A number held by this project. |
| `participants` | `string[]` | yes | 2–32 different phone numbers or Apple ID emails. |
| `initial_message` | `string` | yes | 1–20,000 characters. Group creation and the first message are one operation. |

Request body:

```json
{
  "number_id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
  "participants": [
    "+15555550100",
    "+15555550101"
  ],
  "initial_message": "Welcome to the project group."
}
```

Example:

```bash
curl -X POST https://api.missblue.dev/v1/groups \
  -H "Authorization: Bearer $MISS_BLUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number_id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
    "participants": [
      "+15555550100",
      "+15555550101"
    ],
    "initial_message": "Welcome to the project group."
  }'
```

Response:

```json
{
  "chat_id": "iMessage;+;chat123456789",
  "participants": [
    { "id": "p1", "handle": "+15555550100", "name": "Ari" },
    { "id": "p2", "handle": "+15555550101", "name": "Sam" },
    { "id": "self", "handle": "+16465550142", "is_self": true }
  ]
}
```

Errors:

- `400` — Fewer than two different participants, too many participants, or an empty first message.
- `404` — The number is outside this project.

### GET /v1/groups/{chat_id}

Pull the group's current name, photo URL, and participants.

Example:

```bash
curl -X GET https://api.missblue.dev/v1/groups/iMessage%3B%2B%3Bchat123456789 \
  -H "Authorization: Bearer $MISS_BLUE_KEY"
```

Response:

```json
{
  "chat_id": "iMessage;+;chat123456789",
  "title": "Install team",
  "photo_url": "https://api.missblue.dev/v1/attachments/…/view",
  "participants": [
    { "id": "p1", "handle": "+15555550100", "name": "Ari" },
    { "id": "self", "handle": "+16465550142", "is_self": true }
  ]
}
```

Errors:

- `404` — No such group on a number held by this project.

### PATCH /v1/groups/{chat_id}

Rename a group and/or replace its photo.

Upload the JPEG or PNG first. To remove the current photo, omit photo_attachment_id and send remove_photo: true. The complete refreshed group is returned.

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `title` | `string` | no | At most 256 characters. |
| `photo_attachment_id` | `uuid` | no | Uploaded JPEG or PNG. |
| `remove_photo` | `boolean` | no | Cannot be true while replacing the photo. |

Request body:

```json
{
  "title": "Install team",
  "photo_attachment_id": "88de9745-30e0-4b93-bfcb-dbb7f3325dde"
}
```

Example:

```bash
curl -X PATCH https://api.missblue.dev/v1/groups/iMessage%3B%2B%3Bchat123456789 \
  -H "Authorization: Bearer $MISS_BLUE_KEY"
```

Response:

```json
{
  "chat_id": "iMessage;+;chat123456789",
  "title": "Install team",
  "photo_url": "https://api.missblue.dev/v1/attachments/…/view",
  "participants": [
    { "id": "p1", "handle": "+15555550100", "name": "Ari" },
    { "id": "self", "handle": "+16465550142", "is_self": true }
  ]
}
```

### POST /v1/groups/{chat_id}/participants

Add or remove one group participant.

Set add to false to remove. The response is the complete refreshed group.

Request body:

```json
{
  "participant": "+15555550102",
  "add": true
}
```

Example:

```bash
curl -X POST https://api.missblue.dev/v1/groups/iMessage%3B%2B%3Bchat123456789/participants \
  -H "Authorization: Bearer $MISS_BLUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participant": "+15555550102",
    "add": true
  }'
```

Response:

```json
{
  "chat_id": "iMessage;+;chat123456789",
  "title": "Install team",
  "participants": [
    { "id": "p1", "handle": "+15555550100", "name": "Ari" },
    { "id": "p3", "handle": "+15555550102", "name": "Jo" },
    { "id": "self", "handle": "+16465550142", "is_self": true }
  ]
}
```