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.

Account Setup

Step 1: Create a new subaccount

Several 3Seventy 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. Send an HTTP/1.1 POST to the account endpoint:

https://api.3seventy.com/api/v2.1/account

POST Body

{
"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:
201 CREATED
Content-Type: application/json
{
  "Id": "{AccountId}",
  "ParentId": "{ParentId}",
  "Name": "My First Merchant",
  "Status": 0,
  "AllowCallback": false,
  "CallbackToken": null
}
     

Create a subaccount with curl

curl -v --user {Login}:{Password} "https://api.3seventy.com/api/v2.1/account" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"ParentId": "{ParentAccountId}","Name": "My First Merchant"}'

Step 2: Verify new subaccount

To verify that the subaccount was created in Step 2, perform a HTTP/1.1 GET operation on the new resouce:

https://api.3seventy.com/api/v2.1/account/{NewAccountId}

Verify the subaccount with curl

curl -v --user {Login}:{Password} "https://api.3seventy.com/api/v2.1/account/{NewAccountId}" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

Basic Campaign Setup

Step 1 : 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 (22) and in English (0). See the API Overview for a complete description of channel types and languages supported. Send an HTTP/1.1 POST to the campaign endpoint:

https://api.3seventy.com/api/v2.1/account/{AccountId}/campaign

POST Body

{
"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:

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.

Create a basic campaign with curl

curl -v --user {Login}:{Password} "https://api.3seventy.com/api/v2.1/account/{AccountId}/campaign" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"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 new campaign

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

https://api.3seventy.com/api/v2.1/account/{AccountId}/campaign/{CampaignId}

Verify the new campaign with curl

curl -v --user {Login}:{Password} "https://api.3seventy.com/api/v2.1/account/{AccountId}/campaign/{CampaignId}" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

Step 3: 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, send an HTTP/1.1 GET the channel endpoint:


https://api.3seventy.com/api/v2.1/account/{AccountId}/channel

Get the channel list with curl

curl -v --user {Login}:{Password} "https://api.3seventy.com/api/v2.1/account/{AccountId}/channel" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

Choose the {ChannelId} of the channel you wish to use for your campaign and create a new keyword on this channel by sending an HTTP/1.1 POST request to the keyword resource:

https://api.3seventy.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword

POST Body

{ "name": "MYKEYWORD" }

Create a new keyword with curl

curl -v --user {Login}:{Password} "https://api.3seventy.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "name": "MYKEYWORD" }'
Response should be 201 CREATED:
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 4: 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. Send an HTTP/1.1 POST requests to the resource:

https://api.3seventy.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}/campaign

POST Body

"{CampaignId}"

Attach a keyword to a campaign with curl

curl -v --user {Login}:{Password} "https://api.3seventy.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}/campaign" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '"{CampaignId}"'

Setp 5: Verify Campaign Attachment

To verify that the keyword has been attached to the campaign, simply send an HTTP/1.1 GET request to the following resource and note the campaign_id:

https://api.3seventy.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}

Verify the keyword attachment with curl

curl -v --user {Login}:{Password} "https://api.3seventy.com/api/v2.1/account/{AccountId}/channel/{ChannelId}/keyword/{KeywordId}" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

Step 6: Live test!

Send a text message containing your new keyword to the short code associated with the channel. You should receive the response contained in the message template of the campaign!