## Set or clear an iMessage group photo

**post** `/api/v2/groups/{group_id}/photo`

Sets the Apple-visible photo of an existing iMessage group and waits for the
Sendblue line to verify the resulting device state. Pass `null` to clear the
photo. A set is verified only when the device-created photo transfer becomes
the chat's current photo; the verified photo is then persisted with
the group and returned on group retrieval with an image URL.

Set the photo with either a JSON `photo_url` or raw image bytes in the `file`
field of a multipart form. Images must be JPEG, PNG, or GIF, at most
5 MB, and no more than 25 million aggregate decoded pixels. URL images
must use a direct, publicly resolvable https URL; redirects
are not followed. Replacing or clearing the photo replaces the current stored
reference and attempts to delete the superseded object; no history is
exposed through the API. Supported line types are checked automatically;
ineligible lines return `unsupported_line`. Failed requests are not replayed
automatically; retrying the same desired state is safe.

By default an eligible Sendblue line in the group is selected automatically.
Pass `from_number` to require a specific Sendblue line: it must have an
iMessage mapping for this group, and if that line cannot act the request
fails without falling back to another line. The success response reports the
line that performed the change as `from_number`.

### Path Parameters

- `group_id: string`

### Body Parameters

- `photo_url: string`

  Direct, publicly resolvable https URL of the image to set (JPEG, PNG, or GIF, at most 5 MB and 25 million aggregate decoded pixels; redirects are not followed); null clears the group photo

- `from_number: optional string`

  Sendblue line that must perform the change; it must have an iMessage mapping for this group, and no other line is used if it cannot act. Omit or pass null for automatic selection

### Returns

- `data: object { from_number, group_id, group_photo }`

  - `from_number: string`

    Sendblue line that performed the change

  - `group_id: string`

  - `group_photo: GroupPhoto`

    Device-verified current photo; null after a verified clear

    - `photo_guid: string`

      Device-verified identifier of the current Apple group photo

    - `url: string`

      Direct URL for downloading the current photo; anyone with the exact URL can download it while the image exists

- `status: "OK"`

  - `"OK"`

### Example

```http
curl https://api.sendblue.co/api/v2/groups/$GROUP_ID/photo \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "photo_url": "https://example.com/team-photo.png",
          "from_number": "+15551234567"
        }'
```

#### Response

```json
{
  "data": {
    "from_number": "+15551234567",
    "group_id": "sb_group_608acc54-d0d7-4b41-8092-9ff6e1e70455",
    "group_photo": {
      "photo_guid": "AAAAAAAA-1111-2222-3333-444444444444",
      "url": "https://storage.googleapis.com/..."
    }
  },
  "status": "OK"
}
```