---
title: "Change an iMessage chat background"
method: POST
path: "/conversations/{conversation_id}/backdrop"
---

# Change an iMessage chat background

`POST /conversations/{conversation_id}/backdrop`

## Request

- Base URL: `https://osis.co/api/v1/comms`
- URL: `https://osis.co/api/v1/comms/conversations/{conversation_id}/backdrop`
- Auth: HTTP bearer

Experimental. Set an iMessage conversation's background to a photo or gradient, or clear it. Needs a line that supports backdrops, comms_send, and an Idempotency-Key. The recipient needs iOS 26 or another Apple OS that shows backgrounds, and a 202 doesn't mean they see it. Images can be JPEG, PNG, or WebP (not animated), up to 3 MiB, 24 megapixels, and 8192 pixels per side. They're cropped to a 1080×2340 portrait frame, and metadata is removed. To retry, send the exact same request with the same idempotency key.

## Path parameters

- `conversation_id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- union
  - object
    - `type` 'gradient', required
    - `colors` string[], required
  - object
    - `type` 'clear', required
  - object
    - `type` 'image', required
    - `image_base64` string, byte, required: The image file as plain base64, with no data: prefix. Up to 3 MiB.
    - `content_type` 'image/jpeg' | 'image/png' | 'image/webp', required
    - `crop` object: Which part of the image to use, as fractions from 0 to 1, after EXIF rotation. x + width and y + height can't go over 1. Defaults to the whole image.
      - `x` number, required
      - `y` number, required
      - `width` number, required
      - `height` number, required
    - `position` object: What stays in view if the image needs trimming to fit the portrait frame: 0 is left or top, 0.5 is center, 1 is right or bottom. Defaults to center.
      - `x` number, required
      - `y` number, required

## Response `202`

Background change accepted. Comms can't confirm what the recipient sees.

- ChatBackdropResponse
  - `conversation_id` string, required
  - `status` 'submitted' | 'unknown' | 'processing', required
  - `operation_id` string, nullable, required
  - `replayed` boolean, required
  - `recipient_applied` unknown, required

## Other responses

- `400`: Bad request, or the Idempotency-Key is missing
- `401`: API key is missing or wrong
- `402`: Your workspace has no sends left
- `403`: Your key doesn't have the scope this needs
- `404`: Not found
- `409`: The key was reused, your key is tied to a different line, or the conversation doesn't support this
- `413`: Image is over 3 MiB, or the request is over 4 MiB + 4096 bytes
- `429`: Too many requests
- `501`: This line doesn't support backgrounds
- `502`: The change failed, or Comms couldn't confirm it
- `503`: Down for a moment. Retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/osis/apis/comms-api.md) · [All operations](https://skmtc.dev/osis/apis/comms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/osis/apis/comms-api/revisions/59a4c0ba8936?raw)