Campaign API - TingTing

The Campaign API lets you create and manage bulk voice and SMS campaigns, add contacts, configure voice models, and track call outcomes. All requests require a valid Bearer token in the Authorization header. See Authentication to get your token.

Before creating a campaign, call the List Voice Models endpoint to get the available voice IDs. You’ll need a voice ID when configuring your campaign message.

List voice models

GET https://app.tingting.io/api/v1/voice-models/ Returns all available AI voices you can use in your campaigns.

Response fields

number

required

Unique identifier for the voice model. Use this value as the voice parameter when creating or updating a campaign.

voice_display_name

string

required

Human-readable name for the voice.

voice_internal_name

string

required

The voice identifier used in OTP requests (e.g. "np_rija").

is_premium

boolean

required

Whether this voice requires a premium subscription.

Example

curl --request GET \
  --url https://app.tingting.io/api/v1/voice-models/ \
  --header 'Authorization: Bearer YOUR_TOKEN'

Response

[
  { "id": 1, "voice_display_name": "Rija", "voice_internal_name": "np_rija", "is_premium": false },
  { "id": 2, "voice_display_name": "Rija premium", "voice_internal_name": "np_rija", "is_premium": true },
  { "id": 3, "voice_display_name": "Prashanna", "voice_internal_name": "np_prashanna", "is_premium": false },
  { "id": 4, "voice_display_name": "Binod", "voice_internal_name": "np_binod", "is_premium": false },
  { "id": 5, "voice_display_name": "Shreegya", "voice_internal_name": "np_shreegya", "is_premium": false }
]

List campaigns

GET https://app.tingting.io/api/v1/campaign/ Returns a paginated list of all your campaigns.

Query parameters

limit

number

default:"10"

Number of results to return per page.

offset

number

default:"0"

Number of results to skip before returning results.

status

string

Filter campaigns by status. Accepted values: Not Started, Completed, Terminated, Running, Scheduled.

Example

curl --request GET \
  --url 'https://app.tingting.io/api/v1/campaign/?limit=10&offset=0&status=Completed' \
  --header 'Authorization: Bearer YOUR_TOKEN'

Response

{
  "count": 2,
  "total_pages": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 858,
      "name": "rockabye",
      "services": "PHONE",
      "status": "Completed",
      "sms_message": "",
      "message": "नमस्ते तिङ्तिङ् मा स्वागत् छ ",
      "description": "",
      "schedule": null,
      "audio_file": null,
      "bulk_file": null,
      "category": "Text",
      "user_phone": [12],
      "campaign_action_count": 4,
      "progress_percent": 100,
      "updated_at": "2025-07-07T11:38:24.219065+05:45",
      "credit_limit": null,
      "voice": {
        "id": 5,
        "voice_display_name": "Shreegya",
        "voice_internal_name": "np_shreegya",
        "is_premium": false
      },
      "draft": false,
      "failover_target": [],
      "length_factor": "1.00"
    }
  ]
}

Get campaign details

GET https://app.tingting.io/api/v1/campaign/{campaign_id}/ Returns the full details for a single campaign.

Path parameters

campaign_id

number

required

The ID of the campaign to retrieve.

Example

curl --request GET \
  --url https://app.tingting.io/api/v1/campaign/79/ \
  --header 'Authorization: Bearer YOUR_TOKEN'

Response

{
  "id": 79,
  "name": "example test campaign example",
  "services": "SMS & PHONE",
  "status": "Not Started",
  "sms_message": "नमस्ते तिङ्तिङ् म स्वागत् छ ",
  "message": "नमस्ते तिङ्तिङ् म स्वागत् छ ",
  "description": "Test message",
  "schedule": "2025-07-09T00:00:00+05:45",
  "audio_file": null,
  "bulk_file": null,
  "category": "example category",
  "user_phone": [3],
  "campaign_action_count": 1,
  "progress_percent": 0,
  "updated_at": "2025-07-07T14:01:50.508344+05:45",
  "credit_limit": 100,
  "voice": 3,
  "draft": false,
  "failover_target": [],
  "length_factor": "1.00"
}

Create a campaign

POST https://app.tingting.io/api/v1/campaign/create/ Creates a new campaign. After creating the campaign, use the sub-endpoints below to configure the voice, add contacts, and then run the campaign.

You can use dynamic tags in your message and sms_message fields using curly brace syntax — for example, {name}, {age}, or {salary}. TingTing fills in these variables per contact when the campaign runs. For example: "नमस्कार, {tags_name}, हजुर {tags_age} वर्षको हुनुहुन्छ".

Request body

name

string

required

A display name for your campaign.

services

string

required

The delivery channel for the campaign. Accepted values: PHONE, SMS, SMS & PHONE.

user_phone

number[]

required

