Set Chat Background | AgentPhone

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

conversation_idstringRequired

Request

This endpoint expects an object.

image_urlstringRequired

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

Successful Response

conversationIdstring

channelstring

hasBackgroundboolean

changedboolean

backgroundIdstring or null

backgroundVersioninteger or null

Errors

422

Unprocessable Entity Error

1	import { AgentPhoneClient } from "agentphone";
2
3	async function main() {
4	const client = new AgentPhoneClient({
5	token: "YOUR_TOKEN_HERE",
6	});
7	await client.conversations.setChatBackground("conversation_id", {
8	imageUrl: "https://cdn.agentphone.ai/backgrounds/chat-wallpaper-forest.png",
9	});
10	}
11	main();

1	{
2	"conversationId": "conv_9f8b7c6d5e4a3b2c1d0e",
3	"channel": "iMessage",
4	"hasBackground": true,
5	"changed": true,
6	"backgroundId": "bg_123456789abcdef",
7	"backgroundVersion": 3
8	}