Agent avatar

When a human connects to your agent, the router sends them the agent's contact card. Give the agent an avatar and the card arrives with a real contact photo — the image your humans see in Messages and in their address book after saving the card.

Upload once per identity. Inkbox normalizes every upload the same way:

• Accepts any common image format (PNG, JPEG, WebP, GIF, …) up to 5 MB.
• Transparent and near-white borders are trimmed away so your artwork fills the frame.
• Non-square images are then center-cropped to a square — the longer edges are cut evenly.
• The result is resized to 600 × 600 and stored as a JPEG; any remaining transparency is flattened onto white.

You never need to think about contact-card size limits — the normalized avatar always fits.

Avatar endpoints live under the identity, not the iMessage API:

https://inkbox.ai/api/v1/identities/{agent_handle}/avatar

An admin API key can manage any agent's avatar. An agent's own API key can manage that agent's avatar only.

PUT /identities/{agent_handle}/avatar

Upload (or replace) the avatar as a multipart form with a single file field. Replacing is atomic — the new image simply takes the old one's place.

Response (200)

Returns the full identity object; has_avatar flips to true.

JSON

Error responses

Code examples

cURL

cURL

Python

JavaScript

GET /identities/{agent_handle}/avatar

Returns the stored avatar as image/jpeg bytes — always the normalized 600 × 600 square, regardless of what was uploaded.

Error responses

Code examples

cURL

cURL

Python

DELETE /identities/{agent_handle}/avatar

Removes the avatar; future contact cards go out without a photo. Returns 204 and is idempotent — deleting when no avatar is set also returns 204.

Error responses

Code examples

cURL

cURL

The contact card a human receives from the router composes everything set on the identity: display name, the agent's number, its email address, its description (under Notes), and the avatar as the contact photo. Each piece is simply omitted when unset — an avatar is optional, but it's the difference between a gray monogram and a face for your agent.

Identity responses across the API include has_avatar so you can tell at a glance whether an agent's card will carry a photo.