Basic Campaign Tutorial

Introduction

The following tutorials (Account Setup and Basic Campaign) will guide you through the process of creating a subaccount, a campaign, and a keyword and then finally, assigning that campaign to the keyword. At the end of this tutorial, you will be able to send a text message to the keyword and receive the response you created back from the system.

While you can perform these operations directly from our endpoints doc page, you may find it easier to use a REST client utility such as WizTools RESTClient or the Postman plugin on Chrome.

Account Setup

This tutorial requires that you have valid credentials to access the API. To obtain this information, you may sign up for a free trial account or contact True Dialog to obtain your existing account credentials.

Step 1: Verify API user credentials

Verify that you can connect to the API using your supplied credentials. This can be accomplished by accessing the main Account resource.

GET https://api.True Dialog.com/api/v2.0/account HTTP/1.1 Authorization: Basic {AuthorizationHash} Accept: application/json

The API will return XML by default. To receive JSON, set the Accept header to application/json.

The API uses Basic authentication. Set the Authorization header to Basic {AuthorizationHash}.

The response will contain a list of accounts accessible to theuser. If no subaccounts exist, then only the primary account willbe returned. Note the id of the account returned. This will bereferenced as {AccountId} going forward.

Step 2: Create a new subaccount

Several True Dialog partners require the creation and management of subaccounts to better organize their contacts. If this does not apply to you, or is not enabled on your account, skip to Basic Campaign Setup.

POST https://api.True Dialog.com/api/v2.0/account HTTP/1.1
Authorization: Basic {AuthorizationHash}
Accept: application/json
Content-Type: application/json
{
"ParentId": "{ParentAccountId}",
"Name": "My First Merchant"
}

To send an XML object instead, set the Accept & Content-Type header to application/xml. A 415 Unsupported Media Type error will be returned if Content-Type is to an unrecognized type.

By default, all accounts are created with a status of 0 (zero) to indicate their active status.

To add a subaccount to a subaccount, pass in the AccountId of the desired parent account in the ParentId parameter. By default, the ParentId is set to the AccountId of the authenticated user.

Hierarchy may be used to create an account structure and go several layers deep.

Response should be 201 CREATED:
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"Id": "{AccountId}",
"ParentId": "{ParentId}",
"Name": "My First Merchant",
"Status": 0,
"AllowCallback": false,
"CallbackToken": null
}

Step 3: Verify new subaccount

To verify that the subaccount was created in Step 2, perform a GEToperation on the new resouce.a

GET https://api.True Dialog.com/api/v2.0/account/{AccountId} HTTP/1.1
Authorization: Basic {AuthorizationHash}
Accept: application/json

Basic Campaign Setup

Step 1 : Create a new 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 creating a Campaign.

To create a subscription, perform a POST operation on the new resouce.a

POST https://api.True Dialog.com/api/v2.0/account/{AccountId}/subscription HTTP/1.1
Authorization: Basic {AuthorizationHash}
Accept: application/json
Content-Type: application/json
{
"Name": "Acme",
"Label": "Acme Mobile Alerts",
"Frequency": "30",
"SubscriptionTypeId": 2 // "1" is for a recurring subscription, "2" is for a one time subscription.  (See below)
}
Response should be 201 CREATED:

HTTP/1.1 201 CREATED
Content-Type: application/json
{
"AccountId": "{AccountId}",
"Name": "Acme",
"Label": "Acme Mobile Alerts",
"id": "{SubscriptionId}"
}

Name: This will appear in your STOP messagesLabel: Program label appears in the HELP message, Compliance message, andHandset Verification

 

One-time subscriptions are useful for sending one off messages. E.g. “your package has been delivered”, “your appointment is at 12pm”, anything where the contact only expects to get a message from you once and then 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”).

Step 2 : Create new Basic Campaign

A Basic Campaign (type = 1) will allow you to send a message to contacts and/or auto-respond to incoming SMS messages when attached to a keyword.

