TrueDialog API
API Documentation
Callback
A callback is an HTTP request containing relevant JSON information sent from the TrueDialog platform to a callback receiver you host. It is triggered by an event such as receiving a text or creating a new Account. Through the API, you can create and manage callbacks. Instructions for using the TrueDialog Portal to create and manage callbacks can be found here:
Callback Types
| ID | Name | Description |
|---|---|---|
| 1 | Keyword | Triggers whenever an end-user texts in a keyword. |
| 2 | Subscription | Triggers whenever a contact opts into a subscription. |
| 3 | Survey | Triggers whenever an end-user responds to a survey. |
| 6 | Stop | Triggers whenever an end-user texts in “STOP” or a synonym. |
| 8 | New Account | Triggers whenever a new child account is being created. |
| 11 | Incoming Message | Triggers whenever an end-user sends a message. |
| 12 | Delivery Notice | Triggers for each delivery notice receipt. |
| 13 | Invalid Targets | Triggers if targets have been filtered out during a push. |
| 14 | Clicks | Triggers whenever an end-user clicks on a link. |
| 15 | Long Code Provision | Triggers whenever a long code request is completed. |
Step 1. Enable Callbacks
Callbacks need to be enabled on your account for them to function. To enable callbacks, log in to the Portal and follow the instructions in the article below, or contact your TrueDialog Representative to receive your callback token.
Because the process of configuring each callback is similar, the following steps show only how to set up the Incoming Message Callback.
Step 2. Create a Callback
Send an HTTP/1.1 POST request to the Callback endpoint to create a new callback.
All messages received from end users will trigger a callback to the provided URL. You can create multiple callbacks of the same type to send the same callback event to multiple URLs.
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/callback
POST Body
{
"CallbackType": 11,
"URL": "http://callbackreceiver.mydomain.com/callbackReceiver"
}cURL Example
curl -v --user {apiKey}:{Secret} "https://api.truedialog.com/api/v2.1/account/{AccountId}/callback" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"CallbackType": 11,"URL": "http://callbackreceiver.mydomain.com/callbackReceiver"}'Step 3. Create Web Service to Receive the Callback Request
To receive the HTTP POST callback, you must set up a web service hosted at the URL specified in the callback resource. The table below shows all the JSON keys sent by the TrueDialog callbacks. Each callback type sends only the keys relevant to its event. See the sections below for a description of the information provided by each callback.
Send the following request to the API to get a list of all callbacks and the information each provides. An array of callback types will be returned, and for each type, a payload value will outline the information that the callback provides.
GET
https://api.truedialog.com/api/v2.1/misc/callback-type
Callback Data
| JSON Key Name | Data Type | Description |
|---|---|---|
| AccountId | number | ID of the account the callback is associated with. |
| AccountName | string | Name of the account the callback is associated to. |
| ActionId | number | Action ID if any (null if message is not associated with any action). |
| Answer | string | The matched answer. |
| CallbackTimestamp | string | Date and time the callback has been sent. Format: yyyy-MM-ddTHH:mm:ss |
| CallbackToken | string | Special token, unique for each account. |
| CallbackType | number | The ID of the Callback Type. |
| CallbackURL | string | URL this callback has been sent to. |
| CampaignId | number | ID of the campaign associated with the keyword (0 if none). |
| ChannelCode | string | The actual channel the keyword has been received over. |
| ChannelId | number | ID of the channel the keyword has been received over. |
| ClickTimestamp | string | Date and time the link has been clicked. Format: yyyy-MM-ddTHH:mm:s |
| ContactAccountId | number | The ID of the account that owns the contact record. |
| ContactAccountName | string | The name of the account that owns the contact record. |
| ContactId | number | ID of the contact that submitted the keyword. |
| DialogCampaignId | number | The phone number of the end user that sent the message. |
| Error | string | The error that occurred during the TN order, if any. |
| InvalidTargets | object[] | The list of targets that have been filtered out. |
| Keyword | string | The actual keyword that has been submitted. |
| KeywordId | number | ID of the keyword that has been submitted. |
| LinkId | number | The ID of the link that has been clicked. |
| Message | string | The actual message text. |
| MessageId | string | The ID of the message. |
| Name | string | The name of the newly created account. |
| OrderBy | string | The OrderBy field value of the TN order request. |
| ParentId | number | The ID of the parent account. |
| Pattern | string | The Pattern field value of the TN order request. |
| PhoneNumber | string | The phone number of the end user that submitted the keyword. |
| PhoneNumbers | string[] | The list of phone numbers provided if any. |
| Quantity | number | The Quantity field value of the TN order request. |
| QuestionCampaignId | number | The ID of the question campaign. |
| QuestionText | string | The text of the question. |
| RawAnswer | string | The actual message received from an end user. |
| RedirectUrl | string | The URL the end user has been redirected to. |
| RequestId | number | The ID of the TN order request. |
| RunId | number | ID of the action run this callback is associated with. |
| Status | string | Delivery code, “OK” for delivered message or error code for undelivered. |
| StatusId | number | 2 = Delivered, 3 = Undelivered, 7 = Unknown |
| Subscribed | boolean | The flag indicates if the contact has been opted in or out of subscription. |
| SubscriptionId | number | The ID of the subscription the contact has been subscribed with the keyword. |
| TransactionId | string | Unique token. |
Step 4. Test the Callback
Test the incoming message callback by sending a message to your TrueDialog account. Your callback receiver will receive a callback with the JSON data. The following is an example of the data received from an Incoming Message callback: (Note: Some information has been replaced with X for privacy reasons.)
{
"MessageId": "7cd3bd38-7896-410c-9dfb-6bc45d3aa491",
"AccountName": "TD Technical Documentation",
"Message": "Incoming message callback test.",
"ChannelId": 22,
"ContactId": XXXXXXXXX,
"PhoneNumber": "+1XXXXXXXXXX",
"ChannelCode": "+1XXXXXXXXXX",
"ActionId": 177844357,
"Media": [],
"AccountId": XXXXX,
"CallbackTimestamp": "2024-03-30T20:36:33",
"CallbackToken": "522238b1-f039-4b23-a7db-XXXXXXXXXXXX",
"CallbackType": 11,
"CallbackURL": "https://ptsv3.com/t/tdTestCallback/",
"TransactionId": "40dbfdcb-32c1-431d-b3ec-58436908787e"
}Callback: Keyword
For Keyword callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 1,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"AccountName": string,
"CampaignId": number,
"ChannelId": number,
"ChannelCode": string,
"ContactId": number,
"Keyword": string,
"KeywordId": number,
"PhoneNumber": string,
"SubscriptionId": number
}Callback: Subscription
For Subscription callbacks, see below for the JSON data format that the TrueDialog system sends via a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 2,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"ContactId": number,
"PhoneNumber": string,
"SubscriptionId": number,
"Subscribed": boolean
}Callback: Survey
For Survey callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 3,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"AccountName": string,
"Answer": string,
"RawAnswer": string,
"ChannelId": number,
"ChannelCode": string,
"ContactId": number,
"ContactAccountId": number,
"ContactAccountName": string,
"PhoneNumber": string,
"QuestionCampaignId": number,
"QuestionText": string,
"SubscriptionId": number,
"DialogCampaignId": number
}Callback: Stop
For Stop callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 6,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"AccountName": string,
"ChannelId": number,
"ChannelCode": string,
"ContactId": number,
"ContactAccountId": number,
"ContactAccountName": string,
"PhoneNumber": string,
"SubscriptionId": number
}Callback: New Account
For New Account callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 8,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"Name": string,
"ParentId": number
}Callback: Incoming Message
For Incoming Message callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 11,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"AccountName": string,
"MessageId": string,
"Message": string,
"ChannelId": number,
"ChannelCode": string,
"ContactId": number,
"PhoneNumber": string,
"ActionId": number,
"Media": number[]
}Callback: Delivery Notice
For Delivery Notice callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 12,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"AccountName": string,
"StatusId": number,
"Status": string,
"ChannelId": number,
"ChannelCode": string,
"MessageId": string,
"PhoneNumber": string,
"ContactId": number,
"ActionId": number,
"Message": string
}Callback: Invalid Targets
For Invalid Targets callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 13,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"ActionId": number,
"RunId": number,
"InvalidTargets": [
{
"Target": string,
"ReasonId": number,
"Reason": string,
}
]
}Callback: Clicks
For Clicks callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 14,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"AccountName": string,
"CampaignId": number,
"ContactId": number,
"PhoneNumber": string,
"ClickTimestamp": string,
"LinkId": number,
"RedirectUrl": string
}Callback: Long Code Provision
For Long Code Provision callbacks, see below for the JSON data format sent by the TrueDialog system as a POST request to the callback URL.
POST
http://callbackreceiver.mydomain.com/callbackReceiver
POST Body
{
"CallbackTimestamp": string,
"CallbackToken": string,
"CallbackType": 15,
"CallbackURL": string,
"TransactionId": string,
"AccountId": number,
"AccountName": string,
"RequestId": number,
"OrderBy": string,
"Pattern": string,
"Quantity": number,
"Status": string,
"StatusId": number,
"PhoneNumbers": string[],
"Error": string
}