> ## 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.

# Introduction to Truecaller Messaging

> Truecaller Business Chat API for templates, text, images, video, and documents

Public Truecaller APIs on `https://api-ai.zixflow.com`.

Sending is `POST /api/ingest/truecaller/...`. Template variables and delivery results are `GET /api/data/...`.

A send returns `200` when the message is queued. Delivery, media-type checks, and bot checks happen after that and show up on the delivery report.

The bot id is the Truecaller channel id from **Settings → Channels → Truecaller**.

## Endpoints

| Method | Path | Page |
| - | - | - |
| POST | `/api/ingest/truecaller/v1/template/send` | [Send a template](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/send-template.md) |
| POST | `/api/ingest/truecaller/v1/message/text/send` | [Send text](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/messages/text-message.md) |
| POST | `/api/ingest/truecaller/v1/message/image/send` | [Send an image](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/messages/image-message.md) |
| POST | `/api/ingest/truecaller/v1/message/video/send` | [Send a video](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/messages/video-message.md) |
| POST | `/api/ingest/truecaller/v1/message/document/send` | [Send a document](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/messages/document-message.md) |
| GET | `/api/data/truecaller/v1/{bot_id}/variable-keys` | [Template variable keys](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/get-template-variables.md) |
| GET | `/api/data/messages/v1/delivery-report` | [Delivery report](https://docs.zixflow.com/api-reference/zixflow-ai/messages/get-delivery-report.md) |
| GET | `/api/data/messages/v1/reports/summary` | [Report summary](https://docs.zixflow.com/api-reference/zixflow-ai/messages/get-report-summary.md) |
| GET | `/api/data/messages/v1/reports/logs` | [Report logs](https://docs.zixflow.com/api-reference/zixflow-ai/messages/get-report-logs.md) |

## Authentication

Every endpoint requires both headers. The workspace on the key must match `x-workspace-id`. See [Authentication](https://docs.zixflow.com/api-reference/zixflow-ai/authentication.md).

| Header | Required | Description |
| - | - | - |
| `x-api-key` | yes | Workspace API key |
| `x-workspace-id` | yes | Workspace id that owns that key |
| `Content-Type` | POST only | `application/json` |

Auth failures use a different body from validation failures:

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

HTTP `401`.

## Errors

Validation and handler errors (ingestion and data APIs):

```json theme={null}
{
  "success": false,
  "message": "recipient is required; bot_id is required"
}
```

Several problems are joined with `; `.

Auth, wallet, and rate-limit middleware:

```json theme={null}
{
  "error": true,
  "message": "Insufficient wallet balance"
}
```

| HTTP | When | `message` |
| - | - | - |
| 400 | Body fails the checks on the endpoint | Joined field errors |
| 400 | Wallet balance is below 0 | `Insufficient wallet balance` |
| 401 | Missing or mismatched key or workspace | `Unauthorized` |
| 404 | Template or delivery report not found | See each endpoint |
| 429 | Report summary or logs only. 10 requests/second per workspace and filter, 100 requests per 10 seconds per IP | `Too many requests` |
| 500 | Queue or database failure | `Failed to process Truecaller request`, or the endpoint's failure message |

> [!NOTE]
>
> A balance of exactly 0 is allowed at ingestion. The wallet is charged later, when the message is processed. A later wallet failure is a failed delivery report. The send has already returned HTTP `200`.

## What `200` means

Ingestion success has no `data` wrapper:

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

| Field | Type | Description |
| - | - | - |
| `success` | boolean | `true` |
| `message` | string | `Truecaller request queued successfully` |
| `request_id` | string | UUID. Use it on the delivery-report API. It is also the campaign id of the log. |

`request_id` means the message was accepted onto the queue. Poll [Get Message Delivery Report](https://docs.zixflow.com/api-reference/zixflow-ai/messages/get-delivery-report.md) with that id. A `404` can mean processing has not written the log yet.

If processing rejects the message, the log status is `failed` and `remark` carries the reason. When a status code exists it is appended as ` (Code: …)`.

| Code | Status | Meaning |
| - | - | - |
| 90103 | `INVALID_RECIPIENT_NUMBER` | Recipient could not be normalized to a phone number |
| 91401 | `INVALID_TRUECALLER_BOT_ID` | `bot_id` is missing or is not a bot in this workspace |
| 91402 | `TRUECALLER_BOT_PAUSED` | Bot status is paused |
| 91403 | `INVALID_TRUECALLER_TEMPLATE_NAME` | Template name not found, or it belongs to another bot |
| 91404 | `INVALID_TRUECALLER_MESSAGE` | Text, buttons, links, or list content failed the rules below |
| 91405 | `UNSUPPORTED_TRUECALLER_MEDIA_TYPE` | MIME type missing or not allowed for that message type |
| 91406 | `INVALID_TRUECALLER_TTL` | `ttl_seconds` outside 1 second to 28 days |
| 91407 | `UNSUPPORTED_TRUECALLER_MESSAGE_TYPE` | Type is not template, text, image, video, or document |

### Billing

Billing runs at processing time. If the recipient replied in the last 24 hours, the message is a conversation. Otherwise plain text with no buttons is outbound basic, and any media or buttons are outbound advanced. The international price is used when the recipient's country differs from the bot's country. A message that ends failed, including no delivery before the TTL, is refunded.

## Shared send fields

Present on every ingestion body.

| Field | Type | Required | Rules |
| - | - | - | - |
| `recipient` | string | yes | Phone number. Empty is rejected immediately. After queueing it is normalized with the workspace country (local numbers are accepted). An unusable number fails with `90103`. |
| `bot_id` | string | yes | Truecaller bot id. 24-character hex. Unknown or paused bots fail after queueing. |
| `ttl_seconds` | integer | no | Integer from `1` to `2419200` (28 days). Omit it to use the bot's default TTL. If that default is `0`, processing uses `86400` (24 hours). |
| `post_back_url` | string | no | Stored on the delivery log with the send. No format check. The HTTP payload of that callback is not defined by this API. |
| `post_back_data` | string | no | Stored on the delivery log with the send. |
| `api_source` | string | no | Reserved. Omit it. |

## Buttons

`buttons` is optional on text, image, video, and document sends. Maximum **3**. A template send has no `buttons` field. Buttons are part of the saved template.

Checked immediately: count, `text` length, `type`, and the field that type requires (`url`, `phone_number`, or `list.options`).

Checked after queueing: `action_tag` shape, duplicate tags, link URL shape, phone shape, and unique list option ids and titles.

```json theme={null}
{
  "type": "reply",
  "text": "Track order",
  "action_tag": "track_order"
}
```

| Field | Type | Required | Rules |
| - | - | - | - |
| `type` | string | yes | `reply`, `link`, `call`, or `list`. Any other value is `400`. |
| `text` | string | yes | 1 to 100 characters after trim. |
| `action_tag` | string | no | 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. A bad tag fails after queueing with `91404`. |
| `url` | string | link only | `https://` URL with a host, or an app deep link such as `myapp://order/1`. `http://` is rejected immediately. |
| `phone_number` | string | call only | Required and non-empty at ingestion. After queueing, spaces, `-`, `(`, and `)` are removed and the value must match `+` optional plus 5 to 15 digits. Sent to Truecaller as `tel:+...`. If `action_tag` is omitted, the tag becomes `call_1`, `call_2`, ... |
| `list` | object | list only | See below. `action_tag` on a list button is ignored. |

**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`, ... Clicks are reported by that tag.

**List** (`list` object):

| Field | Type | Required | Rules |
| - | - | - | - |
| `options` | array | yes | 1 to 10 items. |
| `options[].title` | string | yes | 1 to 100 characters. Titles must be unique, case-insensitive, after queueing. |
| `options[].id` | string | no | 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 | no | List id in the answer. Default `list_1`, `list_2`, ... Each list on the message needs its own id. |
| `title` | string | no | Sheet heading. |
| `question` | string | no | Text above the options. |
| `input_id` | string | no | Answer field id. Default `selection`. |
| `one_time_response` | boolean | no | Default `false`. `true` disables the button after the first answer. |

```json theme={null}
{
  "type": "list",
  "text": "Choose a slot",
  "list": {
    "id": "slots",
    "title": "Delivery slots",
    "question": "When should we deliver?",
    "input_id": "slot",
    "one_time_response": true,
    "options": [
      { "id": "morning", "title": "Morning" },
      { "id": "evening", "title": "Evening" }
    ]
  }
}
```

## Text

Every message has text, including image, video, and document. Truecaller rich text in that string:

```text theme={null}
*bold* _italic_ +underline+ ~strike~ `mono` [label](url)
```

| Rule | Limit |
| - | - |
| Required | Yes, including media. Whitespace alone is rejected. |
| Max length | 4096 characters (Unicode code points). |
| Template variables | See below. |

Template placeholders:

```text theme={null}
{{name}}
{{ name | default: "fallback" }}
```

A missing or empty value uses the default, otherwise an empty string. Placeholders that start with `brand.` are filled by Zixflow. The [variable-keys API](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/get-template-variables.md) leaves those keys out.

## Media

One file per message. The URL is sent to Truecaller as given. It must be a public `http://` or `https://` URL. Truecaller's file size limit is 20 MB. The file is not downloaded to measure it before queueing.

`mime_type` is optional when the URL path ends in a known extension. The extension is taken from the path, not the query string.

| Send | Allowed `mime_type` | Extensions that fill `mime_type` |
| - | - | - |
| Image | `image/jpeg`, `image/png`, `image/gif` | `.jpg`, `.jpeg`, `.png`, `.gif` |
| Video | `video/mp4`, `video/quicktime` | `.mp4`, `.mov` |
| Document | `application/pdf`, `text/plain` | `.pdf`, `.txt` |

A missing type, or a type that does not match the send (for example `video/mp4` on an image), fails after queueing with `91405`.

`file_name` is documents only, optional, shown to the recipient, at most 255 characters. Checked immediately.

## Reports

Delivery, summary, and logs use the shared message APIs. For Truecaller, `channel` is `truecaller`. Summary and logs are cached and rate limited. See [Get Message Delivery Report](https://docs.zixflow.com/api-reference/zixflow-ai/messages/get-delivery-report.md), [Get Message Reports Summary](https://docs.zixflow.com/api-reference/zixflow-ai/messages/get-report-summary.md), and [Get Message Report Logs](https://docs.zixflow.com/api-reference/zixflow-ai/messages/get-report-logs.md).


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