> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zixflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Truecaller Image Message

> Send a Truecaller image with caption text and optional buttons

#### Description

Sends a JPEG, PNG, or GIF. The URL is sent to Truecaller as given and must be a public `http://` or `https://` URL. Truecaller's file size limit is 20 MB.

`mime_type` is optional when the URL path ends in `.jpg`, `.jpeg`, `.png`, or `.gif`. The extension is taken from the path, not the query string. A missing type, or a type that is not an allowed image type, fails after queueing with `91405` (`UNSUPPORTED_TRUECALLER_MEDIA_TYPE`).

A `200` means the message was queued.

#### Headers

**x-api-key** `string` *required*

Your API key for authentication. The workspace on the key must match `x-workspace-id`.

**x-workspace-id** `string` *required*

Workspace id that owns the API key.

**Content-Type** `string` *required*

`application/json`

#### Body

**recipient** `string` *required*

Phone number. An empty value is rejected immediately. After the message is queued, the number is normalized with the workspace country, so a local number is accepted. A number that cannot be normalized fails with code `90103` (`INVALID_RECIPIENT_NUMBER`).

**bot\_id** `string` *required*

Truecaller bot id from **Settings → Channels → Truecaller**. 24-character hex. An unknown bot fails after queueing with `91401` (`INVALID_TRUECALLER_BOT_ID`). A paused bot fails with `91402` (`TRUECALLER_BOT_PAUSED`).

**ttl\_seconds** `integer`

How long Truecaller keeps trying to deliver the message. Integer from `1` to `2419200` (28 days). Omit it to use the bot's default TTL. When that default is `0`, processing uses `86400` (24 hours). No delivery report by then marks the message failed. A value outside the range fails after queueing with `91406` (`INVALID_TRUECALLER_TTL`).

**post\_back\_url** `string`

Stored on the delivery log with the send. There is no format check. The HTTP body posted to this URL is not defined by this API.

**post\_back\_data** `string`

Stored on the delivery log with the send.

**image\_url** `string` *required*

Public `http://` or `https://` URL of the image.

**mime\_type** `string`

`image/jpeg`, `image/png`, or `image/gif`. Inferred from `.jpg`, `.jpeg`, `.png`, or `.gif` when omitted.

**text** `string` *required*

Required, including for media. 1 to 4096 Unicode code points. Whitespace alone is rejected.

**buttons** `array`

Optional. Maximum 3. Count, `text` length, `type`, and the field that type requires (`url`, `phone_number`, or `list.options`) are checked immediately. `action_tag` shape, duplicate tags, link URL shape, phone shape, and unique list option ids and titles are checked after queueing. A failure after queueing uses `91404` (`INVALID_TRUECALLER_MESSAGE`).

**buttons\[]**

**type** `string` *required*

`reply`, `link`, `call`, or `list`. Any other value is HTTP `400`.

**Reply.** A tap comes back as an inbound message with the button text and `action_tag`. No default tag is added.

**Link.** If `action_tag` is omitted, it becomes `link_1`, `link_2`, and so on. Clicks are reported by that tag.

**Call.** If `action_tag` is omitted, it becomes `call_1`, `call_2`, and so on.

**List.** `action_tag` on a list button is ignored.

**text** `string` *required*

1 to 100 characters after trim.

**action\_tag** `string`

Optional. If set: starts with a letter, then at least two of `a-z`, `A-Z`, `0-9`, `_`, `-` (3 characters minimum). Must not start with `tc_` (any case). Unique among buttons on the message.

**url** `string`

Required when `type` is `link`. An `https://` URL with a host, or an app deep link such as `myapp://order/1`. `http://` is rejected immediately.

**phone\_number** `string`

Required when `type` is `call`, and non-empty at ingestion. After queueing, spaces, `-`, `(`, and `)` are removed and the value must be an optional `+` plus 5 to 15 digits. Sent to Truecaller as `tel:+...`.

**list** `object`

Required when `type` is `list`.

**list**

**options** `array` *required*

1 to 10 items. Titles must be unique, case-insensitive, after queueing. Option ids must be unique after queueing.

**options\[]**

**title** `string` *required*

1 to 100 characters.

**id** `string`

Returned in the answer. If omitted, derived from the title (lowercase, non-alphanumeric runs become `_`, max 40 characters). Collisions get `_2`, `_3`. Empty titles become `option_1`.

**id** `string`

List id in the answer. Default `list_1`, `list_2`, and so on. Each list on the message needs its own id.

**title** `string`

Sheet heading.

**question** `string`

Text above the options.

**input\_id** `string` (default: selection)

Answer field id. Default `selection`.

**one\_time\_response** `boolean` (default: false)

Default `false`. `true` disables the button after the first answer.

#### Request Example

```json theme={null}
{
  "recipient": "+14155552671",
  "bot_id": "665f1c2a8e4b9a0012ab34cd",
  "image_url": "https://cdn.example.com/receipt.png",
  "mime_type": "image/png",
  "text": "Here is your receipt.",
  "buttons": [
    { "type": "reply", "text": "Thanks", "action_tag": "thanks" }
  ]
}
```

#### Response

**success** `boolean`

`true` when the message was accepted onto the queue.

**message** `string`

`Truecaller request queued successfully` on success. On validation failure, field errors joined with `; `.

**request\_id** `string`

Present when `success` is `true`. UUID. Use it on the delivery-report API.

```json 200-Success theme={null}
{
  "success": true,
  "message": "Truecaller request queued successfully",
  "request_id": "3f1c0a2e-7b64-4d1a-9c2e-1a0b8e6d4f21"
}
```

```json 401-Unauthorized theme={null}
{
  "error": true,
  "message": "Unauthorized"
}
```

```json 500-Internal Server Error theme={null}
{
  "success": false,
  "message": "Failed to process Truecaller request"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.