Array of phone group IDs to include in this campaign.

message

string

required

The voice message text. Supports dynamic tags using {variable_name} syntax.

sms_message

string

The SMS message text. Required when services is SMS or SMS & PHONE. Supports the same dynamic tag syntax as message.

description

string

An optional description for your own reference.

schedule

string

ISO 8601 date or datetime string for when the campaign should start (e.g., "2025-07-08" or "2025-07-08T14:00:00"). If omitted, the campaign runs immediately when you call the Run Campaign endpoint.

voice

number

Voice model ID from List Voice Models.

credit_limit

number

Maximum number of credits to spend on this campaign. The campaign stops when the limit is reached.

Example

curl --request POST \
  --url https://app.tingting.io/api/v1/campaign/create/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "example test campaign",
    "services": "PHONE",
    "user_phone": [3],
    "message": "नमस्ते तिङ्तिङ् मा स्वागत् छ",
    "sms_message": "नमस्ते तिङ्तिङ् मा स्वागत् छ",
    "description": "Test message",
    "schedule": "2025-07-08"
  }'

Response

{
  "id": 79,
  "name": "example test campaign",
  "services": "PHONE",
  "status": "Not Started",
  "sms_message": "नमस्ते तिङ्तिङ् मा स्वागत् छ",
  "message": "नमस्ते तिङ्तिङ् मा स्वागत् छ",
  "description": "Test message",
  "schedule": "2025-07-08T00:00:00+05:45",
  "audio_file": null,
  "bulk_file": null,
  "category": null,
  "user_phone": [3],
  "campaign_action_count": 0,
  "progress_percent": 0,
  "updated_at": "2025-07-07T14:01:50.508344+05:45",
  "credit_limit": null,
  "voice": null,
  "draft": false,
  "failover_target": [],
  "length_factor": "1.00"
}

Set voice and category

PATCH https://app.tingting.io/api/v1/campaign/create/{campaign_id}/message/ Assigns a voice model and sets the message category for a campaign. Call this after creating the campaign.

Path parameters

campaign_id

number

required

The ID of the campaign to configure.

Request body

voice

number

required

Voice model ID from List Voice Models.

Example

curl --request PATCH \
  --url https://app.tingting.io/api/v1/campaign/create/79/message/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"voice": 3, "category": "Text"}'

Response

{
  "voice": 3,
  "sms_message": "नमस्ते तिङ्तिङ् मा स्वागत् छ",
  "message": "नमस्ते तिङ्तिङ् मा स्वागत् छ",
  "category": "Text",
  "draft": false,
  "length_factor": "1.00"
}

Add a single contact

POST https://app.tingting.io/api/v1/campaign/{campaign_id}/add-contact/ Adds a single phone number to a campaign. You can optionally provide custom variable values for dynamic tags used in the campaign message.

Path parameters

campaign_id

number

required

The ID of the campaign to add the contact to.

Request body

number

required

The phone number to add to the campaign.

other_variables

object

Key-value pairs matching the dynamic tags in your campaign message. For example, if your message contains {name} and {age}, provide {"name": "Rajesh", "age": 23}.

Example

curl --request POST \
  --url https://app.tingting.io/api/v1/campaign/79/add-contact/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": 9823561098,
    "other_variables": {"age": 23, "name": "Rajesh", "salary": 50000}
  }'

Response

{
  "message": "New Contact added"
}

Add multiple contacts

POST https://app.tingting.io/api/v1/campaign/{campaign_id}/add-contact/ Adds multiple phone numbers in a single request using the contacts array. Contacts that already exist in the campaign are skipped.

Path parameters

campaign_id

number

required

The ID of the campaign to add contacts to.

Request body

contacts

object[]

required

Array of contact objects to add. Each object must include number and optionally other_variables.

Example

curl --request POST \
  --url https://app.tingting.io/api/v1/campaign/79/add-contact/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "contacts": [
      {"number": "9841234567", "other_variables": {}},
      {"number": "9841234568"},
      {"number": "9841234569", "other_variables": {"name": "Jane"}}
    ]
  }'

Response

{
  "created": 3,
  "skipped": 0,
  "contacts": [
    {"number": "9841234567"},
    {"number": "9841234568"},
    {"number": "9841234569"}
  ],
  "errors": []
}

Upload bulk contacts

PATCH https://app.tingting.io/api/v1/campaign/create/{campaign_id}/detail/ Uploads an Excel file (.xlsx) containing contacts and their custom variable values. The API validates the file and returns a preview of column names, sample values, and the total number of valid rows.

Path parameters

campaign_id

number

required

The ID of the campaign to upload contacts to.

Request body

bulk_file

file

required

An .xlsx file. Each row represents a contact. Include a column for the phone number and additional columns for any dynamic tag variables used in your campaign message.

