Send a message

Send one Truecaller message now: free text, an approved template, or either with an image, file and buttons.

POST /v1/messages

cURL

template

curl --request POST \
  --url https://truecaller.udchowdhury.me/v1/messages \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "to": "919999999999",
  "template_id": "7f3c2a9e-1b2d-4c5e-8f90-123456789abc",
  "variables": {
    "name": "Asha",
    "order_id": "OX1002"
  }
}
'

202

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": "[phone]",
  "sender_id": "<string>",
  "category": "promotional",
  "template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "body": "<string>",
  "extras": {},
  "status": "queued",
  "error": null,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "events": [
    {
      "status": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ]
}

Use this for one-off messages such as OTP follow-ups, order updates or a test of a template. For many people at once, use a campaign instead: it applies opt-outs and promotional limits for you.

Give either body or template_id:

• template_id sends an approved template. Its media and buttons come with it. Fill its {{variables}} with variables; any you leave empty use the template’s defaults.
• body sends free text. Add media and up to 3 buttons if you need them.

A 202 means Truecaller accepted the message (status: "sent"). Delivery and read come later: subscribe to webhooks or get the message.

If the number is not on Truecaller, the send fails with Truecaller NOT_FOUND. That is the most common failure and is not worth retrying.

Authorizations

x-api-key · string · header · required

Workspace API key from Developers → API keys. It starts with tc_live_.

Body

application/json

to · string · required

Recipient number with country code ([phone] or 919999999999). Bare 10-digit numbers are treated as Indian.

Example:

"919999999999"

sender_id · string

One of the workspace's active senders. Defaults to the first active sender.

body · string

Free text. Supports bold, italic, strikethrough, monospace and label [blocked] links. Give this or template_id.

Maximum string length: 1000

category · enum<string> · default: transactional

For free-text sends. A template uses its own category.

Available options: promotional, transactional, service

template_id · string<uuid>

An approved template. Give this or body.

variables · object

Values for the template's variables. Empty ones fall back to the template's defaults.

Show child attributes

media · object

One attachment. Upload with Upload media, or give any public https URL.

Show child attributes

buttons · (Link button · object | Quick reply · object)[]

Maximum array length: 3

Up to 3 per message. Labels and URLs can use {{variables}}.

Link button

Quick reply

Show child attributes

Response

202

application/json

Accepted by Truecaller.

id · string<uuid>

to · string

Example:

"[phone]"

sender_id · string

category · enum<string>

Available options: promotional, transactional, service

template_id · string<uuid> | null

campaign_id · string<uuid> | null

body · string

extras · object | null

Media and buttons sent with the message.

status · enum<string>

sent means Truecaller accepted it, blocked means a limit or opt-out skipped it.

Available options: queued, sent, delivered, read, failed, blocked

error · string | null

Example:

null

created_at · string<date-time>

updated_at · string<date-time>

events · object[]

Show child attributes