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	const url = 'https://api.agentphone.ai/v1/conversations/conversation_id/background';
2	const options = {
3	method: 'POST',
4	headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
5	body: '{"image_url":"https://cdn.agentphone.ai/backgrounds/chat-wallpaper-forest.png"}'
6	};
7
8	try {
9	const response = await fetch(url, options);
10	const data = await response.json();
11	console.log(data);
12	} catch (error) {
13	console.error(error);
14	}

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

1	const url = 'https://api.agentphone.ai/v1/conversations/conversation_id/background';
2	const options = {
3	method: 'POST',
4	headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
5	body: '{"image_url":"https://cdn.agentphone.ai/backgrounds/chat-wallpaper-forest.png"}'
6	};
7
8	try {
9	const response = await fetch(url, options);
10	const data = await response.json();
11	console.log(data);
12	} catch (error) {
13	console.error(error);
14	}

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