MessageTemplates contain the actual message. One message template can be added for each channel type – language combination supported by the campaign. For this example, we’ll create a campaign with 1 message template for the SMS channel (0) and in English (0).
See the API Overview for a complete description of channel types and languages supported.

POST https://api.True Dialog.com/api/v2.0/account/{AccountId}/campaign HTTP/1.1
Authorization: Basic {AuthorizationHash}
Accept: application/json
Content-Type: application/json
{
"SubscriptionId": "{SubscriptionID}",
"Name": "Welcome Message",
"CampaignTypeId": 1,
"Content": 
{
"Name": "Welcome Message Content",
"Templates":
[
{
"ChannelTypeId": "0",
"LanguageId": "0",
"EncodingTypeId": "0",
"Template": "Welcome to our mobile club!"
}
]
}
}
Response should be 201 CREATED:

HTTP/1.1 201 CREATED
Content-Type: application/json
{
"Id": "{CampaignId}",
"AccountId": "{AccountId}",
"SubscriptionId": {SubscriptionId},
"Name": "Welcome Message",
"CampaignTypeId": 1,
"StatusId": 0,
"StatusReason": null,
"ContentId": {ContentId},
"Session": false,
"SessionLength": null,
"Created": "2013-06-19T19:04:18.47",
"Modified": "2013-06-19T19:04:18.47",
"CreatedBy": null,
"ModifiedBy": null
}

Template encoding must be set to 0 (plain text).

Message templates can be modified sending a PUT with a new MessageTemplate resource. Also, new message templates can be added to the campaign by sending a POST to request with a
MessageTemplate resource.

Step 3: Verify new campaign

To verify that the campaign was created, perform a GET operation on the new resouce.a

GET https://api.True Dialog.com/api/v2.0/account/{AccountId}/campaign/{CampaignId} HTTP/1.1
Authorization: Basic {AuthorizationHash}

Step 4: Create new keyword

Keywords are necessary for receiving inbound SMS messages. They serve a number of purposes, but in this example a keyword is used to opt-in to a campaign via SMS. Choose a keyword that is applicable to your campaign and can be easily texted by a subscriber.

Keywords belong to a particular channel, which in the case of the SMS channel type, means a particular short code or phone number. To discover what channels are available to your account, GET the channel list:

 

GET https://api.True Dialog.com/api/v2.0/account/{AccountId}/channel HTTP/1.1
Authorization: Basic {AuthorizationHash}

{ChannelId} of the channel you wish to use for your campaign and create a new keyword on this channel by POSTing to the keyword resource.

POST https://api.True Dialog.com/api/v2.0/account/{AccountId}/channel/{ChannelId}/keyword HTTP/1.1
Authorization: Basic {AuthorizationHash}
Accept: application/json
Content-Type: application/json
{ "name": "MYKEYWORD" }
Response should be 201 CREATED:
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"AccountId": "{AccountId}",
"channel_id": "{channelId}",
"campaign_id": null,
"name": "MYKEYWORD",
"status": 0,
"callback_required": null,
"id": "{KeywordId}"
}

 

The keyword will remain reserved but inactive until a campaign is attached to it. As indicated by the null value in the keyword’s campaign_id field.

Step 5: Attach Keyword to Campaign

When a Keyword is attached to a Campaign, anyone who texts into the short code associated with the channel will receive the message included in the Campaign resource.

POST https://api.True Dialog.com/api/v2.0/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}/campaign HTTP/1.1
Authorization: Basic {AuthorizationHash}
Accept: application/json
Content-Type: application/json
"{CampaignId}" 

Setp 6: Verify Campaign Attachment

To verify that the keyword has been attached to the campaign, simplyGET the keyword and note the campaign_id.

GET https://api.True Dialog.com/api/v2.0/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId} HTTP/1.1
Authorization: Basic {AuthorizationHash}

Step 7: Live test!

Send a text message containing your new keyword to the short codeassociated with the channel. You should receive the responsecontained in the message template of the campaign!