TrueDialog Web API

Getting Started

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

Please sign up for a trial or paid account to access our SMS API.

Before you can send messages there is some initial setup that needs to be done. This is a one-time setup.  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.

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.

Basic Campaign

After you define your subscription, you can create a basic 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. [Check out the Basic Campaign Tutorial]

 Key Integration Points

Account Structure

  • ROOT Account
    • Production
      • Client 1
      • Client 2
    • UAT
      • Client 1 UAT
      • Client 2 UAT
    • DEMO
      • DEMO Account 1
      • DEMO Account 2

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 sub-account.

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
    • 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
    • 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 per phone number).
  • 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
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. True Dialog currently supports SMS, MMS, 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

True Dialog 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 Surveys ask a question or a series of questions to the subscriber and listens for their response. Responses are stored as contact attributes. Surveys 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 a shortened URL to a bar code coupon.

Schedule Types

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

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

(1) Now Trigger the event immediately.
(2) One Time Tigger the event at a specified time in the future.
(6) Daily Trigger the event at a specified time on specified days of the week.

Channel Types

The True Dialog 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. 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 True Dialog 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 Language 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}

HTTP Response Codes

True Dialog 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
404 Not Found The requested resource is not found or not accessible to the
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 True Dialog 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 True Dialog so we can investigate the issue.

Date & Time Formats

True Dialog 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.
  • A string with a time zone that conforms to ISO 8601.
  • 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