TrueDialog API – Overview

TrueDialog API

API Documentation

The TrueDialog API allows you to send messages from within your website or app and provides callbacks, contact management/filtering, and more. The following is an overview of the API, explaining its main features and variables. For more in-depth information about each endpoint, see the API Endpoints documentation.

All the URLs referenced in the instructions are based on the same Base URL https://api.truedialog.com/api/v2.1

Resources

The core features of any RESTful API are the resources themselves. This table outlines the resources necessary to use the API effectively. For more information on implementation, refer to the Endpoints section.

Accounts

Subscriptions

A Subscription ID is required for the API to track the contact’s opt-in/opt-out status for campaigns.

One-time subscriptions are useful for sending one-time messages. Examples: “Your package has been delivered”, “Your appointment is at 12 pm”.

Recurring subscriptions are for sending ongoing communications (e.g., “Thanks for joining our program, here’s this week’s coupon”, “This week’s special is the tomato soup”, “We are having a big sale next month”). This type of subscription is commonly used for mobile marketing campaigns.

NOTE: When a new account is created, a recurrent subscription is also created.

Synchronization

Contact

You should regularly synchronize any information you have for a contact/customer (i.e., FirstName, LastName, ZipCode, etc.) with the TrueDialog system. All contact information is stored as “Contact Attributes” in our system/API. While the API allows you to merge all contact information, it is recommended that you merge only recently changed data.

NOTE: This can be done at the PROD account level, so that all linked accounts are synchronized regularly via a single API call or similar process.

Account

“Account Attributes” are primarily used by customers with multiple subaccounts to represent their various business locations or divisions. These attributes can be synchronized through the API, and the synchronization frequency depends on the specific use case. Generally, 24 hours is sufficient time for synchronization to occur.

Segmentation

• We allow segmentation based on any contact attribute or account attribute.
• All lists are dynamic. When a message is sent, a filtering criterion is executed to determine the current list of contacts.

Campaigns

• Messages can be sent via a Gateway Campaign, where the message body is delivered to us via the API. One API request delivers the message to a single phone number or a list of contacts.
• Messages can be sent via a Basic Campaign, where the message body is stored in a template. One API request delivers the message to a list of contacts.
• Basic messages can contain dynamic content via a Razor template that pulls in both Account Attribute data (specific to the subaccount, such as LocationCity) and Contact Attribute data (specific to the individual contact, such as FirstName).

Gateway Campaigns

Gateway Campaigns are the most basic type of campaign. They have no predefined content and require you to supply the message when you push the campaign. To create this type of campaign, all that is needed is the Campaign Name (Name) and the Campaign Type ID (campaignTypeId), which is 0. Once the campaign is created, the Campaign ID (id) is used whenever you push a new message with the campaign.

Campaign Types

TrueDialog supports a variety of campaign types.

If you need further assistance, Contact Us to discuss your requirements so we can help you determine the best approach.

Below is a list of supported Campaign Types with their API values.

Channel Types

The TrueDialog Platform supports messaging over multiple channels. If you require a channel that is not listed, Contact Us to discuss your unique requirements.

Below is a list of supported Channel Types with their API values.

Encoding Types

Content templates can be encoded as plain text or in a C# Razor template compiled at runtime.

Below is a list of supported Message Encoding Types with their API values.

Schedule Types

Any campaign can be sent immediately or scheduled for a future time. The API also supports recurring scheduling.

To send a message immediately, set the execute variable to true in the Creates a new push action request body.

Below is a list of supported Schedule Types with their API values.

Language Types

Below is a list of supported Languages with their API values.

Data Types

Below is a list of supported Data Types with their API values.

Date and Time Formats

While the TrueDialog API can read many different Date/Time formats, we recommend using ISO 8601 format for best support. Below are some examples of valid date/time strings.

A string with a date and time component:

"2013-04-01T12:31:00.0000Z"
"2013-04-01T12:31:00.0000-05:00"

"2013-04-01T12:31:00.0000Z"
"2013-04-01T12:31:00.0000-05:00"

A string that includes the GMT designator and conforms to RFC 1123:

"Mon, 01 Apr 2013 12:31:00 GMT"

"Mon, 01 Apr 2013 12:31:00 GMT"

A string that includes the date and time in addition to the time zone offset:

"04/01/2013 12:31:00 -5:00"

"04/01/2013 12:31:00 -5:00"

A string with a date but no time. The time component will default to 12:00 midnight.

A time with no date. The default date will be the current date.

Process Statuses

Process statuses indicate the current state of a campaign push or action. Below is a list of the Process Statuses with their API values.

HTTP Response Codes

TrueDialog uses the following HTTP response/error codes. Error codes are returned with Content-Type=text/plain.