Skip to main content
The Sling Truecaller API lets you send branded messages directly to users through the Truecaller app in Nigeria. Messages appear under your registered sender name, giving recipients a verified, trusted experience. You can send to a single number, a saved contact, or an entire contact group, and choose between synchronous (instant) and asynchronous delivery modes.

​
Send a Truecaller message

curl --request POST \
  --url https://app.sling.com.ng/api/v1/send-truecaller \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {API_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "sender": "Brand",
    "to": "08140363233",
    "message": "Hello from Truecaller",
    "type": "transactional",
    "callback": "https://your-server.example.com/callback",
    "instant": false
  }'

​
Parameters

​
to
string
required
Recipient phone number. Accepts local format (without country code, where applicable), country code without +, or E.164 with + prefix — for example 08012345678, 2348012345678, +2348012345678, or +14155552671. Required unless contact or group is provided.
​
message
string
required
The message text to deliver. Maximum of 3 pages.
​
sender
string
required
Your registered sender ID. Register a sender ID on your dashboard before use.
​
type
string
Routing type for the sender ID. Accepted values: transactional or promotional.
​
callback
string
A publicly accessible URL on your server. Sling sends a POST request to this URL when the delivery status changes. Only used when instant is false. See the callbacks guide for payload details.
​
instant
boolean
Controls delivery mode. See the section below for the difference between true and false.
​
fallback_sms
boolean
When true, Sling falls back to SMS if the message cannot be delivered over Truecaller.
​
fallback_sms_sender
string
Sender ID used for the SMS fallback when fallback_sms is true. For example, Sling while your Truecaller sender is Brand.
​
contact
string
The ID of a saved contact from your Sling contact list. Use instead of to.
​
group
string
The ID of a contact group. Sends the message to every contact in the group. Use instead of to.

​
Instant vs. async delivery

The instant parameter controls whether Sling processes the message synchronously or queues it for background delivery.
Sling processes the message immediately and returns the result — success or failure — directly in the API response. Use this when you need to confirm delivery in real time before proceeding in your application logic.
{
  "sender": "Brand",
  "to": "08140363233",
  "message": "Your OTP is 482910",
  "type": "transactional",
  "instant": true
}
The response will include a status of "success" or a failure detail, allowing you to handle the outcome synchronously.

​
SMS fallback

Set fallback_sms to true and Sling will re-send the message as a standard SMS if delivery over Truecaller is not possible. Use fallback_sms_sender to set the SMS Sender ID for that fallback (for example, Sling when your Truecaller sender is Brand).
{
  "sender": "Brand",
  "to": "08140363233",
  "message": "Hello from Truecaller",
  "type": "transactional",
  "fallback_sms": true,
  "fallback_sms_sender": "Sling"
}

​
Responses

​
Success

{
  "status": "success",
  "message_id": "2bajqzt5tw",
  "sender": "Sling",
  "message": "Hello, from Sling",
  "recipient": "2349123772222",
  "credit_used": 1
}

​
Errors

{
  "status": "fail",
  "credit_used": "0",
  "details": "insufficient credit"
}

{
  "status": "fail",
  "credit_used": "0",
  "details": "The given data was invalid"
}
When instant is false, store the message_id from the response to correlate it with the callback payload your server receives when delivery completes.