Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This page will guide us on how we can use the Bulk API for Verified Campaigns
If you suspect your webhook token has been compromised, you can easily regenerate a new token within the business console.
Navigate to webhook setup:
This API is used to generate an access token using the Key ID and Secret API Key created from the Manage API Keys page
Validity of the auth token is 60min ,post that we need to recall the API for fresh auth token value.
Replace the {{BaseURL}} with the one mentioned
To help you stay informed about events related to the features in your enterprise plan, you can easily configure Webhooks (also known as HTTP callbacks) directly on our Self-serve platform. This ensures your systems are automatically notified, keeping you seamlessly updated.
Should you wish to learn more about how webhooks can benefit your operations, please don't hesitate to contact us at: [email protected]. We'd be happy to assist you!
Return to the "Webhook Setup" page within the Verified Campaigns section of the business console.
Regenerate token:
Look for a button labeled "Regenerate Webhook Token" on the page below your webhook token section. Click on it to initiate the regeneration process.
Copy and update:
A new webhook token will be generated and displayed on the screen.
Securely copy this new token and update the configuration of any applications or systems that were using the previous token.
POST {{BaseURL}/organisations/{organisationid}/campaigns/token {organisationid}: This can be taken directly from the self serve portal under the API Setup Page
Headers
X-Public-Access
allow
Required
Body
api_key
string
Required API key from the API Set up Page
key_id
string
Required Key ID from the API Setup Page
Pre-requisites for using Verified Campaigns :
An active subscription of Truecaller Customer Experience Solution for your business
Integration Steps :
Log into your Truecaller for Business account.
Configure a webhook token for your organization.
Copy the relevant details from your account - Webhook Endpoint URL, Organization ID and Token.
Set up "Truecaller" as a new channel of communication on your Customer Engagement Platform, in-house audience definition tool or CRM platform.
Copy the following within Truecaller for Business console's webhook setup page.
Webhook Endpoint URL:
{
"api_key": "9325a824-8a9b-4684-99d3-33c10b8ae1d3",
"key_id": "ad1c032c-2856-4cf8-9b1f-20b555b610d7"
}{
"token": "a4p0sTtfFbsSfRlm4_CazHEbv0guHq4u0tID1TTe4CX4KIu_20BMgI0Bc7qXdmr7",
"created_at": "2025-08-19T06:27:31.193Z"
}{
"slug": "authorization-error",
"message": "Missing authorization header"
}Upload your marketing assets via your Truecaller for Business console.
Define specific template parameters to personalize the message to be shown to your target users (Refer to Template Styles to know more about available templates).
That's it! You have now set up a webhook connector to send the audience data to Truecaller for Business backend service.
Verified Campaigns will start showing up on Truecaller user device's based on specified parameters and when a Verified Business call or message lands on their device.
This is the address (URL) where you will push your segment and template parameters to.
Action: Copy this URL and paste it into the webhook configuration section of your external CX system.
Organization ID:
This is a unique identifier assigned to your organization within the Truecaller for Business system. It's a 16 digit UUID.
Action: Copy this ID. You'll need to include it in the authentication headers of your webhook requests to verify that you're authorized to receive the notifications.
Key-Value Pair Format : X-Org-ID: [Your Organization ID]
Webhook Token:
This token is used for authenticating your webhook requests to ensure secure communication between your system and Truecaller's backend service.
Action: Copy the webhook token and include it in the headers of your requests as an additional security measure.
Key-Value Pair Format: X-Org-Token: [Your Webhook Token]
Truecaller for Business uses API keys for authenticating API requests.
You can view and manage your API keys from the True caller for Business console.
Click on “API Setup” from the left-hand rail in the account under "Connectors"
Click on the “Create API Key” button.
Enter the Key Name and Description (optional). You can see the access level underneath the description box for all available features.
Click on “Generate”. This will take you to the screen which has the option to copy/save the Key ID and Secret API Key. This file should be downloaded and kept securely.
Display your campaigns directly on your Business Page to engage users with targeted content whenever they view your verified identity. Reinforce your messaging through branded visuals, CTAs, and offers—right where users come to learn more about your business.
Below are the required payload parameters for each Template Style on the Universal ACS screen :
profile section parameters are Mandatory for all webhook payloads :
A total of 5 webhooks can be configured under a customer account at a given point in time.
To configure your webhooks, simply follow these steps:
Access Webhook : Click on Manage Webhooks under Verified Campaigns
40 characters MAX; supports 2 lines
40 characters MAX; supports 2 lines
Sub Title
60 characters MAX; supports 2 lines
NA
60 characters MAX; supports 2 lines
60 characters MAX; supports 2 lines
CTA
15 characters MAX; supports 1 line
NA
15 characters MAX; supports 1 line
15 characters MAX; supports 1 line
Image Dimensions
NA
W 320 x H 140
W 100 x H 140
W 100 x H 140
Image File Format
NA
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
Image File Size
NA
>150 KB
>150 KB
>150 KB
Redirection
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Image File Hosting
NA
CDN bucket
CDN bucket
CDN bucket
Local Lannguage Support
Yes
Yes
Yes
Yes
PDU Aspect Ratio
320x140
320x140
320x140
320x140
Title
40 characters MAX; supports 2 lines
NA
40 characters MAX; supports 2 lines
40 characters MAX; supports 2 lines
Sub Title
60 characters MAX; supports 2 lines
NA
60 characters MAX; supports 2 lines
60 characters MAX; supports 2 lines
CTA
NA
NA
NA
NA
Image Dimensions
NA
W 320 x H 140
W 100x H 140
W 100x W 140
Image File Format
NA
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
Image File Size
NA
>150 KB
>150 KB
>150 KB
Redirection
None
None
None
None
Image File Hosting
NA
CDN bucket
CDN bucket
CDN bucket
Local Lannguage Support
Yes
Yes
Yes
Yes
PDU Aspect Ratio
320x140
320x140
320x140
320x140
Title
40 characters MAX; supports 2 lines
NA
campaign_id : External campaign reference ID
receiver_number : Phone numbers of the end user to whom the communication should be delivered.
content section parameters can vary based on display_unit and template_style as follows : * means mandatory
“display_unit”*
“display_unit”*
“display_unit”*
“display_unit”*
"title"*
"deeplink"*
"title"*
"title"*
"sub_title"*
Enter Webhook Details:
Webhook Name: Provide a descriptive name for your webhook in the designated field. This name will be used to identify the webhook within the Truecaller for Business console. Please ensure the name is unique at any given time and does not exceed 50 characters.
Webhook URL: Enter the endpoint to which Truecaller should send the webhook notifications. For enhanced security, you might consider including a self-generated key as part of your URL (e.g., https://server.yourcompany.com/tcbiz-webhook?key=<yourkey>).
Select Event Type: Choose the specific type of webhook event you wish to receive notifications for. Currently, webhooks are available for Verified Campaigns-Detailed Whenever a response occurs for these enabled features, we will capture it as an event and send it to your configured URL.
You can review event logs for your webhooks on both the "Manage Webhooks" page and the dedicated "Webhook events" page. Detailed information for each event is available on its respective event details page, with logs retained for the last 30 days.
Finalize Creation: Once all the required details are filled, click "Create." Your webhook will now be successfully set up.
Test Your Webhook : After creation, you can test your webhook to ensure it's functioning correctly.
Click on "Test Webhook" next to an existing webhook.
Select the event you wish to test (the default is "Call Me Back").
Click "Test URL" to send a test notification.
This endpoint pushes the campaign details to the respective TC users.
Maximum 500 campaigns can be pushed in a single API call
Replace the {{BaseURL}} with the one mentioned here
POST {{BaseURL}/organisations/{organisationid}/campaigns/bulk-upload
{organisationid} : This can be taken directly from the self serve portal under the API Setup Page
Headers
Body
In case of single object we can pass it as a raw json and we need not add the request in the file format.
File in below format -for multiple user records
Response
Display your campaign when users receive calls from your verified number, ensuring high visibility and engagement. This touchpoint allows you to present important messages directly during incoming calls, enhancing user awareness of your brand
Below are the required payload parameters for each Template Style on the Caller ID screen :
profile section parameters are Mandatory for all webhook payloads :
campaign_id : External campaign reference ID
receiver_number : Phone numbers of the end user to whom the communication should be delivered.
content section parameters can vary based on display_unit and template_style selected as follows : * means mandatory
Generate campaign payload using the DIY tool on the business console or follow the documentation.
Navigate to the "Verified Campaigns" section within your business console and click on "Template Generator" option
Step 1: Campaign identifiers and use case
Campaign Name: Enter the name of your campaign.
Display your campaign on a sticky pop-up that shows up for Truecaller users after a call ends on the user's device. Leverage this touchpoint to reinforce your messaging with a highly engaging visual that appears immediately after the conversation, capturing user attention right when it matters.
Below are the required payload parameters for each Template Style on the Universal ACS screen :
profile section parameters are Mandatory for all webhook payloads :
Display your campaign on a sticky pop-up that shows up for Truecaller users when the user misses or rejects your call. Leverage this touchpoint to communicate with your customers with a custom campaign when they fail to receive your call.
Below are the required payload parameters for each Template Style on the Missed Call screen :
profile section parameters are Mandatory for all webhook payloads :
CleverTap :
Message ID is a sticky notification that comes up for Truecaller users, capturing their attention for every transactional notification they receive. This touchpoint not only ensures timely and relevant messaging but also delivers business outcomes by enhancing user engagement and interaction with your brand.
Below are the required payload parameters for each Template Style on the Message ID screen :
profile section parameters are Mandatory for all webhook payloads :
"ttl"
"sub_title"*
"sub_title"*
"call_to_action"*
"call_to_action"*
"call_to_action"*
"deeplink"*
"deeplink"*
"deeplink"*
"ttl"
"ttl"
"ttl"
"sub_title"*
"sub_title"*
"ttl"
"ttl"
"ttl"
“display_unit”*
“display_unit”*
“display_unit”*
“display_unit”*
"title"*
"ttl"
"title"*
"title"*
"sub_title"*
WebEngage :
Segment by Twilio :
contents
array of object
min:1 max: 5
Depends on the number of touchpoints set up in selfserve portal
display_unit
string
enums cid
acs-answered
acs-missed-rejected mid
business-profile
The display unit where the campaign will be played
deeplink
string
valid link
The external link to which the request should be routed
ttl
string
min:1 max: 365
Time to live (in days)
Content-Type
Required
application/json
Authorization
Required
Bearer <token>
campaigns
array of objects
min:1 max: 500
Campaign Details Object
campaign_id
string
min:1 max: 500
This can be taken from the self serve portal under the Campaigns tab
receiver_number
string
NA
Receiver Number,
It is a 12 digit number with country code and without + sign ,also we can pass the number in the SHA256 format ,it also should be a 12 digit number with country code but without + sign
{
"message": "Payload received successfully for processing"
}{
"slug": "internal-server-error",
"message": "500/50011 - Failed to parse token"
}Campaign ID: Enter your campaign's unique identifier, this could be the same external campaign reference or campaign ID that you use in your external system
Campaign Type: Select the relevant type (Lifecycle or Offer).
Step 2: Choose your Display Unit
Select the display unit(s) where your campaign will run:
Caller ID: The incoming pop-up shown when a call is incoming on a user device.
Post Call Pop-up (Universal): The pop-up displayed after a call is answered., missed or rejected.
Missed Call Pop-up : The pop-up shown after a missed call.
Sticky Message ID: The UI shown for transactional message notifications
Business Profile : The brand page on the Truecaller app/
Each display unit may have different template style options available.
Step 3: Configure Campaign template
Dynamic Fields : For each selected Display Unit and Template Style the parameters of customization are different.
Custom Fields: Enter the campaign message content (title, subtitle, CTA, deeplink, etc.) based on the chosen display unit and template style chosen.
Static Fields : These are stored and saved in our backend mapped to your Campaign ID
Text Color: Choose a text color that works best with your brand image (Black or White).
Template Theme: Select a brand color for the template theme.
Brand Image: Host your marketing assets on Truecaller Assets page (Note : Adhere to recommended dimensions and image storage requirements).
Save and Generate JSON: Click this button when you're satisfied with your template.
Step 4: JSON Generator
JSON Payload: A formatted JSON payload, based on your template and selections, will be displayed. This payload adheres to the required format for Truecaller's Verified Campaigns Webhook endpoint.
Copy: Click the "Copy" button to copy the JSON payload to your clipboard.
Important Notes:
campaign_id : External campaign reference ID
receiver_number : Phone numbers of the end user to whom the communication should be delivered.
content section parameters can vary based on display_unit and template_style as follows : * means mandatory
“display_unit”*
“display_unit”*
“display_unit”*
“display_unit”*
"title"*
"deeplink"*
"title"*
"title"*
"sub_title"*
campaign_id : External campaign reference ID
receiver_number : Phone numbers of the end user to whom the communication should be delivered.
content section parameters can vary based on display_unit and template_style as follows : * means mandatory
“display_unit”*
“display_unit”*
“display_unit”*
“display_unit”*
"title"*
"deeplink"*
"title"*
"title"*
"sub_title"*
campaign_id : External campaign reference ID
receiver_number : Phone numbers of the end user to whom the communication should be delivered.
content section parameters can vary based on display_unit and template_style as follows : * means mandatory
“display_unit”*
“display_unit”*
“display_unit”*
“display_unit”*
"title"*
"deeplink"*
"title"*
"title"*
"call_to_action"*
PDU Aspect Ratio
320x100
320x100
320x100
320x100
Title
40 characters MAX; supports 2 lines
PDU Aspect Ratio
320x140
320x140
320x140
320x140
Title
40 characters MAX; supports 2 lines
PDU Aspect Ratio
320x140
320x140
320x140
320x140
Title
40 characters MAX; supports 2 lines
"ttl"
"sub_title"*
"sub_title"*
"call_to_action"*
"call_to_action"*
"call_to_action"*
"deeplink"*
"deeplink"*
"deeplink"*
"ttl"
"ttl"
"ttl"
"ttl"
"sub_title"*
"sub_title"*
"call_to_action"*
"call_to_action"*
"call_to_action"*
"deeplink"*
"deeplink"*
"deeplink"*
"ttl"
"ttl"
"ttl"
"ttl"
"call_to_action"*
"call_to_action"*
"deeplink"*
"deeplink"*
"deeplink"*
"ttl"
"ttl"
"ttl"
NA
40 characters MAX; supports 2 lines
40 characters MAX; supports 2 lines
Sub Title
NA
NA
NA
NA
CTA
15 characters MAX; supports 1 line
NA
15 characters MAX; supports 1 line
15 characters MAX; supports 1 line
Image Dimensions
NA
W 320 x H 100
W 100 x H 100
W 100 x H 100
Image File Format
NA
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
Image File Size
NA
>150 KB
>150 KB
>150 KB
Redirection
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Image File Hosting
NA
CDN bucket
CDN bucket
CDN bucket
Local Lannguage Support
Yes
Yes
Yes
Yes
NA
40 characters MAX; supports 2 lines
40 characters MAX; supports 2 lines
Sub Title
60 characters MAX; supports 2 lines
NA
60 characters MAX; supports 2 lines
60 characters MAX; supports 2 lines
CTA
15 characters MAX; supports 1 line
NA
15 characters MAX; supports 1 line
15 characters MAX; supports 1 line
Image Dimensions
NA
W 320 x H 140
W 100 x H 140
W 100 x H 140
Image File Format
NA
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
Image File Size
NA
>150 KB
>150 KB
>150 KB
Redirection
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Image File Hosting
NA
CDN bucket
CDN bucket
CDN bucket
Local Lannguage Support
Yes
Yes
Yes
Yes
NA
40 characters MAX; supports 2 lines
40 characters MAX; supports 2 lines
Sub Title
60 characters MAX; supports 2 lines
NA
60 characters MAX; supports 2 lines
60 characters MAX; supports 2 lines
CTA
15 characters MAX; supports 1 line
NA
15 characters MAX; supports 1 line
15 characters MAX; supports 1 line
Image Dimensions
NA
W 320 x H 140
W 100 x H 140
W 100 x H 140
Image File Format
NA
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
.jpeg, .png and .gif supported
Image File Size
NA
>150 KB
>150 KB
>150 KB
Redirection
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Landing page on mobileweb browser or app deeplink supported
Image File Hosting
NA
CDN bucket
CDN bucket
CDN bucket
Local Lannguage Support
Yes
Yes
Yes
Yes
UUID / String
Unique identifier for the user event. This groups all related actions for a single campaign interaction. To be generated from BE.
No
reference_id
String
Mapped as an external reference to a user phone number. Can be in following formats :
The raw 12 digit phone number (with 2-digit country code) of the user who saw the campaign impression.
The SHA256 hashed value of the 12 digit phone number (with 2-digit country code) of the user who saw the campaign impression.
The reference_id of the user who saw the campaign impression; mapped to the optional reference_id field in the Payload Exchange API
Yes
organisation_id
String
Identifier for the Organisation associated with the event.
No
campaign_id
String
Identifier for the campaign associated with the event.
No
display_unit
String
Identifier for the display unit where the event was served.
No
impression_timestamp
Timestamp
The exact date and time when the impression was served.
No
click_timestamp
Timestamp (Optional)
The exact date and time when the click event occurred. Only populated if a click happened.
No
business_number
String
The business phone number/sender id which triggered the campaign to the end user.
No
event_id
// Event Structure for Clickstream - Detailed Events
{
"event_id": "DfK910987654321SNJ",
"reference_id": "911234567890",
"organisation_id": "HHSDFZX1234592828SJ299",
"campaign_id": "Test_campaign",
"display_unit": "business-profile",
"impression_timestamp": "1754116200",
"click_timestamp": "1754118000",
"business_number": "9122245644890"
}// Event Structure for Clickstream - Click Events
{
"event_id": "DfK910987654321SNJ",
"reference_id": "911234567890",
"organisation_id": "HHSDFZX1234592828SJ299",
"campaign_id": "Test_campaign",
"display_unit": "business-profile",
"impression_timestamp": "1754116200",
"click_timestamp": "1754118000",
"business_number": "9122245644890"
}