1. Create an API Key for User Feedback.

2. Generate the required access token.

3. Hit the below endpoint to get logs.

4. The response is a URL through which the logs can be downloaded.

Generate API Keys

1. Truecaller for Business uses API keys for authenticating API requests.

2. You can view and manage your API keys from the Truecaller for Business console.

3. Click on “Manage API Keys” from the overflow menu beside the account name in the left hand side panel of the console.

4. Click on the “Create API Key” button.

5. Enter the Key Name and Description (optional). You can see the access level underneath the description box for all available features.

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

Customers are allowed to generate 5 API keys for concurrent use at a time.

Here are some use cases for Call Personalisation APIs:

• Calling operations done through non-company owned numbers where a permanent identity cannot be listed.

• Scheduled calling operations that are run daily, where your business wants to add a clean identity and personalized call context for optimal performance.

• Calls often made from one business number to multiple users.

• Refreshing your identity on Truecaller easily, if your business has limited calling numbers.

Pre-requisites for using Call Personalisation APIs:

• Dynamic Label ID: Only “Dynamic Label IDs” can be used in the API request for placing calls. These dynamic label IDs need to be created in the Truecaller for Business console, after which the dynamic label ID can be copied from the Caller ID page in the console

• A subscription to a package that includes Call Personalisation APIs.

Integration steps:

• Create an API Key.

• Generate Access Token.

• Create a dynamic label on Truecaller for Business console:

  • Log in to the Truecaller for Business console.

  • Navigate to Business Identity in the left hand side panel.

  • Click on "Identity" and then go to the Caller ID Details section.

  • Click on "Create a Label".

  • Select the caller ID type as Dynamic Caller ID.

  • Add a logo for your dynamic caller ID. The logo should be a PNG file, with dimensions 200x200 and file size less than 2 MB.

  • Add a label name of less than 40 characters for your Dynamic Caller ID.

  • Choose the category for your business from the dropdown after creating a label name.

  • Click on "Create Caller ID' to finish creating your dynamic caller ID.

• Check the status of pushed records.

• Hit the dialer and place the call.

Access Token rate limits:

• Requests Per Minute (RPM): The maximum number of requests allowed within a one-minute time window.

• A maximum of 10 tokens can be created every 30 minutes.

This API allows you to generate access token that grants you access to Truecaller for Business endpoints.

1. Create an API Key for Call Me Back.

2. Generate the required access token.

3. Hit the below endpoint to get logs.

4. The response is a URL through which the logs can be downloaded.

Here are a few things to consider when pushing the records through the API :-

• Caller and receiver should be phone numbers without the “+” character.

• ends_at should not be before the current timestamp.

• starts_at and ends_at cannot be more than 24 hrs apart

• label_id should be that of a dynamic label belonging to this client.

• Label name and call reason are optional fields.

• Max length for label name is 40 chars

• Min length for call reason is 10 chars

• Max length for call reason is 100 chars

• starts_at and ends_at should be in milliseconds.

Rate limits

Truecaller for Business restricts API requests when you exceed the limits entitled to your business.

• Thus, if your business is using a batch based approach to push records to our systems, 10*60*500 = 300000 records can be processed every minute.

Adapting to rate-limits

• Exponential Backoff: If you receive a "429" status code, consider implementing exponential backoff for retrying requests.

• Prioritize Important Requests: If your application performs various tasks, prioritize critical requests over less essential ones to stay within limits.

Here are a few things to consider when pushing the records through the API :-

• Caller and receiver should be phone numbers without the “+” character.

• ends_at should not be before the current timestamp.

• starts_at and ends_at cannot be more than 24 hrs apart

• label_id should be that of a dynamic label belonging to this client.

• Label name and call reason are optional fields.

• Max length for label name is 40 chars

• Min length for call reason is 10 chars

• Max length for call reason is 100 chars

• starts_at and ends_at should be in milliseconds.

Rate limits

Truecaller for Business restricts API requests when you exceed the limits entitled to your business.

• Each token can handle 100 requests per second

• Maximum of 10 tokens can be created in every 30 minutes

Number management APIs are super handy for businesses that want to automate management of business numbers on Truecaller platform. These APIs come packed with features to help you handle everything, such as:

• Listing numbers as verified numbers.

• Delisting numbers that are no longer in use.

• Get information of verified number(s).

• Get feature set ID to manage numbers inside feature sets.

By using these APIs, you can make automate your number ownership and management tasks way easily, ensuring your numbers reflect their true profiles.

Just a heads up, before diving in, you'll need to:

• Generate an authentication token

• Create an API key

This ensures you get secure access and can interact with the number management services.

Feature-set ID can be fetched from the get feature-set API.

