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

> Send a saved Truecaller template by name

#### Description

Sends a saved template by name. The template must belong to `bot_id`. Variables replace placeholders in the template text, media URL, and links.

A template send has no `buttons` field. Buttons are part of the saved template.

`variables` must be present. `{}` is valid when the template has no caller variables. Keys are the names from [Template variable keys](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/get-template-variables.md), without braces. Placeholders that start with `brand.` are filled by Zixflow and are left out of that list.

A `200` means the message was queued. See [Introduction](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/introduction.md) for auth errors, wallet checks, processing codes, and billing.

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

**template\_name** `string` *required*

Name of the template on that bot. An unknown name, or a template that belongs to another bot, fails after queueing with `91403` (`INVALID_TRUECALLER_TEMPLATE_NAME`).

**variables** `object` *required*

Object of string to string. Must be present. `{}` is valid when the template has no caller variables. Keys are the names from the variable-keys API, without braces.

#### Request Example

```json theme={null}
{
  "recipient": "+14155552671",
  "bot_id": "665f1c2a8e4b9a0012ab34cd",
  "template_name": "order_shipped",
  "ttl_seconds": 86400,
  "variables": {
    "order_id": "10492",
    "name": "Ada"
  },
  "post_back_url": "https://example.com/hooks/truecaller",
  "post_back_data": "order-10492"
}
```

#### 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. It is also the campaign id of the log.

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

```json 400-Bad Request theme={null}
{
  "success": false,
  "message": "template_name is required"
}
```

```json 400-Variables theme={null}
{
  "success": false,
  "message": "variables must be provided (can be empty map)"
}
```

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

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

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