Example

curl --request PATCH \
  --url https://app.tingting.io/api/v1/campaign/create/79/detail/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --form 'bulk_file=@/path/to/contacts.xlsx'

Response

{
  "error_list": [],
  "samples": [
    {"column": "number", "sample": "9841234567"},
    {"column": "name", "sample": "Rajesh"},
    {"column": "age", "sample": "23"},
    {"column": "salary", "sample": "50000"}
  ],
  "total_validated_rows": 150
}

Update a campaign

PATCH https://app.tingting.io/api/v1/campaign/{campaign_id}/ Updates one or more fields on an existing campaign. Only the fields you include in the request body are updated.

Path parameters

campaign_id

number

required

The ID of the campaign to update.

Request body

name

string

New display name for the campaign.

services

string

Updated delivery channel. Accepted values: PHONE, SMS, SMS & PHONE.

message

string

Updated voice message text.

sms_message

string

Updated SMS message text.

schedule

string

Updated schedule as an ISO 8601 date or datetime string.

Example

curl --request PATCH \
  --url https://app.tingting.io/api/v1/campaign/79/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"name": "updated name", "services": "SMS & PHONE", "schedule": "2025-07-09"}'

Delete a campaign

DELETE https://app.tingting.io/api/v1/campaign/{campaign_id}/ Permanently deletes a campaign and all its associated contacts.

Path parameters

campaign_id

number

required

The ID of the campaign to delete.

Example

curl --request DELETE \
  --url https://app.tingting.io/api/v1/campaign/79/ \
  --header 'Authorization: Bearer YOUR_TOKEN'

Contact management

List contacts

GET https://app.tingting.io/api/v1/campaign-detail/{campaign_id}/ Returns a paginated list of all contacts in a campaign, along with per-contact call outcomes and credit usage.

Path parameters

campaign_id

number

required

The ID of the campaign whose contacts you want to list.

Response fields

results

object[]

Array of contact records.

Show Contact fields

number

Unique contact ID.

number

string

Phone number.

status

string

Call status for this contact (e.g., Completed, Failed).

call_duration

number

Duration of the call in seconds.

playback

number

Percentage of the message that was played back.

credit_consumed

number

Voice credits consumed for this contact.

credit_consumed_SMS

number

SMS credits consumed for this contact.

carrier

string

Mobile carrier of the contact’s number.

total_credits_consumed

number

Total credits consumed across all contacts in the campaign.

carrier_summary

object

Breakdown of contacts by carrier.

Example

curl --request GET \
  --url https://app.tingting.io/api/v1/campaign-detail/79/ \
  --header 'Authorization: Bearer YOUR_TOKEN'

Get contact info

GET https://app.tingting.io/api/v1/campaign/{contact_id}/attributes/ Returns the custom attribute values stored for a specific contact.

Path parameters

contact_id

number

required

The ID of the contact whose attributes you want to retrieve.

Example

curl --request GET \
  --url https://app.tingting.io/api/v1/campaign/42/attributes/ \
  --header 'Authorization: Bearer YOUR_TOKEN'

Response

{
  "age": 22,
  "name": "राहुल",
  "salary": "एक लाख "
}

Edit contact number

PATCH https://app.tingting.io/api/v1/phone-number/update/{contact_id}/ Updates the phone number for a specific contact.

Path parameters

contact_id

number

required

The ID of the contact to update.

Request body

number

required

The new phone number to assign to this contact.

Example

curl --request PATCH \
  --url https://app.tingting.io/api/v1/phone-number/update/42/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"number": 9808684325}'

Edit contact attributes

PATCH https://app.tingting.io/api/v1/campaign/{contact_id}/attributes/ Updates the custom attribute values for a specific contact. The keys you provide must match the dynamic tag names used in the campaign message.

Path parameters

contact_id

number

required

The ID of the contact whose attributes you want to update.

Request body

(variable_name)

string

One or more key-value pairs matching the dynamic tag names in your campaign message. For example: {"name": "Ram", "age": "22", "salary": "200000"}.

Example

curl --request PATCH \
  --url https://app.tingting.io/api/v1/campaign/42/attributes/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"age": "22", "name": "Ram", "salary": "200000"}'

Delete a contact

DELETE https://app.tingting.io/api/v1/phone-number/delete/{contact_id}/ Permanently removes a contact from a campaign.

Path parameters

contact_id

number

required

The ID of the contact to delete.

Example

curl --request DELETE \
  --url https://app.tingting.io/api/v1/phone-number/delete/42/ \
  --header 'Authorization: Bearer YOUR_TOKEN'

Response

{
  "message": "Successfully Deleted."
}

Testing

Test voice

POST https://app.tingting.io/api/v1/test-speak/riri/{campaign_id}/ Generates a preview audio file so you can hear how your message will sound before running the campaign.