In order to notify your systems for events related to features in your enterprise plan, Webhooks (or HTTP callbacks) can be configured on the Self-serve platform.

One way of authenticating a webhook call is by including a key generated by you, as part of the webhook URL. For example, the URL could look like:

https://server.yourcompany.com/tcbiz-webhook?key=<yourkey>

Whenever there is a response to the enabled features you have set up with a webhook, we will catch it as an event. Right now, we are all set to capture Call Me Back and User Feedback events.

A webhook can be attached to one or both of the Call Me Back and User Feedback events.

Event logs for your webhooks can be found from Manage Webhooks page or Webhook events page.

1. To configure your webhooks, click on the overflow menu and click on "Manage Webhooks".

2. Click on “Create webhook” to add a new webhook.

3. Add the name of the webhook in the field provided. The name should not exceed 50 characters.

4. Add the webhook URL.

5. Select the type of webhook event (Call Me Back or User Feedback), as per your requirement.

6. Once all details have been filled, click on "Create". Your wehook has now been created.

7. You can click on "Test Webhook" to test the webhook you have created for a particular event.

A webhook can only be tested after it is created. Below are the steps to test a Webhook:

1. Click on Test Webhook on an existing webhook.

2. Choose the event to test (The current default selection is Call Me Back).

3. Click on Test URL.

To change a webhook’s configuration or to delete it, click on the overflow menu beside the Test webhook button.

We support Call Me Back and User Feedback events for webhooks. Each event has its resources that can be referred from the resource column.

Feature-set

Payload - Call Me Back

{
  "event_id": "91584c0f-32a8-11ef-a9e4-5a5798f0",
  "client_account_id": "9b7f9343-12a5-4271-b560-6daa163",
  "event_type": "cmb",
  "created_at": "1719288504",
  "cmb_payload": {
    "business_number": "0806951XXXX",
    "feature_set": "cmb",
    "client_number": "08047360",
    "requested_at": "1719288504",
    "requested_date": "26 June 2024",
    "requested_slot": "tomorrow"
  }
}

Payload - User Feedback

{
  "event_id": "d9f0c752-32a8-11ef-af53-3e643cc47",
  "client_account_id": "9b7f9343-12a5-4271-b560-6daa1638",
  "event_type": "user_feedback",
  "created_at": "1719288626",
  "survey_payload": {
    "business_number": "080698XXXXXX",
    "feature_set": "user_feedback_numbers",
    "client_number": "0804736XXXX",
    "requested_at": "1719288626",
    "user_responses": [
      {
        "question": "Did you find our services helpful?",
        "response": "Yes, very helpful!"
      }
    ]
  }
}

Number groups

Payload - Call Me Back

{
    "event_id": "15502265-74a2-4df7-a810-7b262d827",
    "client_account_id": "11f288fa-9e83-4aa5-968b-28df7ca53",
    "event_type": "cmb",
    "created_at": "1711709529734",
    "cmb_payload": {
        "business_number": "9190357XXXX",
        "number_group": "Capital City - sales",
        "client_number": "+91901906XXXX",
        "requested_at": "1711709529734",
        "requested_date": "30 Mar 2024",
        "requested_slot": "Saturday"
    }
}

Payload - User Feedback

{
  "event_id": "8140e293-c8e0-4102-bed4-5553c94f",
  "client_account_id": "11f288fa-9e83-4aa5-968b-28df7ca53",
  "event_type": "user_feedback",
  "created_at": "1711709820631",
  "survey_payload": {
    "name": "webhook_survey ",
    "business_number": "+91903571XXXX",
    "number_group": "Capital City - Support numbers",
    "client_number": "+9190190XXXXX",
    "user_responses": [
      {
        "question": "Did you find our support response helpful?",
        "response": "Yes, somewhat helpful."
      }
    ]
  }
}

There are 3 error scenarios for webhooks:

1. Webhook not found

2. Events:

   • Rescheduled error

   • Webhook Deleted

3. Webhook Failed: When webhook fails an email is sent to the user.

There are 3 timeouts for Webhooks provided by Truecaller for Business:

1. Connection Timeout: The connection timeout is the timeout for making the initial connection to the webhook URL's HTTP server.

2. Read Timeout: Once the initial connection has been made, there is a possibility that there is an indefinite wait to read data from the HTTP server at any time. The read timeout is the timeout for such a wait.

3. Total Webhook Timeout: In addition to the above timeouts, Truecaller for Business also checks the total execution of time of any webhook call via the webhook execution timeout.

The values for each timeout are as follows:

Webhook execution can fail due to timeouts or errors. For each event where webhook call fails, the calls are retried up to 7 times based on the following schedules:

This is mentioned in the event details page.