Loading...

Callback Setup


The TrueDialog API supports a few standard types of callbacks listed below. A callback is the event-driven triggering of an HTTP request containing relevant JSON information that is sent from the Platform to a callback receiver hosted by the client. The following tutorial will show you how to make use of callbacks from our system to yours.


Callback Types

TrueDialog presently supports the following callback types:

(1) Keyword Fires a callback whenever a Keyword is texted into. Note that only keywords will callbacks enabled will fire callbacks.
(3) Dialog Fires a callback whenever a Dialog question receives a valid response.
(6) Stop Fires a callback whenever a Subscription preference has been changed (e.g. when a customer texts STOP to opt out of a Subscription).
(8) NewAccount Fires a callback whenever a new Account has been created.
(11) IncomingMessage Fires a callback on every incoming message to the Platform.

Step 1:

In order to use callbacks, this feature must be enabled on your account. Contact your account representative to get this enabled and receive your callback token.


Step 2:

Create a callback record by sending an HTTP/1.1 POST request to /account/{accountId}/callback. The following example creates a Keyword callback. All keywords with callbacks enabled will fire to the URL provided. You may create multiple callbacks of the same type to fire callback events to multiple URLs.

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

POST Body

{
  "CallbackType": 1,
  "URL": "http://callbackreceiver.mydomain.com/keyword",
  "Active": true
}

Create a keyword callback with curl

curl -v --user {apiKey}:{Secret}  "https://api.3seventy.com/api/v2.1/account/{AccountId}/callback" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"CallbackType": 1,"URL": "http://callbackreceiver.mydomain.com/keyword","Active": true}'

Step 3:

(For Keyword callbacks only, skip to Step 4 for other callbacks)

Create a Keyword (Refer to Keyword Creation Tutorials)

Once the Keyword is created, Attach the keyword to a campaign (you can use the default Gateway campaign that was created under your account). Send an HTTP/1.1 POST request to:

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

POST Body

CampaingId

Attach a keyword to a campaign with curl

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

Step 4:

Code a simple webservice to receive the HTTP callback POST request, and host at the URL provided in the callback resource.


Callback Data

Each callback type passes back slightly different data. The following table defines all attributes used in callbacks

AccountId For Keyword callbacks, this is the AccountId of the keyword owner. For Dialog callbacks, this is the AccountId of dialog campaign owner. For Stop callbacks, this is the AccountId of the Contact owner. For NewAccount callbacks, this is the AccountId of the new account that was created.
Answer The value associated with the dialog question answer. If the question is multiple choice, the value associated with the answer will be returned. If the question is yes/no, true or false will be returned. If the question is an open response, the valid response will be sent.
CallbackTimestamp The time that the callback was issued. Time zone used is UTC.
CallbackToken A GUID associated with the account.
CallbackType The type of callback. See Callback Types above.
CallbackURL The URL that the callback was delivered to.
Campaign Contains information on messages to send. Several campaign types exist.
CampaignId For Keyword callbacks, the Id of the campaign that was attached to the keyword at the time it was texted into.
ChannelId The Id of the channel / shortcode / Longcode that was texted into.
ContactId The Id of the contact that texted in.
ContactAccountId For Dialog Callback, account id of the contact which responded with the answer.
ContactAccountName For Dialog Callback, name of the account which contact belongs to.
Message For Incoming Message Callback, the message received from the contact.
ChannelCode For Incoming Message Callback, the actual channel code Eg: +19103755141.
Keyword The name of the Keyword that was texted into.
KeywordId The Id of the Keyword that was texted into.
AccountName The Name of the Account that was created.
ParentId The AccountId of the new account's parent account.
PhoneNumber The Phone Number of the Contact that texted in.
QuestionCampaignId The CampaignId of the question that was answered.
QuestionText The full text of the question that was asked to the contact.
SubscriptionId For Keyword callbacks, the Id of the Subscription is associated with the campaign attached to the keyword. For Stop callbacks, the Id of the Subscription being opted out of. For Dialog callbacks, the Id of the subscription associated with the dialog campaign.
DialogCampaignId The CampaignId of the dialog.
TransactionId A unique GUID assigned to each individual callback. If the same exact callback is resent multiple times (for instance if there is a network error), it will contain the same TransactionId.

