Callbacks

Creating new callbacks

To create a new API callback you can use the /callbacks endpoint.

The following table describes the fields that can be used within the request.

High-level request elements

name

String

Specifies the name (ID) of the callback to be used within message requests.

url

String

Specifies the service URL that API callbacks should be forwarded to.

auth

Object

Specifies the authorisation type that should be used with this endpoint. The specific elements of this object are described below.

The options for this parameter are:

  • querystring
  • httpheader

contentType

String

Specifies the content type that should be sent to this endpoint.

The choices are:

  • json
  • xml

removeHTML

String

Specifies whether HTML should be stripped from responses.

The choices are:

  • enabled
  • disabled

retriesEnabled

Boolean

Specifies whether Whispir should perform retries in the event there is a failure accessing the callback service.

The choices are as follows:

  • true
  • false

email

String

Specifies the email address that failure notifications should be sent to.

callbacks

Object

The object to store the callbacks that should be invoked for this endpoint. The specific elements of this object are described below.

The options for this parameter are:

  • reply: enabled/disabled
  • undeliverable: enabled/disabled


Notes:

  • The callback server must be expecting and accepting both GET and POST requests.
  • During the callback creation, Whispir makes a GET request to ensure the callback URL provided is valid. The responseCode for this request is 200. Any other code is considered a failure and the callback creation will fail.
  • This is the only time a GET request is made. Subsequent requests (callbacks) will all be POST requests.

  • JSON
  • XML

Creating new callbacks

The following API calls allow users to create new callbacks using the Whispir API:

{{codeStart}}

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

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

{

"name" : "Callback Name",

"url" : "http://myserver.com/mycallback.php",

"auth" : {

"type" : "querystring",

"key" : "MY_AUTH_KEY"

},

"contentType" : "json",

"removeHTML" : "disabled",

"retriesEnabled" : "true",

"email" : "me@example.com",

"callbacks" : {

"reply" : "enabled",

"undeliverable" : "enabled"

}

}

{{codeEnd}}

The sample code above will create a callback endpoint that can be used within messages being sent from Whispir.

The expected response to this call is a HTTP 201 - Created response.


Callback creation errors

Usually callback creation is simple and straightforward. But you may face errors at times when the configuration details given in the API are malformed.

400 Malformed Request error

The 400 Malformed Request error is a common error that you may face when creating a callback. If you get this issue perform the following checks:

  • Read the error detail in the response body. It will immediately give you a hint for what the issue is.
  • Is the callback URL reachable from outside of your intranet?
    Try again from outside your network.
  • Is the response for a GET request to the URL a 200?
    Try it in your browser and see what status you get on the Network tab of Developer Tools (F12). Or you can use cURL.
    • If the GET request doesn't receive a 200 response, Whispir considers the callback creation request a failure and throws a 400 Malformed Request.
    • The ‘request’ is malformed; that is, the URL is not working and so a bad configuration/malformed detail is given to Whispir.
  • A callback with the same name already exists in the Whispir platform under your account.

Callback authorisation

Whispir callbacks have been designed to be simple yet secure.

In order to make your callback server processing much safer, Whispir recommends the following security measures:

  • Use SSL on your callback URL.
  • Use a unique token. It should be an alphanumeric string generated and assigned specifically for Whispir callbacks.

When the token is provided in the callback payload, Whispir will include it in every request made to the listening application. The token’s presence confirms that the request has originated from Whispir.

There are two options for locating the authorisation token:

1. HTTP header

Using a HTTP header for authorisation is the preferred approach. This method uses a custom HTTP header X-Whispir-Callback-Key.

This can be added to the callback by specifying the code block:

"auth" : { "type" : "httpheader", "key" : "MY_AUTH_TOKEN" }

Every request to the specified URL will include the supplied AUTH token within this header. Alternatively, this could be supplied as a query parameter as follows.

2. URL query parameter

In this method, the authorisation is passed to the callback server on the query string using an ‘Auth’ parameter as follows:

"auth" : { "type" : "querystring", "key" : "MY_AUTH_TOKEN" }


  • JSON
  • XML

Callback authorisation

Callback servers should validate that the inbound request they are receiving is actually coming from Whispir.

 

HTTP header auth token 

Users can specify their Authorization token as a HTTP header. Whispir will add the X-Whispir-Callback-Key header to the request.

Below is an example of callback made by Whispir. It shows the response object format that will be sent to your callback server.

 

{{codeStart}}

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

X-Whispir-Callback-Key: MY_AUTH_TOKEN

Content-Type: application/json

{

"messageid" : "ABC4857BCCF484575FCA",

"messagelocation" : "https://api.<region>.whispir.com/messages/ABC4857BCCF484575FCA",

"from" : {

"name" : "Fred Waters",

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

"mobile" : "+1000000000",

"email" : "me@example.com",

"voice" : "+1000000000"

},

"responseMessage" : {

"channel" : "SMS",

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

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

}

}

{{codeEnd}}

 

URL query parameter auth token 

Users can specify their authorization token as a URL query parameter. This will come as auth=:your_token on the URL.

{{codeStart}}

HTTP 1.1 POST https://yourserver/callback.php?auth=MY_AUTH_TOKEN

Content-Type: application/json

{

"messageid" : "ABC4857BCCF484575FCA",

"messagelocation" : "https://api.<region>.whispir.com/messages/ABC4857BCCF484575FCA",

"from" : {

"name" : "Fred Waters",

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

"mobile" : "+1000000000",

"email" : "me@example.com",

"voice" : "+1000000000"

},

"responseMessage" : {

"channel" : "SMS",

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

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

}

}

{{codeEnd}}


Callback types

Callbacks can be added to any message that is sent from the Whispir API using the /messages endpoint.

Each callback can be invoked from one of two actions:

  • A message has been replied to.
    or
  • A message delivery failure occurred (wrong number or service unavailable).

You can control which of these actions are delivered to the endpoint using the callbacks object when registering new callbacks.

The options that are available are:

  • reply: Enabled/disabled.
  • undeliverable: Enabled/disabled.

When these options are enabled, any reply or failed delivery will cause a GET request to be invoked on the callback URL.