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 ParametersExpand Collapse

group_id: string

Body ParametersJSONExpand Collapse

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

ReturnsExpand Collapse

data: object { from_number, group_id, group_photo }

from_number: string

Sendblue line that performed the change

group_id: string

group_photo: GroupPhoto { photo_guid, url }

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"

Set or clear an iMessage group photo

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"
        }'

{
  "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"
}

Returns Examples

{
  "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"
}