> ## 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 Text Message

> Send a Truecaller text message with optional buttons

#### Description

Sends a text message. Rich text and the 4096-character limit are described in the [introduction](https://docs.zixflow.com/api-reference/zixflow-ai/truecaller/introduction.md#text).

A `200` means the message was queued. Button and content rules that run after queueing fail the delivery report with `91404`.

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

**text** `string` *required*

Required. 1 to 4096 Unicode code points. Whitespace alone is rejected. Supports `*bold*`, `_italic_`, `+underline+`, `~strike~`, monospace, and `[label](url)`.

**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",
  "text": "Your order *10492* has shipped.",
  "buttons": [
    { "type": "reply", "text": "Track", "action_tag": "track_order" },
    {
      "type": "link",
      "text": "Invoice",
      "url": "https://example.com/invoices/10492",
      "action_tag": "open_invoice"
    }
  ]
}
```

#### 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 400-Bad Request theme={null}
{
  "success": false,
  "message": "recipient is required; bot_id is required"
}
```

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