Keyword

The following represents the format of the JSON data that will be POSTed to the callback URL for Keyword callbacks:

POST   http://callbackreceiver.mydomain.com/keyword

POST Body

{
    "AccountId":{AccountId},
    "CallbackTimestamp":"2013-06-17T05:35:26",
    "CallbackToken":"{CallbackTokenGuid}",
    "CallbackType":1,
    "CallbackURL":"http://callbackreceiver.mydomain.com/keyword",
    "CampaignId":{CampaignId},
    "ChannelId":{ChannelId},
    "ContactId":{ContactId},
    "Keyword":"{KeywordName}",
    "KeywordId":{KeywordId},
    "PhoneNumber":"{PhoneNumber}",
    "SubscriptionId":{SubscriptionId},
    "TransactionId":"{TransactionGuid}"
}

Dialog

The following represents the format of the JSON data that will be POSTed to the callback URL for Dialog callbacks:

POST   http://callbackreceiver.mydomain.com/dialog

POST Body

{
    "AccountId":{AccountId},
    "Answer":"{AnswerValue}",
    "CallbackTimestamp":"2013-06-17T06:23:32",
    "CallbackToken":"{CallbackTokenGuid}",
    "CallbackType":3,
    "CallbackURL":"http://callbackreceiver.mydomain.com/dialog",
    "QuestionCampaignId":{QuestionCampaignId},
    "QuestionText":"{QuestionText}",
    "ChannelId":{ChannelId},
    "ContactId":{ContactId},
    "PhoneNumber":"{PhoneNumber}",
    "SubscriptionId":{SubscriptionId},
    "DialogCampaignId":{DialogCampaignId},
    "TransactionId":"{TransactionGuid}"
}

Stop

The following represents the format of the JSON data that will be POSTed to the callback URL for Stop callbacks:

POST   http://callbackreceiver.mydomain.com/stop

POST Body

{
    "AccountId":{AccountId},
    "CallbackTimestamp":"2013-06-28T21:23:23",
    "CallbackToken":"{CallbackTokenGuid}",
    "CallbackType":6,
    "CallbackURL":"http://staging-callbackreceiver.3seventy.com/api/stopcallback/",
    "ChannelId":{ChannelId},
    "ContactId":{ContactId},
    "PhoneNumber":"{PhoneNumber}",
    "SubscriptionId":{SubscriptionId},
    "TransactionId":"{TransactionGuid}"
}

NewAccount

The following represents the format of the JSON data that will be POSTed to the callback URL for NewAccount callbacks:

POST   http://callbackreceiver.mydomain.com/newaccount

POST Body

{
    "AccountId":{AccountId},
    "CallbackTimestamp":"2013-06-28T21:23:23",
    "CallbackToken":"{CallbackTokenGuid}",
    "CallbackType":8,
    "CallbackURL":"http://staging-callbackreceiver.3seventy.com/api/newaccount/",
    "Name":"{AccountName}",
    "ParentId":{ParentAccountId},
    "TransactionId":"{TransactionGuid}"
}

Incoming Message

The following represents the format of the JSON data that will be POSTed to the callback URL for Incoming Message callbacks:

POST   http://callbackreceiver.mydomain.com/newaccount

POST Body

{
    "AccountId":{AccountId},
    "Message":"Is it a good time to chat?",
    "ChannelId":{ChannelId},
    "ContactId":{ContactId},
    "PhoneNumber":"{PhoneNumber}",
    "ChannelCode": "{ChannleCode}",
    "CallbackTimestamp":"2016-06-28T21:23:23",
    "CallbackToken":"{CallbackTokenGuid}",
    "CallbackType": 11,
    "CallbackURL":"http://staging-callbackreceiver.3seventy.com/api/incomingMessage/",
    "AccountName":"{AccountName}",
    "TransactionId":"{TransactionGuid}"
}