Path parameters

campaign_id

number

required

The ID of the campaign whose message you want to preview.

Request body

voice_input

number

required

Voice model ID (1–5) to use for the preview. Get the available IDs from List Voice Models.

message

string

required

The text to convert to speech for the preview.

Example

curl --request POST \
  --url https://app.tingting.io/api/v1/test-speak/riri/79/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"voice_input": 5, "message": "yo test voice ko laagi ho"}'

Response

"https://riritwo.prixacdn.net/output/eccc8258894076a9dc9e00cf4ebf472a.mp3"

Demo call

POST https://app.tingting.io/api/v1/demo-call/{contact_id}/ Triggers a real test call to a specific contact before you launch the full campaign. Use this to verify that the message, voice, and dynamic tags work correctly end-to-end.

Path parameters

contact_id

number

required

The ID of the contact to call for the demo.

Example

curl --request POST \
  --url https://app.tingting.io/api/v1/demo-call/42/ \
  --header 'Authorization: Bearer YOUR_TOKEN'

Run campaign

POST https://app.tingting.io/api/v1/run-campaign/{campaign_id}/ Starts a campaign. If you set a schedule when creating the campaign, it will begin at that time. If no schedule was set, the campaign starts immediately.

Path parameters

campaign_id

number

required

The ID of the campaign to run.

Example

curl --request POST \
  --url https://app.tingting.io/api/v1/run-campaign/79/ \
  --header 'Authorization: Bearer YOUR_TOKEN'

Scheduled response
Immediate response

{
  "message": "Campaign Scheduled successfully for 2082-03-25 at 14:46:00"
}

{
  "message": "Campaign Began Successfully!!"
}

Download report

Download call outcome data for a campaign as a CSV file.

Campaign report

GET https://app.tingting.io/api/v1/download/{campaign_id}/report/ Downloads a CSV report containing per-contact call outcomes, durations, and credit usage for the specified campaign.

Path parameters

campaign_id

number

required

The ID of the campaign to download the report for.

Example

curl --request GET \
  --url https://app.tingting.io/api/v1/download/79/report/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --output campaign_report.csv

Survey report

GET https://app.tingting.io/api/v1/download/survey/{survey_id}/report/ Downloads a report for a survey campaign. Returns CSV by default. Pass ?format=json to receive JSON instead.

Path parameters

survey_id

number

required

The ID of the survey to download the report for.

Query parameters

format

string

default:"csv"

Response format. Accepted values: csv, json.

Example

curl --request GET \
  --url 'https://app.tingting.io/api/v1/download/survey/12/report/?format=json' \
  --header 'Authorization: Bearer YOUR_TOKEN'

Get Started

API Reference

​List voice models

​Response fields

​Example

​List campaigns

​Query parameters

​Example

​Get campaign details

​Path parameters

​Example

​Create a campaign

​Request body

​Example

​Set voice and category

​Path parameters

​Request body

​Example

​Add a single contact

​Path parameters

​Request body

​Example

​Add multiple contacts

​Path parameters

​Request body

​Example

​Upload bulk contacts

​Path parameters

​Request body

​Example

​Update a campaign

​Path parameters

​Request body

​Example

​Delete a campaign

​Path parameters

​Example

​Contact management

​List contacts

​Path parameters

​Response fields

​Example

​Get contact info

​Path parameters

​Example

​Edit contact number

​Path parameters

​Request body

​Example

​Edit contact attributes

​Path parameters

​Request body

​Example

​Delete a contact

​Path parameters

​Example

​Testing

​Test voice

​Path parameters

​Request body

​Example

​Demo call

​Path parameters

​Example

​Run campaign

​Path parameters

​Example

​Download report

​Campaign report

​Path parameters

​Example

​Survey report

​Path parameters

​Query parameters

​Example

List voice models

Response fields

Example

List campaigns

Query parameters

Example

Get campaign details

Path parameters

Example

Create a campaign

Request body

Example

Set voice and category

Path parameters

Request body

Example

Add a single contact

Path parameters

Request body

Example

Add multiple contacts

Path parameters

Request body

Example

Upload bulk contacts

Path parameters

Request body

Example

Update a campaign

Path parameters

Request body

Example

Delete a campaign

Path parameters

Example

Contact management

List contacts

Path parameters

Response fields

Example

Get contact info

Path parameters

Example

Edit contact number

Path parameters

Request body

Example

Edit contact attributes

Path parameters

Request body

Example

Delete a contact

Path parameters

Example

Testing

Test voice

Path parameters

Request body

Example

Demo call

Path parameters

Example

Run campaign

Path parameters

Example

Download report

Campaign report

Path parameters

Example

Survey report

Path parameters

Query parameters

Example