TrueDialog API
API Documentation
This section walks through the most common TrueDialog API tasks. All requests are based on the base URL https://api.truedialog.com/api/v2.1. Campaigns are the objects that send messages over a channel (SMS, MMS, Email, or RCS); many endpoints reference your Campaign ID to determine which channel a campaign uses. A Subscription ID is required for the API to track each contact’s opt-in/opt-out status for campaigns.
Account Creation
If you have not yet created a TrueDialog Account, do so HERE. Subaccounts can be used to manage contacts.
To create a new subaccount, send an HTTP/1.1 POST to the account endpoint:
POST
https://api.truedialog.com/api/v2.1/account
Keyword Creation
A keyword is required to receive inbound SMS messages. To create a new keyword, send an HTTP/1.1 POST to the keyword resource:
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword
Once created, the keyword will remain inactive until a campaign is attached to it.
Each keyword is associated with a channel. To determine which channels are available with your account, send an HTTP/1.1 GET to the channel endpoint:
GET
https://api.truedialog.com/api/v2.1/account/{AccountId}/channel
Sending Basic Text Messages
A Gateway Campaign allows you to send an outgoing SMS message. Send an HTTP/1.1 POST to the action-pushcampaign endpoint.
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/action-pushcampaign
You will need to provide the following information:
| Attribute | Type | Definition |
|---|---|---|
| Channels | Array | TrueDialog supports different communication/transport channels: SMS, MMS, Email, and RCS. The channel ID specifies the channel type. Your account is already provisioned with an SMS channel, as indicated in the confirmation email. |
| Targets | Array | This parameter provides a list of destination telephone numbers in the E.164 format. +1########## |
| Message | String | The message you want to send. |
| Execute | Boolean | This instructs the platform to execute the command. |
Basic Campaign
A basic campaign lets you send a message to contacts and automatically respond to incoming SMS messages.
The following tutorial will walk you through creating a basic campaign, creating a keyword, and then sending a message to the keyword. The result will be a return message from the keyword you created.
Step 1. Create a New Basic Campaign
Send an HTTP/1.1 POST to the Campaign Endpoint.
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/campaign
You will need the following:
- ChannelTypeId:
- SMS = 0 (SMS messages go out over a Short Code, e.g., 33898, or a Long Code, e.g., +19103755141. SMS messages in the United States must be 160 characters or less.)
- MMS = 1 (MMS messages go out over a short code, e.g., 70626.)
- Email = 2 (An email channel can be set up for any SMTP server. By default, we will send emails using Amazon SES.)
- LanguageId
- English = 0
- Spanish = 1
- Simplified Chinese = 2
- French = 3
- Arabic = 4
- Nepali = 5
- Burmese = 6
- Somali = 7
- Encoding Type
- Text = 0 (Plain Text, no encoding, no dynamic text)
- Razor = 1 (Used for emails. You can use dynamic text (contact attributes or account attributes) in messages.)
- Template: The Template contains the actual message. You can have one template for each channel-language combination.
Example
{
"Name": "Welcome Message",
"CampaignTypeId": 1,
"Content": {
"Name": "Welcome Message Content",
"Templates": [
{
"ChannelTypeId": "0",
"LanguageId": "0",
"EncodingTypeId": "0",
"Template": "Welcome to our mobile club!"
}
]
}
}Step 2. Verify a New Campaign
To verify the new campaign created above, use the following HTTP/1.1 GET operation.
GET
https://api.truedialog.com/api/v2.1/account/{AccountId}/campaign/{CampaignId}
Example
curl -v --user {apiKey}:{Secret} "https://api.truedialog.com/api/v2.1/account/{AccountId}/campaign/{CampaignId}" \
-H "Content-Type: application/json" \
-H "Accept: application/json"Step 3. Create New Keyword
A keyword is required to receive inbound SMS messages. As described in the Keyword Creation section above, send an HTTP/1.1 POST to the keyword resource to create one:
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword
Once created, the keyword will remain inactive until a campaign is attached to it.
Step 4. Attach Keyword to Campaign
Once a keyword is attached to a campaign, anyone who texts the channel’s number will receive the message included in the campaign resource. To attach the keyword to the campaign, send an HTTP/1.1 POST request to the campaign resource.
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}/campaign
Example
curl -v --user {apiKey}:{Secret} "https://api.truedialog.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}/campaign" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '"{CampaignId}"'Step 5. Verify Campaign Attachment
To verify that the keyword above has been attached to the campaign, send an HTTP/1.1 GET request to the keyword resource. Note the CampaignId.
GET
https://api.truedialog.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}
Example
curl -v --user {apiKey}:{Secret} "https://api.truedialog.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}" \
-H "Content-Type: application/json" \
-H "Accept: application/json"Step 6. Push the Campaign Message
Now that the campaign is created and set up, it is time to send the message to the contacts. To push a message, send an HTTP/1.1 POST request to the action push campaign resource.
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/action-pushCampaign
Sending Basic Media Message
A Multimedia Messaging Service (MMS) is like a Basic Text Message but allows you to send pictures, videos, audio, or documents. The following file types are supported:
| File Type | Supported Extensions |
|---|---|
| Image | .jpg .jpeg .png |
| GIF | .gif |
| vCard | .vcf |
| Video | .mpeg .mpg .mpe .m1v .m2v .mp4 mp4v |
| Document | .doc .docx |
| Text | .txt .text |
| Audio | .wav .mp2 .mp3 |
Step 1. Upload a media file to TrueDialog
Send an HTTP/1.1 POST to the Account Image API endpoint.
POST
https://api.truedialog.com/api/v2.1/account/accountId/image
Example
curl -v --user {apiKey}:{Secret} -F "data=@filename.jpg"
"https://api.truedialog.com/api/v2.1/account/AccountID/image"Response
{
"Id": MediaId,
"AccountId": AccountID,
"Uri": "uri.jpg",
"OriginalName": "filename.jpg",
"MediaType": "image/jpg"
}The MediaId of the uploaded file will be used in the campaign to indicate the file to send in your MMS message.
Step 2. Send the MMS Message
To send the MMS message to your contacts, send an HTTP/1.1 POST request to the action push campaign resource.
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/action-pushCampaign
Example
curl -v -u {apiKey}:{Secret} "https://api.truedialog.com/api/v2.1/account/accountId/action-pushcampaign"
-H "Content-Type: application/json"
-d '{ "Channels":[ChannelID]
"Targets":["telephone number"], "MediaId":##, "Execute":true }'Additional Information
An MMS message can also be associated with a Campaign or assigned a keyword, just like an SMS message. To do this, change the Channel type to 1 for MMS. For more details, see the instructions under Sending Basic Text Messages above.
Contact List
The Contact List section is currently being updated. Some of the information may not reflect the current API.
Contact lists allow you to create a filtered list of contacts with predefined values and conditions. You can filter contacts by attributes such as age or name. With a contact list, you can target your campaigns to specific contacts.
When pushing a Campaign, you can specify a contact list to receive the campaign’s message. See the tutorial below for creating a Contact List.
Step 1. Create a Filter
A contact list is created by defining filters. Filters specify which criteria (age, ZIP code, etc.) will be used to search all contacts. The following tables explain the information a filter requires.
Filter
A filter comprises the following JSON parameters outlined in the table below.
| Attribute | Type | Description |
|---|---|---|
| FilterTypeId | Integer | A filter type identifies the type attribute/variable of the operand. The Filter Types table below explains each type. |
| OperandId | Integer | The OperandId specifies the ID of the attribute/variable on which the operation will be performed. |
| Operation | String | The logic operation to perform. |
| Value | String | The value you are filtering on. |
Filter Types
The attributes and variables of a contact are separated based on the type of information they contain. To select an attribute or variable to filter on, first select the FilterTypeId. The FilterTypeId is the ID of the category to which each attribute or variable belongs. See the table below for the FilterTypeId for each category.
| ID | Name | Description |
|---|---|---|
| 1 | Contact Attribute | User-defined attributes including state, city, DOB, ZIP code, name, age, etc. |
| 2 | Subscription | The Subscription ID or IDs the contact is currently subscribed to. |
| 3 | Contact Info | TrueDialog defined data: Phone Number First Name Last Name Assigned ID |
| 4 | Account Attribute | |
| 5 | Keyword | The keyword or keywords attached to a contact. |
| 6 | Ignore Subscription | |
| 7 | Action |
Operand ID
The OperandId is a unique ID assigned to the attribute or variable on which the filter operation is performed. To find the OperandId, you need to know the FilterTypeId in which the operand is located and then look up the operand’s ID. You can think of this in terms of a relational database, where FilterTypeId indicates the table and OperandId indicates the column within that table. Refer to the table below for instructions on obtaining the ID for each Filter Type.
| FilterTypeId | FilterType Name | API Request |
|---|---|---|
| 1 | Contact Attribute | GET https://api.truedialog.com/api/v2.1/account/{AccountId}/contact-attributeDef |
| 2 | Subscription | |
| 3 | Contact Info | |
| 4 | Account Attribute | |
| 5 | Keyword | |
| 6 | Ignore Subscription | |
| 7 | Action |
Operation
The filter’s logical operation is the Operation parameter. The table below lists the available operations you can enter in the JSON Operation field.
| Operation | Name |
|---|---|
> | Greater Than |
< | Less Than |
>= | Greater Than or Equal |
<= | Less Than or Equal |
<> | Not Equal |
= | Equal |
anybits | Any Bits |
allbits | All Bits |
nobits | No Bits |
^ | Begins With |
$ | Ends With |
Example
The filter in this example will return all contacts who are at least 25 years old. The “Age” attribute is selected by setting the FilterTypeId to “1” (the Contact Attribute filter type) and the OperandId to “5201” (the ID of Age, which is unique to the TrueDialog account this example was created with). Then the Operation of “>=” (greater than or equal to) is set to compare with a Value of “25”. Below, the filter is shown as a Logic operation, SQL operation, and JSON code.
Logic
Age >= 25SQL
SELECT *
FROM Contacts
WHERE `Age` >= 25;JSON
{
"FilterTypeId": "1",
"OperandId" : "5201",
"Operation" : ">=",
"Value" : "25"
}Step 2. Create a Filter Group
Multiple filters can be combined into a group. Groups are used to create more complex logic operations.
| Name | Description |
|---|---|
| Operator | Only “AND” or “OR”. |
| Groups | Array of nested items. The group details. |
| Filters | The Filter Details |
Example
This filter group will filter for people between 25 and 35 years old. It works by filtering a “Contact Attribute” called “Age” with an OperandId of “5201” that is greater than or equal to “25” AND less than “35.”
Logic
(Age >= 25) AND (Age < 35)SQL
SELECT *
FROM Contacts
WHERE (`Age` >= 25)
AND (`Age` < 35);JSON
{
"Operator": "AND",
"Groups" : [],
"Filters" : [
{
"FilterTypeId": "1",
"OperandId" : "5201",
"Operation" : ">=",
"Value" : "25"
},
{
"FilterTypeId": "1",
"OperandId" : "5201",
"Operation" : "<",
"Value" : "35"
}
]
}Step 3. Create a Contact List
Now that the filtering has been explained, we can create a complete contact list.
Contact List Format
{
"Name": string,
"RootGroup": {
/* root group details */
}
}Complex Example of a Contact List
This contact list has several different logic operations in the filter. The first filter group selects all contacts aged 25 to 35 who also have a phone number with area code 512. The second filter group combines the results of the first filter with all contacts whose email addresses end with support@truedialog.com.
Logic
((Age >= 25) AND (Age < 35) AND (Phone ^ "+1512"))
OR (Email = "support@truedialog.com")SQL
SELECT *
FROM Contacts
WHERE ((`Age` >= 25) AND (`Age` < 35) AND (`Phone` LIKE '+1512%')
OR (`Email` IS 'support@truedialog.com');JSON
{
"Name": "My complex contact list",
"RootGroup": {
"Operator": "OR",
"Groups": [
{
"Operator": "AND",
"Groups" : [],
"Filters" : [
{
"FilterTypeId": "1",
"OperandId" : "5201",
"Operation" : ">=",
"Value" : "25"
},
{
"FilterTypeId": "1",
"OperandId" : "5201",
"Operation" : "<=",
"Value" : "35"
},
{
"FilterTypeId": "3",
"OperandId" : "5",
"Operation" : "^",
"Value" : "+1512"
}
]
}
],
"Filters": [
{
"FilterTypeId": "3",
"OperandId" : "4",
"Operation" : "=",
"Value" : "support@truedialog.com"
}
]
}
}To create a Contact List using the example above, send the JSON code above in the body of an HTTP/1.1 POST request to the ContactList endpoint.
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/contactlist
Creating a Contact List with the Portal
The TrueDialog Portal has a UI for creating Contact Lists that you can use if you do not need to programmatically create one via the API. The Portal is also a good resource for testing and viewing Contact Lists. See the documentation for creating Contact Lists in the article below.
Personalized Campaign
A Personalized Campaign lets you use contact attributes to send dynamic content. See the tutorial below to create an attribute and a contact list for the campaign.
Step 1. Create a Contact List
See the Contact List section above for instructions on creating one.
Step 2. Create a Basic Campaign
After creating a Contact List, the next step is to create a Basic Campaign (CampaignTypeId = “1”). Basic Campaigns allow you to send a message to contacts or respond automatically to SMS messages attached to a keyword.
The Content Templates contain the actual message text. You may add one Content Template for each Channel Type (SMS, MMS, Email).
Send an HTTP/1.1 POST to the Campaign endpoint.
POST
https://api.truedialog.com/api/v2.1/account/{AccountId}/campaign
You will need the following:
- ChannelTypeId:
- SMS = 0 (SMS messages go out over a Short Code, e.g., 33898, or a Long Code, e.g., +19103755141. SMS messages in the United States must be 160 characters or less.)
- MMS = 1 (MMS messages go out over a short code, e.g., 70626.)
- Email = 2 (An email channel can be set up for any SMTP server. By default, we will send emails using Amazon SES.)
- LanguageId
- English = 0
- Spanish = 1
- Simplified Chinese = 2
- French = 3
- Arabic = 4
- Nepali = 5
- Burmese = 6
- Somali = 7
- Encoding Type
- Text = 0 (Plain Text, no encoding, no dynamic text)
- Razor = 1 (Used for emails. You can use dynamic text (contact attributes or account attributes) in messages.)
- Template: The Template contains the actual message. You can have one template for each channel-language combination.
Example
{
"Name": "Welcome Message",
"CampaignTypeId": 1,
"Content":
{
"Name": "Welcome Message Content",
"Templates": [
{
"ChannelTypeId": "0",
"LanguageId": "0",
"EncodingTypeId": "0",
"Template": "Welcome to our mobile club!"
}]
}
}Step 3. Insert Contact Attribute
To personalize the message and insert a contact attribute, such as First Name or Preferred Location, set EncodingTypeId = “1” in the template and create the campaign. See below:
"EncodingTypeId": "1",
"Template": "@(Contact.FirstName), welcome to our mobile club! Text STOP to end"