Callbacks

Callback parameters

The callback API allows you to include in the callback response those values (parameters) that you want to be returned as is.

Here is a simple scenario to explain it:

  1. An app sends a POST /messages request to Whispir for sending a message to the customer.
  2. The app gets a location and messageid with responseCode as 202, meaning the message is received by Whispir successfully.
  3. Whispir queues the request and executes it at the next execution cycle (usually immediately).

Then

  1. The customer receives the message and responds to it.
  2. Whispir receives the message and pushes the response to the app via the callback URI.

Then

  1. The app needs to identify the customer that has responded.
  2. The app uses the messageid provided in step 2 to cross-check and identify.

As evident in the scenario, messageid plays a key role in identifying the message response chain. However, rather than using just the Whispir provided messageid, the app can send in its own free-will callback parameters like:

  • customerID
    or
  • a unique hash that corresponds to a specific transaction
    or
  • just about anything that can be a unique value from the perspective of your app.

Whispir takes note of these callback parameters, and when the response is returned via the callback URI, these parameters are included in the payload and sent as callbackParameters, which is an object. This makes it easy for the app to identify the user data from the single/multiple/follow-on response of a conversation.

The data provided via the ‘callbackParameters’ is set:

  • in JSON as

{ Key : Value }

  • in XML as

<entry> <key> <value> </entry>

If there is more than one set of values, the data is set:

  • in JSON as

{ Key : Value }, { Key : Value }

  • in XML as

<entry> <key> <value> </entry> <entry> <key> <value> </entry>

 

  • JSON
  • XML

Callback parameters within a callback response

A single callback parameter:

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

{

"to" : "+1000000000",

"subject" : "Test SMS",

"body" : "This is the SMS",

"callbackId" : "Sample Callback 1",

"callbackParameters" : {

"CustomID" : "890h0ef0fe09efw90e0jsdj0"

}

}

{{codeEnd}}

 

Multiple callback parameters:

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

{

"to" : "+1000000000",

"subject" : "Test SMS",

"body" : "This is the SMS",

"callbackId" : "This is my callback",

"callbackParameters" : {

"CustomID" : "890h0ef0fe09efw90e0jsdj0",

"CustomID2" : "9ef0fe09efw90e0jsdjsd43fw"

}

}

{{codeEnd}}

 

Receiving callback parameters in the response

When the callback is invoked for a reply/delivery failure, the callbackParameters passed are sent in the response call to your callback server.

An important point to note is that these values are part of the customParameters object. The response doesn't contain the callbackParameters object. The naming convention can be a bit confusing at times but it is retained from a logical premise.

You’re passing in parameters that are custom to a specific message in the /messages call. The parameters are included in the callback object. So, you include them in the callbackParameters at source and when you receive them, you get them as customParameters the way they are intended. while(1) { read again; }

Notes:

  • The calling app can supply any number of callback parameters.
  • The information is passed back to the application every time a response is triggered.
  • The response type is always string, even when an integer is used.
  • Apart from the callback parameters specified in the /messages request, the API also gives another set of values that are used to process it.
  • JSON
  • XML

{{codeStart}}

HTTP 1.1 POST https://yourserver/callback.php

Content-Type: application/json

{

"messageid":"ABC4857BCCF4CA",

"location" : "https://api.<region>.whispir.com/messages/ABC4857BCCF4CA",

"from":{

"name":"Fred Waters",

"mri":"Fred_Waters.528798.Sandbox@Contact.whispir.com",

"mobile":"0430984567",

"email":"imacros@test.com",

"voice":"0761881564"

},

"responseMessage":{

"channel":"SMS",

"acknowledged":"09/01/19 13:22",

"content":"Yes, I accept. Will I need to bring steel cap boots?"

},

"customParameters" : {

"CustomerId" : "890h0ef0fe09efw90e0jsdj0",

"TransactionId" : "9ef0fe09efw90e0jsdjsd43fw",

...

}

}

{{codeEnd}}