Chatsv2

Set chat background

PUT/chats/{chatId}/background

Set or update the background image for a conversation. Works for both 1-on-1 and group chats.

The request body must be multipart/form-data with a single background field containing the raw image file bytes (not a URL or base64 string). Supported formats: JPEG, PNG, GIF, WebP, HEIC/HEIF. Maximum file size: 10 MB.

Example with curl — note the @ prefix that tells curl to read the file from disk:

curl -X PUT "https://api.blooio.com/v2/api/chats/%2B15551234567/background" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "background=@/path/to/image.jpg;type=image/jpeg"

When the chat id is a phone number, percent-encode the leading + as %2B in the URL path.

Path parameters

chatIdRequiredstring

Chat identifier. Can be: (1) phone number in E.164 format (e.g., +15551234567), (2) email address, (3) group ID (grp_xxxx), or (4) comma-separated list of phone numbers/emails for multi-recipient group chats (e.g., +15551234567,+15559876543). All values should be URL-encoded.

Headers

AuthorizationRequiredstring

Your API key, sent as a bearer token: Authorization: Bearer <api_key>. Editing this stays in sync with the API key box on the right.

Bearer

Body parameters

form-data

backgroundRequiredstring

Binary image file upload (JPEG, PNG, GIF, WebP, HEIC/HEIF, max 10 MB). Send as a file field in multipart/form-data — e.g. -F "background=@/path/to/image.jpg" with curl, or a File/Blob appended to FormData in JavaScript. Do NOT send a URL or base64 string.

Returns

chat_idoptionalstring

Normalized chat identifier (phone number, email, or group ID)

has_backgroundoptionalboolean

Whether the chat currently has a background set

background_idoptionalstring | null

Unique identifier for the current background, or null if none

background_urloptionalstring | null

Public URL of the persisted background image stored in R2. Returned after a successful PUT and on GET when a background has been set through the API. May be null if persistence failed or the background was set outside of the API.

background_versionoptionalinteger | null

Version number of the background (for cache invalidation)

changedoptionalboolean

Whether the background was changed by this operation (only present on PUT)

Response codes

200Chat background set successfully

400Invalid request parameters

401Authentication required or invalid

502Failed to set background on device

503No active number available

Sends a live request with your values and shows the real response below. Your key is stored only in this browser.

Request

curl -X PUT https://api.blooio.com/v2/api/chats/chat_a1b2c3d4/background \  -H "Authorization: Bearer bl_live_..." \  -F "file=@/path/to/file"

Response objectexample

{  "chat_id": "chat_a1b2c3d4",  "has_background": true,  "background_id": "obj_a1b2c3d4",  "background_url": "https://example.com",  "background_version": 0,  "changed": false}