Callbacks

Handling callback failures

In the event that the provided callback URL can’t be reached or the connection to the service times out, Whispir automatically generates a notification to the nominated email address containing details of the failed attempt.

Whispir automatically sends an email in the following circumstances:

  • If the callback server returns anything other than a HTTP 200 OK.
  • If the authorisation to the callback server fails (for example, it returns a HTTP 400 level error)
  • If the callback server doesn't connect within 5 seconds.
  • If the callback server doesn't return a response within 60 seconds.

 

Callback retries

The retriesEnabled flag can be enabled on a callback to ensure that Whispir automatically attempts to retry in the event of a failure occurring.

When a failure conditions occurs, Whispir marks the callback server as down and logs the attempted callback as Failed. The callback is retried after approximately 5 minutes. If the server is available, the callbacks are automatically processed through the server; you don’t need to take any further action.

The following rules apply to Whispir’s automated retries for callbacks:

  • When a failure to make a callback occurs, Whispir begins retries approximately every 5 minutes.
  • Whispir will retry any callback for up to 24 hours.
  • After 24 hours the callbacks are no longer retried.
  • If the callback service becomes available prior to 24 hours the callbacks will automatically re-process.
  • If the callback service takes longer than 24 hours, you can access the callback information from the /callbacks/:id/calls endpoint.

You need to supply one of the following headers (for retrieving JSON or XML):

  • Accept: application/vnd.whispir.api-call-v1+xml
  • Accept: application/vnd.whispir.api-call-v1+json

An array of calls is returned to you in the HTTP response body. Each call provides the following information:

Response elements

id

String

The unique ID of the specific call within Whispir.

messageid

String

The unique ID of the message within Whispir.

messagelocation

String

The fully qualified URL to the original message within Whispir.

status

String

The status of this particular callback attempt. The options are:

  • SUCCESS
  • FAILED

from

Object

The details about this particular message sender/responder.

The properties of this object are:

  • name (string): The name of the sender of this message.
  • mri (string): The unique identifier for this contact within Whispir.
  • mobile (string): The mobile phone number associated with this sender.
  • voice (string): The phone number associated with the voice channel for this sender.
  • email (string): The email address associated with the email channel for this sender.

responseMessage

Object

The details about this particular message that have been sent to the callback.

The properties of this object are as follows:

  • channel (string): The channel that this message was sent on. Either SMS, email or voice.
  • acknowledged (string): The date/time that this message was acknowledged.
  • undeliverable (string): The date/time that this message was marked as undeliverable.
  • content (string): The content of the message.

Note: Only one of the acknowledged or undeliverable timestamps will be provided.

callback

Object

The details about this particular callback attempt.

The properties of this object are:

  • id (string): The ID of the callback attempting to be invoked.
  • name (string): The name of the callback server attempting to be invoked.
  • url (string): The URL of the callback server attempting to be invoked.
  • attemptedDate (string): The date/time that the callback server was attempted to be invoked.
  • statusCode (integer): The statuscode that was returned from the callback service.
  • statusMessage (string): The status message that was returned from the callback service.

link

Array

Provides a list of URLs that can be used to manipulate or access the callback.

  • uri: The link to access the specific callback.
  • rel: The descriptor for what the link will do.
  • method: The HTTP method to use with this particular link.

Retrieving the list of calls based on their status

To retrieve a list of attempted API calls from the Whispir API you can execute a HTTP GET using the /calls endpoint on a specific callback.

To specifically retrieve the FAILED/SUCCESS calls you can pass a status query param in the URL.

Query params

status

String

The status value can be one of:

  • &status=SUCCESS
  • &status=FAILED

Only calls with the requested STATUS will be present in the response.


Updating the status of calls to a callback

As every call to a callback endpoint is now stored within the /calls endpoint, it’s possible that when failed calls are successfully processed through a manual exercise, these calls will need to be updated to reflect the current status.

Take the following example:

  1. The callback server becomes unavailable.
  2. A message is sent via Whispir with callbacks enabled.
  3. The message gets a response and this triggers the callback.
  4. The callback server is unavailable so the response is stored with a status of 'FAILED’.
  5. After 24 hours the callback server becomes available again. Retries have stopped, so this information will not automatically flow into the callback server.
  6. The customer writes a script to GET all of the calls stored in the /calls endpoint and process them.
  7. Once successfully processed, the customer’s script should update the contents of the /calls endpoint to reflect the current status of ‘SUCCESS’.

You can facilitate this process by using a PUT request to the /calls endpoint in Whispir.

To update a list of attempted API calls from the Whispir API you can execute a HTTP PUT using the /calls endpoint on a specific callback.

You need to supply one of the following headers (for retrieving JSON or XML):

  • Accept: application/vnd.whispir.api-call-v1+xml
  • Accept: application/vnd.whispir.api-call-v1+json

The expected response code for this operation is 204 No Content.

You can specify multiple IDs to be updated using the following notation:

/callbacks/:id/calls?id=ID1&id=ID2&id=ID3...

This ensures that all callbacks that have been processed can be updated in a single API call, rather than having to make a single API call per callback attempt.

The PUT request takes a single API parameter in the body:

Request elements

status

String

The status to update the attempted calls to:

  • SUCCESS
  • FAILED


  • JSON
  • XML

Callback failures

Whispir will automatically send notifications to your nominated email address in the event of a failure to access your callback server.

When retries are enabled, the following message will be sent:

 

Dear Customer, 
Your callback *callback_id* failed on *date* with response: *response*. 
The callback that failed is as follows: 
URL: https://yourserver/callback.php?auth=12345
Location: https://api..whispir.com/messages/ABC4857BCCF484575FCA
Name: Fred Waters
Mobile: +1000000000
Email: me@example.com
Channel: SMS
Content: Yes, I accept. Will I need to bring steel cap boots?
Whispir will automatically retry any failed requests to this callback endpoint for 24 hours, after which the requests can be queried using the Whispir API for up to 30 days.
Please take the necessary steps to ensure your callback is configured correctly.
Regards,
Whispir Support

 
When retries are disabled the message is slightly different:

Retries are disabled on this callback endpoint so no retries will be attempted. Any requests can be queried using the Whispir API for up to 12 months from this notification.

  

Retrieving attempted calls to a callback endpoint

The following API methods allow you to access callback attempts via the API:

 

{{codeStart}}

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

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Accept: application/vnd.whispir.api-call-v1+json

{

"status": "1 to 1 of 1",

"calls": [

{

"id": "B3EDFE83DF389DFE",

"messageId": "ABC4857BCCF484575FCA",

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

"status": "FAILED",

"from": {

"name": "Fred Waters",

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

"mobile": "+1000000000",

"email": "",

"voice": ""

},

"responseMessage": {

"channel": "SMS",

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

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

},

"callback": {

"id": "B384FD38DCBADE38",

"name": "My Callback Server",

"url": "https://www.myapplication.com/myapp",

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

"statusCode": 500,

"statusMessage": "Internal Server Error"

},

"link": [{

"rel": "updateCall",

"uri": "/callbacks/B384FD38DCBADE38/calls/B3EDFE83DF389DFE",

"method": "PUT"

}]

}

],

"link": [{

"rel": "next",

"uri": "/callbacks/B384FD38DCBADE38/calls?limit=20&offset=20",

"method": "GET"

}]

}

{{codeEnd}}