---
title: "Set Chat Background"
method: POST
path: "/v1/conversations/{conversation_id}/background"
tags: ["conversations"]
---

# Set Chat Background

`POST /v1/conversations/{conversation_id}/background`

Set a custom wallpaper for the chat (iMessage only).

Customer sends `image_url`; we fetch (≤10MB, JPEG/PNG/GIF/WebP/HEIC),
validate, and forward as multipart to the iMessage provider. Idempotent —
re-setting replaces. Recipients on iOS < 18 fall back to the default
silently.

## Path parameters

- `conversation_id` string, required

## Request body

- SetBackgroundRequest
  - `image_url` string, required — HTTPS URL of the background image. JPEG/PNG/GIF/WebP/HEIC, max 10MB. Recipients on iOS < 18 see the default background; no error is raised.

## Response `200`

Successful Response

- SetBackgroundResponse
  - `conversationId` string, required
  - `channel` string, required
  - `hasBackground` boolean, required
  - `backgroundId` string, nullable
  - `backgroundVersion` integer, nullable
  - `changed` boolean, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agentphone/apis/agentphone-api.md) · [All operations](https://skmtc.net/agentphone/apis/agentphone-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentphone/agentphone-api/versions/3f3aa65dcd20/schema)