API Overview

TrueDialog’s RESTful API allows you to connect with 990+ operators and 5.5 billion wireless subscribers globally.

You will need to sign up for an account to get started.

Before you can send messages there is some initial setup that needs to be done. This is all a one-time setup for this, so you do not need to do this for every message that is sent; but it allows us to track the users and make sure we honor the opt-out messages they send back to us.

NOTE The following is how you can do this through our API, but you can also accomplish this through our portal and use the resulting details in later direct API calls.


First you need a subscription, this is what your contacts will opt in and out of.

One-time subscriptions are useful for sending one-time messages. "Your package has been delivered", "your appointment is at 12pm", and any other message where the contact only expects to get a message from you once; and then he will generally not hear from you again.

Recurring subscriptions are for sending on-going communications (e.g. "thanks for joining our program, here's your free coupon", "this week’s special is the tomato soup", "we are having a big sale next month"). This is the most commonly used for mobile marketing campaigns.

NOTE When an account is created, a Recurring subscription will also be created by default.

Basic Campaign

Once you have your Subscription ready you can create a gateway campaign. These campaigns do not have any predefined content, which allows you to supply the message when you’re ready to push the campaign.

All the other details can be left as their defaults since that is what you probably want at first. Once you get the Campaign ID, you should be all set. This ID can be reused multiple times each push, and there's no need to make these API calls again. Most often people will use the documentation page or the portal to setup the initial campaign details, write down the IDs they get, and code that to their call to the push endpoint.

NOTE When an account is created, a Basic Campaign will also be created by default.

Account Creation

Account structure will look like such:

For each new client, you can use the GUI or API to create a new subaccount. Subaccounts isolate both campaign information as well as contact (customer) information for all contacts in the subaccount.

UAT accounts may be used for post-sales, pre-go live API integration testing.

Demo accounts may be used for pre-sales client-specific capability demonstrations.

Contact Synchronization

FirstName, LastName, ZipCode, etc. -- any information you have for a contact / customer should be regularly synchronized between the systems. These are all “Contact Attributes” in our system / API.

The API allows you to merge contact information, however it is recommend to only merge recently changed contact data.

NOTE This can be done from the PROD account level, so that all linked accounts are synchronized regularly via 1 API call, or other such process.

Account Synchronization

Account Attributes are used mostly for customers that have multiple sub-accounts, where subaccounts are generally used to represent multiple business locations or business divisions.

Synchronization of these attributes can be done via API, and the frequency of the sync depends on the use case – generally 24hr is sufficient but not always.

NOTE We have an API call that allows you to update account information.

Segmentation Synchronization

We allow segmentation based on any contact attribute or account attribute.

All of our lists are dynamic, meaning a set of filtering criteria is executed to determine the list of contacts at the time a message is sent to the list.

Campaign Creation

Messages can be sent via a Gateway Campaign (where the message body is delivered to us via API – 1 API request delivers the message to a single phone number or to a list of contacts).

Or messages can be sent via a Basic Campaign (where the message body is stored in a template, and 1 API request delivers the message to a list of contacts).

Basic messages can be created via API.

Basic messages can contain dynamic content using a Razor template, which can pull in both the Account Attribute data (specific to the subaccount, such as LocationCity) and Contact Attribute data (specific to the individual contact, such as FirstName).

Message Delivery

The most common case is to push a campaign that has been previously setup and sending to a contact list that has been previously setup.

We provide a scheduler that allows campaigns to be sent out at a specific date and time in the future – this is set in the same API call as sending a message.


The meat and potatoes of any RESTful API are the resources themselves. This describes the main resources you will need to be familiar with in order to effectively use the API. See Endpoints for additional implementation details.

Account The top level resource from which all API requests are made.
Subscription This is what your customers opt in and out of. Most accounts only have 1 or a small number of subscriptions. A subscription is required prior to sending any messages.
Campaign Contains information on messages to send. Several campaign types exist.
Content & Content Templates Multi-channel and multi-language message templates. A Template campaign can have 1 Content Template for each channel & language supported.
Contact The subscriber receiving the message, including contact information (phone number and/or email) and subscriber channel preferences.
Contact Attributes Each account can setup custom contact attributes to mimic (or build) their customer database. Attributes may be used in message templates and can also be used in ContactLists to create targeted contact filters.
ContactList A sophisticated static/dynamic list used to group Contacts. Container for a set of filters that are evaluated at the time a campaign is sent.
Channel A communication / transport channel. TrueDialog currently supports SMS, MMS, Voice and Email channels.
Keyword For SMS, Keywords are used by participants to text into a campaign. Primarily used on shared short codes, they can also be used on dedicated codes to distinguish which promotion a participant is responding to.

Campaign Types

TrueDialog supports a variety of campaign types. Contact Us to discuss your requirements so we can assist you in determining the best approach to take.

Below are a list of Campaign Types (values) supported via API.

(0) Gateway API-only campaign type used to send single-channel, single-language SMS messages where the message text is passed in through every request. Not recommended when pushing to over 500 contacts.
(1) Basic The most common campaign. Message content is stored in the campaign and is sent to a list of contacts that are passed in, or to a predefined ContactList for large pushes.
(2) Dialog Dialog asks a question or a series of questions to the subscriber and listens for their response. Responses are stored as contact attributes. Dialog’s can be yes/no, multiple choice, or validated open response.
(4) Coupon Similar to a Template campaign, but will include a static or system generated unique coupon code in the message, or an external list coupon code, or a shortened URL to a barcode coupon.

Schedule Types

Any campaign can be scheduled to be sent immediately or at a designated time in the future. TrueDialog also supports recurring scheduling.

Below are a list of Schedule Types (values) supported via API.

(2) One Time Tigger the action at a specified time in the future.
(6) Daily Trigger the action at a specified time every day.
(7) Weekly Trigger the action at a specified time on specified days of the week.
(8) Monthly Trigger the action at a specified time on specified days of the month.

Channel Types

The TrueDialog Platform was architected to support messaging over multiple channels. If you require a channel that is not listed, Contact Us and let us know what you need.

Below are a list of Channel Types (values) supported via API.

(0) SMS 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.
(1) MMS MMS messages go out over a short code, e.g. 70626.
(2) Email An email channels can be setup for any SMTP server. By default, we will send emails using Amazon SES.

Encoding Types

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

Below are a list of Message Encoding Types (values) supported via API.

(0) Text Plain text / no encoding. No dynamic text.
(1) Razor Required for emails. Can use dynamic text (contact attributes or account attributes) in message.

Language Types

The TrueDialog Platform can send messages in any language. If you do not see the language you need listed, Contact Us and we'll add it.

Below are a list of Message Encoding Types (values) supported via API.

(0) English
(1) Spanish
(2) Simplified Chinese

Data Types

Data Types are used to specify the type of data in dynamic account & contact attributes.

Below are a list of Data Types (values) supported via API.

(1) Integer Whole number {0,1,2,3... or -1, -2, -3}.
(2) String Text information.
(3) Real Number Number with decimal {1.732 etc..}.
(4) Date Date or Datetime value.
(5) Boolean True or False
(6) Binary Binary data, such as an image or other file
(7) GUID Globally unique identifier {e.g. 8D796643-F9AE-4BE6-846C-B44EB9124DE9}
(8) BigInt Large whole number {0,1,2,3... or -1, -2, -3}

HTTP Response Codes

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

200 OK The request was received successfully.
201 Created The resource was created successfully via POST.
204 No Content The request was processed successfully, but there was no content to return.
400 Bad Request The request was malformed or missing required information.
401 Not Authorized The authenticated user is not authorized to access the resource.
404 Not Found The requested resource is not found or not accessible to the user.
405 Method Not Allowed The requested resource does not support the HTTP method attempted. See Endpoints for a full list of which methods are supported on all resources.
415 Unsupported Media Type The TrueDialog Web API supports XML (application/xml) and JSON (application/json) content types. A user may see this error if a different media type is requested in the Accept or Content Type headers.
500 Server Error See message body for further details. Sometimes this occurs when the body of the request cannot be parsed. If noticed repeatedly, please contact TrueDialog so we can investigate the issue.

Date & Time Formats

TrueDialog can accept just about any human readable format for a date and time. Supported formats are:

A string with a date and time component

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 current date.

  • "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"

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

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