NAV
json xml

Whispir Platform API

API Endpoint

https://api.<region>.whispir.com

Whispir regions are -

AU - https://api.au.whispir.com
AP - https://api.ap.whispir.com
AP1 - https://api.ap1.whispir.com
NZ - https://api.nz.whispir.com
US - https://api.us.whispir.com
IT - https://api.it.whispir.com
EDU - https://api.education.whispir.com

API Authorization

Users must use an API Key and Authorization Header to access the Whispir API. These are available by signing up for a account at whispir.io.

Summary of Resources

The following resource endpoints are accessible when using the Whispir API.

/messages
/messages/:id/messagestatus
/messages/:id/messageresponses
/templates
/responserules
/contacts
/contacts/:id/devices
/distributionlists
/scenarios
/events
/imports
/resources
/activities
/users
/customlists
/callbacks
/callbacks/:id/calls
/workspaces
/apps

Note: The events endpoint is only available for users with the Events Module.

Example Request

# Authorization and apikey are provided in the registration processes
curl -H "Authorization: Basic <YOUR AUTHORIZATION HEADER>" -H "x-api-key: <YOUR API KEY>"
     https://api.<region>.whispir.com/messages?apikey=<YOUR API KEY>

Example Response

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>No records found</status>
</ns2:return>

Built by developers, for developers, Whispir is the place where you can easily build communications into your app – SMS, email, push, voice, chat, web, social, & rich messages.

The Whispir API gives developers the ability to:

Communications Template API

The Whispir.io Template API gives developers the ability to:

Event Management API

The Whispir.io API Event Management API provides developers with the tools needed to manage the communication around events that happen:

Contact Management API

The Whispir.io API provides developers with the ability to manage the recipients of their messages:

API Gateway Changes

We have moved away from our legacy API Gateway service to AWS API Gateway Service to better serve your growing API needs.

This migration is being performed in 2 phases.

Phase 1: Provide the new regional gateway service (Completed)
Phase 2: Sunset the api.whispir.com url, and only keep the regional based links. (Ongoing, and last date for clients to update is Apr 30, 2019)

Please follow the steps below to check the 3 main element of compliance to the new API Gateway standards.

Change of SSL Certs

Whispir is aware of some client integrations that depend upon trusting the client SSL Certificate explicitly.

If your application has this dependency, we would recommend that you review your implementation as the certificate serving api.whispir.com will be changing. You can download the new wildcard certificate by simply visiting au.whispir.com , or the respective region (ap, us, nz, it, ap1) based URL.

IP Whitelisting

The new and legacy Whispir API Gateway services are hosted in AWS.

If your implementation depends upon IP Whitelisting in order to make calls to our service, we suggest that you review the following set of Amazon IP’s. You will need to whitelist all IP ranges

For users still connecting to “https://api.whispir.com” until the 30-Apr-2019 deadline,

For all the regional endpoints, you should be using REGION + EC2

Enforcing HTTP Specifications

Whispir is aware of some client intergration that do not adhere to header parsing rules specified in the Hypertext Transfer Protocol specification.

While Whispir is looking to implement mitigations for those impacted, we highly recommend that you review your implementations and ensure that they treat all headers as case insensitive to increase resilience.

The rollout of changes on the 21st of August 2018 highlighted these issues with some client integrations. The most common problem identified was a dependency on the casing of the ‘location’ response header provided by Whispir after successful API calls.

Changes to API URL and Key

Whispir has recently updated the API Gateway Service for all its instances. This update brings in the ability to better route the API requests to its regional instances, and also lays the foundation for more API Gateway related benefits it will bringing to its customers in the future.

The changes we are rolling in now are primarily in two areas.

  1. The API URL will be more specific to your region
  2. The API Key information is also to be passed in the headers, apart from the current query param

However, Whispir requests you to make efforts to change as stated below FROM 15-Mar-2019 until the 30-Apr-2019 which is a fixed date, and no extension will be provided. If no changes are made by the 30-Apr-2019 (23:59:59 GMT), your API calls will be rejected by Whispir.

New API URL

Current API Base URL

https://api.whispir.com

New API URL based on regions -

AU - https://api.au.whispir.com
AP - https://api.ap.whispir.com
AP1 - https://api.ap1.whispir.com
NZ - https://api.nz.whispir.com
US - https://api.us.whispir.com
IT - https://api.it.whispir.com
EDU - https://api.education.whispir.com

When you are making a call to Whispir API today, the URL is simply https://api.whispir.com. This is a single URL for all the regions. Going forward, the URL will be more inline with your account’s region making it https://api.<region>.whispir.com.

The region and its corresponding URL is as following -

RegionAPI Base URL
AUhttps://api.au.whispir.com
APhttps://api.ap.whispir.com
AP1https://api.ap1.whispir.com
NZhttps://api.nz.whispir.com
UShttps://api.us.whispir.com
IThttps://api.it.whispir.com
EDUhttps://api.education.whispir.com

What is my region?

  1. Login to your Whispir.io Account, and click on any existing key. The information is available there as Enviroment value. Eg: for ap.whispir.com, your region is ap.
  2. By asking your company administrator. The region is usually revealed from your Platform URL, which would be in the format of https://<region>.whispir.com
  3. If you are still unsure, Please reach out to Whispir Support by passing your API Key. Support would advise on your region specifc API URL.

Sending API Key

Taking an example, If your region is AP, then your -

Current API Key sending mechanism

https://api.whispir.com?apikey=YOUR-API-KEY
Authorization: Basic YOUR-AUTH-HEADER

New API URL based on region, and api key is sent via headers -

https://api.ap.whispir.com?apikey=YOUR-API-KEY
Authorization: Basic YOUR-AUTH-HEADER
x-api-key: YOUR-API-KEY

The only change here is the addition of a new header value to carry the api key, and change of the url to be region specific.

Whispir needs your API Key to validate that the request is made genuinely by you, and ties it against your account for rate limiting, and throughput capacity purposes. Currently, the api key information is sent via the url query params.

In line with the new API Gateway changes, the key information has to be passed in via the “headers” as well, using the x-api-key header value.

Important Points:

  1. The apikey is to be passed both as a query param and also as a header value.
  2. The header key to be used is x-api-key. Eg: x-api-key: YOUR-API-KEY. The value is same as the apikey value sent in the headers.
  3. The order in the headers does not matter. x-api-key can be passed as the last header value, or the first, or somewhere in the middle. Sending it is important. The order is not so much so.
  4. If the API Key value is incorrect, or not passed propery, then a 403 Forbidden error will be returned by Whispir.
  5. All other header parameters that you are sending today, should be passed as-is. DO NOT remove them. DO NOT remove them. DO NOT remove them. You have been warned thrice.

If you have any queries, related to this, please do reach out to Whispir Support. Provide as much detail as possible in relation to the help you need, or the error you have faced with this change.

Getting Started

Getting started with the Whispir.io API is easy:

  1. Register with Whispir to create your account - (Free 14 Day Trial)
  2. Activate your account, and reach out to Whispir for the API Credentials- (Whispir Support)
  3. Check your connectivity to the API
  4. Try it out! Send your first message

Register with Whispir

The Whispir.io API is available for all existing Whispir customers to use. If you’re already a Whispir customer, great! Your existing username and password will work straight away.

  1. If you are an existing Whispir client, please contact Whispir Support for a new API key.
  2. If you are using a Whispir Free Trial - please email Whispir Support to apply for an API key.

Once you’ve got your App API key, you can check your connectivity to the API using the steps below.

Connect to the API

Connect to the API

Using the information on the left, you can execute the following curl statement:

curl -H "Authorization: <Your Authorization Header>" -H "x-api-key: <YOUR API KEY>"
     https://api.<region>.whispir.com?apikey=<Your API Key>

# with sample values

curl -H "Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk" -H "x-api-key: 89asdfohasd89023rsd" 
     https://api.<region>.whispir.com?apikey=89asdfohasd89023rsd

# If all is correct, the following response should be expected (The API defaults to an XML response)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:company xmlns="http://schemas.api.whispir.com/dap"
             xmlns:ns2="http://schemas.api.whispir.com">
    <link method="GET"
          rel="retrieveWorkspaces"
          uri="https://api.<region>.whispir.com/workspaces?apikey=89asdfohasd89023rsd"/>
    ...
</ns2:company>

The first thing you’ll need to do is generate your Authorization Header for your API requests. You’ll need to use the Authorization Header on every request that you submit to the Whispir.io API.

Whispir uses Basic HTTP Authentication for all API requests.

You can generate the Authorization header in most programming languages very easily, however for simplicity you can generate it here by filling in the form below.

Note: Your Whispir authentication information is not submitted or stored, it is only used as part of an algorithm to automatically generate your header.

Whispir Username:

Whispir Password:

Authorization Header:

Once you have generated this header, you can use it in a request to the API. This will ensure everything is working correctly. To do this you can use a programming lanugage, a curl script, or a generic REST client.

NOTE: When you change your password, you’ll need a new authorization header.

Connect using a programming language

Whispir.io provides some basic code samples in a range of languages to assist users in geting started with the API. Once you have created your App in the Whispir.io Dashboard, simply click on the Code tab on the left side of the screen.

Select the App, and the action that you would like to perform (e.g. Send an SMS message).

This will automatically generate the code for you. You can copy this code into your IDE, import any required dependencies, and run it.

You will need to replace the following elements of the request:

  1. App API Key
  2. Authorization Header
  3. Recipient information
  4. Message Subject
  5. Message Content

Once you have verified you have replaced all of these, run the request in your IDE and you will receive your first message using the Whispir.io API.

Using cURL

cURL is a computer software project providing a library and command-line tool for transferring data using various protocols. One key use of cURL is to make HTTP requests.

In order to test your ability to use the Whispir.io API, cURL is a very quick mechanism to enter on to a command line interface and make sure everything is set up correctly.

Generate your Authorization Header using the form above, and using the code snippets in the code panel, you can execute your first request to the Whispir.io API.

Using a generic REST Client

If you’re unsure about using curl, you can install a REST Client in your browser and test the calls through there. Whispir recommends the following clients:

  1. Postman - Chrome/IE
  2. RESTClient - Firefox

To test your connectivity, you will need to enter the following parameters:

  1. The URL that you would like to request
  2. Your App API Key
  3. Your Authorization Header
  4. (Optional) The Content-Type/Accept Headers

The HTTP call will look like the following:

GET https://api.<region>.whispir.com?apikey=89asdfohasd89023rsd

With the following headers (as a minimum).

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk and x-api-key: 89asdfohasd89023rsd

Once you have executed this request, you should receive a 200 OK response from the REST Client. This means that you have connectivity to the Whispir.io API and can start building your App.

If you received another response, please continue to the next section to understand how to resolve your issues.

Resolving connectivity issues

If you get a different response than HTTP 200 OK, perform the following:

HTTP 403 Forbidden, or HTTP 401 Unauthorized

Other HTTP errors or no connectivity at all

Sending Messages

Sending Messages

Send your first message using curl.

curl -H "Authorization: Basic <YOUR AUTH HEADER>"
     -H "x-api-key: <YOUR API KEY>"
     -H "Content-Type: application/vnd.whispir.message-v1+json"
     -H "Accept: application/vnd.whispir.message-v1+json"
     -d '{
            "to": "<DESTINATION PHONE NUMBER(S)>",
            "subject": "This is the first line of my SMS",
            "body": "This is the content of my SMS"
         }'
     https://api.<region>.whispir.com/messages?apikey=<YOUR API KEY>

Once you submit this, Whispir will send you back an HTTP 202 Accepted stating that your request has been accepted for processing.

Within a few seconds your phone should be buzzing away.

Sending Messages

By now you should be able to connect to the API and can issue requests and receive responses. Based on this, you can now send your first SMS message using the API.

This is very similar to the previous request you executed to test your connectivity, but instead of using an HTTP GET to retrieve information, this time you’re going to use an HTTP POST to ask Whispir to do something.

As you’re sending a message, you need to tell Whispir who to send it to, and what the type of content it is.

You’re going to use the URL https://api.<region>.whispir.com/messages as the API endpoint.

Content Type

Samples in XML / JSON

The following example shows how to use a POST request to send the message in XML or JSON. Use the selector at the top to choose your syntax.

POST https://api.<region>.whispir.com/messages?apikey=89asdfohasd89023rsd
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: 89asdfohasd89023rsd
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
    "to": "<DESTINATION PHONE NUMBER>",
    "subject": "This is the first line of my SMS",
    "body": "This is the content of my SMS"
}
Content-Type: application/vnd.whispir.message-v1+xml
Accept: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>[DESTINATION PHONE NUMBER]</to>
    <subject>This is the first line of my SMS</subject>    
    <body>This is the content of my SMS</body>
</ns2:message>

The next thing you need to do is tell Whispir what information you’re sending. You can just blindly send some XML or JSON content, but life is much easier if Whispir knows exatly what it is you are sending.

You’re going to tell Whispir what you are sending by using the Content-Type HTTP header. Your Content-Type header is going to be (either JSON or XML):

This tells Whispir that you are sending content that conforms to Version 1 of the message schema. As Whispir adds more features to each schema, our version numbers will increase, this is described in much more detail later on in the documentation.

Sending messages using JSON and XML

Once you have successfully sent your SMS message using curl, you can move on to using your application to generate XML or JSON formats for processing.

Be sure to include the correct headers for the desired content type:

For more information on Messages and all the other Whispir resources please continue through the documentation, or browse straight to Messages resource documentation for more information.

API Rate Limits

API Rate Limits

In the event that Whispir’s rate limits are breached, the following error messages will be returned from the Whispir API:

# Over Queries Per Second Limit 

GET /messages?apikey=abc38bc83bcd3ucbud83
x-api-key: abc38bc83bcd3ucbud83

HTTP 403 Forbidden
X-Error-Code: ERR_403_DEVELOPER_OVER_QPS
X-Error-Detail: Account Over Queries Per Second Limit

# Over Queries Per Day Limit

GET /messages?apikey=abc38bc83bcd3ucbud83
x-api-key: abc38bc83bcd3ucbud83

HTTP 403 Forbidden
X-Error-Code: ERR_403_DEVELOPER_OVER_QPD
X-Error-Detail: Account Over Queries Per Day Limit

Whispir’s API usage is limited on a per apikey basis using per second limit and per day limits.

Depending on your Whispir License, you will obtain higher per second and per day rates:

Whispir.io Editions

Whispir.io Edition Requests Per Second Requests Per Day
Startup API Edition 5 requests per second 10000 requests per day
Business API Edition 10 requests per second 20000 requests per day
Enterprise API Edition 30 requests per second 50000 requests per day

If further calls per second or per day are required for your application, please contact your Whispir Sales Representative, or Contact Us.

Auto Extention of daily limits

Whispir enforces a strict daily limit for the API Calls made to its API irrespective of the endpoint and the HTTP Method. At times, there could be a need to temporarily extend the limits of the API Key because you may be experiencing higher than normal activity on your service due to planned or unplanned events. Whispir understands that, and does an automated extention of your api limits to twice the original value for the next 24 hours. This helps in prevention of hitting a wall, and ensures that your messaging traffic flows smoothly. The extention is automatic, and does not need your input or confirmation/action. After 24 hours, the limits are returned to original values. Any auto-extention is free twice a month, and notification will be sent to your account manager whenever the extention happens. Whispir may reach out to discuss commercials if a higher CPD limit is observed continously.

Ex: If you are in Startup Edition, then your per day limits will be doubled to 20k. For Business, it will become 40k, and Enterprise will become 100k. The per second limits remain unchanged at all times.

Conventions

API Security

API Security

Whispir utilises Basic HTTP Authentication over HTTPS to secure the API Requests.

HTTP/1.1 GET https://api.<region>.whispir.com/?apikey=ab37bdvs32898dssddsddsfklio
Authorization: Basic frJIUN8DYpKDtOLCwo//yllqDzg=
x-api-key: your_api_key

# Successful Response
HTTP/1.1 200 OK

# Unsuccessful Response (incorrect apikey)
HTTP/1.1 403 Forbidden
<h1>Developer Inactive</h1>

# Unsuccessful Response (incorrect username / password)
HTTP/1.1 401 Unauthorized

# Unsuccessful Response (no permission to access that resource endpoint)
HTTP/1.1 403 Forbidden

The Whispir.io API supports multiple methods of authentication to cater for varying client needs. Authentication is necessary for users of the API to ensure that only valid and legal requests are processed by the Whispir messaging engine.

Basic Authentication over HTTPS

The basic authentication process is offered for use with clients that already have an ‘up and running’ application, and would like to integrate Whispir as a messaging provider in a quick and simple fashion.

Basic access authentication over HTTPS involves the application client sending an encoded Username and Password when requesting resources from the server.

Clients will also be required to provide the API Key that is provided when the application is registered within Mashery. This API Key is used to determine the application that is making the request, and whether it is allowed to make requests, it is still within the request thresholds, and is a valid API Key. 

Once this has been confirmed, the request is forwarded on to Whispir for Basic authentication processing.

Basic Authentication

Once Whispir has validated the username and password, the requested resource is returned through Mashery to the application client.

Basic Authentication – Example

A valid request that will be accepted and authenticated by the Whispir messaging engine using Basic authentication is as follows:

The ‘Authorization’ header is comprised of the word Basic followed by the base64 representation of the username and password of the user.

More information about HTTP Basic Authentication can be found on Wikipedia.

RESTful Architecture

The Whispir.io API provides interfaces for application clients to utilise Whispir functionality that are platform agnostic, without any dependency on the environment or programming language being used.

Whispir’s API supports multiple methods of inbound request over HTTPS, primarily:

Clients can issue requests using either of the methods, and receive a response in the same format. This allows easy integration with existing and new applications using technologies that are widely supported in a range of languages.

RESTful Architecture

The Whispir.io API employs a ‘REST’ (Representational State Transfer) architecture.  This architecture is the foundation of the World Wide Web and is widely used in application, service and API development.

An application is considered ‘RESTful’ if it conforms to a ‘REST’ architecture.  A ‘REST’ architecture consists of clients and servers.  The clients initiate requests to the servers, and the servers process the requests and return the appropriate responses.  Requests and responses are structured using defined and addressable resources

Each resource within the Whispir API is available through a secure and authenticated URL. 

Note: More information about REST can be found on Wikipedia.

Retrieving objects

Retrieving objects

Retrieve all workspaces within your Company

HTTP/1.1 GET https://api.<region>.whispir.com/workspaces?apikey=bneov3023nfo023rssdf3
HTTP/1.1 GET https://api.<region>.whispir.com/workspaces?apikey=bneov3023nfo023rssdf3

Retrieve all Messages from within the Company

HTTP/1.1 GET https://api.<region>.whispir.com/messages?apikey=bneov3023nfo023rssdf3
HTTP/1.1 GET https://api.<region>.whispir.com/messages?apikey=bneov3023nfo023rssdf3

Application clients can retrieve lists of resources of a single type through a simple URL. 

For example, to retrieve a list of Workspaces from within the Company, the URL is as follows:

GET https://api.<region>.whispir.com/workspaces?apikey=bneov3023nfo023rssdf3

Retrieving a single object

Retrieving a single object

Retrieve the Workspace with the ID of 12345

HTTP/1.1 GET https://api.<region>.whispir.com/workspaces/12345?apikey=bneov3023nfo023rssdf3
HTTP/1.1 GET https://api.<region>.whispir.com/workspaces/12345?apikey=bneov3023nfo023rssdf3

Application clients also have access to a single resource by specifying the relevant ID of the resource.  This information would have been returned when retrieving the list of resources as specified above.

To retrieve a single Workspace when you know the ID, the URL is as follows:

GET https://api.<region>.whispir.com/workspaces/12345?apikey=bneov3023nfo023rssdf3

Or to retrieve a single Contact when you know the ID, the URL is as follows:

GET https://api.<region>.whispir.com/contacts/78910?apikey=bneov3023nfo023rssdf3

Retrieve the Contact with the ID of 78910

HTTP/1.1 GET https://api.<region>.whispir.com/contacts/78910?apikey=bneov3023nfo023rssdf3
HTTP/1.1 GET https://api.<region>.whispir.com/contacts/78910?apikey=bneov3023nfo023rssdf3

Nested objects

Nested objects

Retrieve the Contact with the ID 67890 from within the Workspace with ID 12345

HTTP/1.1 GET https://api.<region>.whispir.com/workspaces/12345/contacts/67890?apikey=bneov3023nfo023rssdf3
HTTP/1.1 GET https://api.<region>.whispir.com/workspaces/12345/contacts/67890?apikey=bneov3023nfo023rssdf3

Within Whispir’s resource model, some resources are nested within one another.  For example;

Requests can be nested in order to provide application clients the ability to access specific resources when they are nested.

For example, if you wanted to retrieve a Contact from within a Workspace, the URL would look as follows:

GET https://api.<region>.whispir.com/workspaces/12345/contacts/67890?apikey=bneov3023nfo023rssdf3

HTTP Response Codes

Application clients that are using Whispir’s API will receive HTTP response codes in response to every request that is issued. 

The table below describes the response codes that will be issued and gives potential reasons as to why they may have been sent back.

Successful Response Codes
200 OK: Successful request
No further action required.
201 Created: Successfully created the resource.
The requested resource has been successfully created and can be found via the URL in the ‘Location’ header
202 Accepted: Successfully accepted the request for processing
The request has been accepted for processing by the asynchronous processor. The request’s unique identifier can be found via the URL in the 'Location’ header
204 No Content: Successfully processed the request, but no content was sent back
The update (PUT) or delete (DELETE) request has been successfully processed, and no content was returned from the server.
301 Moved Permanently: Successful request, but the resource is no longer available at this location.
This resource URL should no longer be used. Check the location header of the response and redirect the request there.
302 Found: Successful request, but the resource is temporarily not available at this location.
This resource URL should still be used in future, but for this specific request, check the location header of the response and redirect the request there.
304 Not modified: Content hasn’t changed since last request
No action required
Unsuccessful Response Codes
400 Bad Request: Invalid or missing request parameters
Inspect the request parameters and ensure that all required parameters are supplied.

Note the error text in the response and update the request accordingly
401 Unauthorized: Invalid or no credentials passed in the request
Inspect the authorisation header and ensure that a valid authentication has been provided.
403 Forbidden: Authorization credentials passed and accepted but account does not have permission
  • Inspect the authorisation header and ensure that a valid authentication has been provided.
  • returned when HTTP is used instead of HTTPS
  • returned when invalid API Key is used
  • returned when you have tried to make API calls more than your allowed Quota (QPS). refer to API Rate Limits
404 Not Found: The requested URL does not exist
The requested resource was not found, inspect the ID in the URL that was used and ensure that it is valid.

Also, inspect the Accept and Content-Type headers that are being used to make sure they are correct for the URL that is being requested.
405 Method not allowed: The requested resource does not support the supplied verb
Inspect the HTTP method that was used in the request and ensure that it is valid for the resource being requested
415 Unsupported Media Type: The request was unsuccessful because the requested content type is not supported by the API.
The application client can use this response to determine if it is asking for a supported version of a resource.  Upon receiving this response, the client can query the developer documentation to determine the appropriate version for the requested resource.

In most cases, this is due to the user not supplying the correct Accept or Content-Type header for the requested URL.
429 Too many requests: Above API Quota Limits
  • returned when you have tried to make API calls more than your allowed Quota (QPS). refer to API Rate Limits
422 Unprocessable Entity: The request is formed correctly, but due to some condition the request cannot be processed e.g. email is required and it is not provided in the request
The request did not contain all of the information required to perform this method.  Please check your request for the required fields to be passed in and try again.  The offending fields will be specified in the error text of the response.
500 Internal Server Error: An internal error occurred when processing the request.
Attempt the request again and if the HTTP 500 error re-occurs contact support@whispir.com
501 Method Not Implemented: The HTTP method being used has not yet been implemented for the requested resource.
The method being used is not implemented for this resource. Please check the documentation for the specific resource type. 

Content Types and Versioning

The Whispir.io API has been designed and built to support the wide feature set provided in the current version of the Whispir Platform. 

In order to manage and incorporate change in future versions of the API, Whispir’s API has implemented a versioning structure that allows application clients to choose which version of the API they would like to retrieve their responses from.

This allows new versions to be built and old versions to be supported concurrently, with no impact to clients when changes are made.

Whispir’s API achieves this versioning capability by using Vendor Specific MIME Types (VSMT).

Without VSMT

Without VSMT

A Sample API request that is not using VSMT

HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264 
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml
<contact>
   <name>Neil Armstrong</name>
</contact>

This implementation of an API in this manner works correctly, but conceptually it is incorrect.  The issue with this design is the request is only asking for an XML representation of some resource called a Contact, it is not specifically asking for the XML version of a Contact Resource as defined by Whispir’s API.

Any XML representation of a resource could be passed back e.g. a Cat or a House, and the client would need to inspect the response to determine whether it is a Contact or not through its own means.

With VSMT

With VSMT

A Sample API request that is uses VSMT

HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264 
Accept: application/vnd.whispir.contact+xml

HTTP/1.1 200 OK
Content-Type: application/xml
<contact>
   <name>Neil Armstrong</name>
</contact>

By using VSMT, Whispir can define and make available the various content types for resources prior to the requests being made. This allows the application clients to specify the resource that they would like to receive from the API, and Whispir will only return content of that specific type.

For example:

By using this method, the client is specifically asking for a resource representation of a Contact that is defined by Whispir’s API.  There is no confusion about the representation that will be returned, and the client need not worry about validation as Whispir will only ever return a valid Contact as a response to this request.

VSMT also allows the client the ability to choose the language in which their resource representation should be returned.  Using the previous example, the application client was asking for the Contact to be returned in XML.

Accept: application/vnd.whispir.contact+xml

This Contact resource could just as easily be returned as a JSON object by changing the content type as follows:

Accept: application/vnd.whispir.contact+json

With VSMT (including versioning)

With VSMT (including versioning)

Sample request with VSMT and Versioning (V1)

HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264 
Accept: application/vnd.whispir.contact-v1+xml

HTTP/1.1 200 OK
Content-Type: application/vnd.whispir.contact-v1+xml
<contact>
   <name>Neil Armstrong</name>
</contact>

Sample request with VSMT and Versioning (V2)

HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264 
Accept: application/vnd.whispir.contact-v2+xml

HTTP/1.1 200 OK
Content-Type: application/vnd.whispir.contact-v2+xml
<contact>
   <name>Neil Armstrong</name>
   <mobile>$mobile</mobile>
   <email>neil.armstrong@space.com</email>
</contact>

This method of using VSMT also allows the resource representations to be updated, re-written and maintained without any notification required to application clients.

This can be achieved by adding a version element to the defined content types.

By versioning the application MIME types, application clients can request the resource representation that their application is built on, e.g. ‘contact-v1’, or ‘workspace-v2’.

Whispir can create new representations of these documents, and the application clients will not be affected by these changes.

The v2 version of this resource representation can co-exist with the v1 version, and application clients do not need to worry about their existence.

Deprecation of Versions

As the version numbers grow and new features are introduced into the resource representations, it is inevitable that the older versions will become deprecated and no longer supported over an extended period of time.

This process of deprecation will be facilitated using HTTP Status Codes 301 and 415.

List of Whispir’s VSMT’s

The following table depicts the available mime types that will be accepted through Whispir’s API:

Note: The Mime Type is always Singular. message-v1, not messages-v1.

List of Whispir.io VSMT’s
Workspace: XML - application/vnd.whispir.workspace-v1+xml
JSON - application/vnd.whispir.workspace-v1+json
Message: XML - application/vnd.whispir.message-v1+xml
JSON - application/vnd.whispir.message-v1+json
Message Status: XML - application/vnd.whispir.messagestatus-v1+xml
JSON - application/vnd.whispir.messagestatus-v1+json
Message Responses: XML - application/vnd.whispir.messageresponse-v1+xml
JSON - application/vnd.whispir.messageresponse-v1+json
Message Response Rule: XML - application/vnd.whispir.responserule-v1+xml
JSON - application/vnd.whispir.responserule-v1+json
Message Template: XML - application/vnd.whispir.template-v1+xml
JSON - application/vnd.whispir.template-v1+json
Contact: XML - application/vnd.whispir.contact-v1+xml
JSON - application/vnd.whispir.contact-v1+json
Distribution List: XML - application/vnd.whispir.distributionlist-v1+xml
JSON - application/vnd.whispir.distributionlist-v1+json
Message Scenario: XML - application/vnd.whispir.scenario-v1+xml
JSON - application/vnd.whispir.scenario-v1+json
Event: XML - application/vnd.whispir.event-v1+xml
JSON - application/vnd.whispir.event-v1+json
Asset: XML - application/vnd.whispir.asset-v1+xml
JSON - application/vnd.whispir.asset-v1+json
Custom List: XML - application/vnd.whispir.customlist-v1+xml
JSON - application/vnd.whispir.customlist-v1+json
Activity Log: XML - application/vnd.whispir.activity-v1+xml
JSON - application/vnd.whispir.activity-v1+json
User: XML - application/vnd.whispir.user-v1+xml
JSON - application/vnd.whispir.user-v1+json

Pagination

Pagination

Request for the first page of messages:

HTTP/1.1 GET https://api.<region>.whispir.com/?apikey=[your-api-key]&limit=20&offset=0

Request for the second page of messages (note the offset is now 20):

HTTP/1.1 GET https://api.<region>.whispir.com/?apikey=[your-api-key]&limit=20&offset=20

Request for the page of messages which does not exist.

HTTP/1.1 GET https://api.<region>.whispir.com/workspaces/7311ABEB701E7C60/messages?apikey=[your-api-key]&limit=20&offset=20
<?xml version="1.0" encoding="UTF-8" standalone="true"?>
<ns2:return xmlns:ns3="http://schemas.api.whispir.com" xmlns:ns2="http://schemas.api.whispir.com/dap">
    <status>No records found</status>
</ns2:return>
{
    "status" : "No records found"
}

Requests that contain multiple items will be paginated by default.

Each page will provide a maximum of 20 items per page.

Two parameters can be used to control the number of items retrieved:

Most resources will provide these links at the end of the response object in a link array that supplies links with rel=next and rel=prev attributes.

This makes programatic pagination easy as you can simply detect for the presence of these attributes. You can loop through the pages until you receive a response of 'No messages found’.

Note: The following resources aren’t paginated for ease of use:

Extra parameters

It’s also possible that the messages are older than the default filter that is applied. At present Whispir provides a default of the last 7 days of messages. You can ask for older messages by using the following 4 parameters:

Requesting for records from 01/01/2015 00:00 – 01/07/2015 23:59

https://api.<region>.whispir.com/messages?apikey=[your-api-key]&criteriaFromDate=01/01/2015&criteriaFromTime=00:00&criteriaToDate=01/07/2015&criteriaToTime=23:59

All four of these parameters are required for a date search to work e.g.

You can also use the parameter viewType=shared if the messages you are looking for were sent from other users (not the API user).

Case Sensitivity of Headers

As per RFC-2616, the headers in both the request and response are case in-sensitive. Please ensure your integration takes this into note when interacting with Whispir API.

Workspaces

API Endpoint

  • generic
https://api.<region>.whispir.com/workspaces/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.workspace-v1+xml
https://api.<region>.whispir.com/workspaces/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.workspace-v1+json
> Resource type

- application/vnd.whispir.workspace-v1+xml
- application/vnd.whispir.workspace-v1+json


> Methods supported

- GET
- POST

Workspace allows application developers to create new work areas for the varying use cases of their application. They provides different functions that can be provided to users of the application, e.g. creating messages, executing scenarios, or viewing distribution lists.

Every account upon creation is given a default workspace. All operations are usually carried out in the default workspace. To separate the concerns, one can create multiple (there is no limit) workspaces suited for each of their application needs.

Each of these work areas are independent from one another and can be governed by user permissions. So, users can be assigned access to these workspaces to restrict the control of information as needed. So, the information, assets, contacts, actions performed in workspace does not or cannot be accessed from another one. This allows the applications to be independent and audited much effectively with proper permissions and keys.

Creating a new workspace

HTTP 1.1 POST https://api.<region>.whispir.com/workspaces?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.workspace-v1+xml 


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:workspace xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <projectName>A Space Odessey</projectName>
    <projectNumber>2000</projectNumber>
    <status>A</status>
    <billingcostcentre>Hollywood</billingcostcentre>
</ns3:workspace>
Content-Type: application/vnd.whispir.workspace-v1+json

{
  "projectName": "A Space Odessey",
  "projectNumber": "2001",
  "status": "A",
  "billingcostcentre": "Hollywood"
}

To create a new workspace, you can use the /workspaces endpoint.

Only 2 fields are required:

  1. projectName - The name of the Workspace to be created.
  2. status - The status of the Workspace being created. This should be ‘A’ for 'Active’ when creating new workspaces.

Note: There is no limit to the amount of workspaces each API user can create.

High-Level Request Elements
projectName : String
Specifies the name of the Workspace to be created.
projectNumber: String
Specifies the reference ID for the workspace from the User Side. Generally not used.
Note: This is not the actual workspace ID. It is just a custom reference ID given by you for your own purposes.
status: String
Specifies the status of the Workspace being created. The status can be one of -
  • Active (A)
  • Disabled (D)
billingcostcentre: String
Only applicable to customers with the Billing Cost Centre Module enabled. Allows the user to set a billing cost centre for the Workspace.

Retrieving Workspaces

To retrieve a list of workspaces from the Whispir.io API you can execute an HTTP GET using the /workspaces endpoint.

HTTP 1.1 GET https://api.<region>.whispir.com/workspaces?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Accept: application/vnd.whispir.workspace-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 4 of 4</status>
    <ns2:workspaces>
        <ns2:workspace>
        <id>BB9ECBE5BA73CD81</id>
        <projectName>Sales Lead Notifications</projectName>
            <projectNumber></projectNumber>
            <status>A</status>
            <billingcostcentre>test</billingcostcentre>
            <ns2:link uri="https://api.<region>.whispir.com/workspaces/BB9ECBE5BA73CD81?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:workspace>
        <ns2:workspace>
            <id>7311ABEB701E7C60</id>
        <projectName>Product Release Management</projectName>
            <projectNumber></projectNumber>
            <status>A</status>
            <billingcostcentre>0</billingcostcentre>
            <ns2:link uri="https://api.<region>.whispir.com/workspaces/7311ABEB701E7C60?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:workspace>
        <ns2:workspace>
            <id>26B1A09C1FEC20A2</id>
        <projectName>CAAS</projectName>
            <projectNumber></projectNumber>
            <status>A</status>
            <billingcostcentre>0</billingcostcentre>
            <ns2:link uri="https://api.<region>.whispir.com/workspaces/26B1A09C1FEC20A2?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:workspace>
        <ns2:workspace>
            <id>A358845BF004C113</id>
        <projectName>Business Working Group</projectName>
            <projectNumber></projectNumber>
            <status>A</status>
            <billingcostcentre>CLSA</billingcostcentre>
            <ns2:link uri="https://api.<region>.whispir.com/workspaces/A358845BF004C113?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:workspace>
        <ns2:workspace>
            <projectName>Critical Incident Management</projectName>
            <projectNumber></projectNumber>
            <status>A</status>
            <billingcostcentre></billingcostcentre>
            <ns2:link uri="https://api.<region>.whispir.com/workspaces/B7BFEF555F0F7F81?apikey=[your_api_key]" rel="self" method="GET"/>
       </ns2:workspace>
    </ns2:workspaces>
</ns2:return>
Accept: application/vnd.whispir.workspace-v1+json

{
  "workspaces": [
    {
      "id": "7311ABEB701E7C60",
      "projectName": "Sales Lead Notifications",
      "projectNumber": "",
      "status": "A",
      "billingcostcentre": "0",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/workspaces/7311ABEB701E7C60?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "26B1A09C1FEC20A2",
      "projectName": "Product Release Management",
      "projectNumber": "",
      "status": "A",
      "billingcostcentre": "0",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/workspaces/26B1A09C1FEC20A2?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "A358845BF004C113",
      "projectName": "Business Working Group",
      "projectNumber": "",
      "status": "A",
      "billingcostcentre": "CLSA",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/workspaces/A358845BF004C113?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "B7BFEF555F0F7F81",
      "projectName": "Critical Incident Management",
      "projectNumber": "",
      "status": "A",
      "billingcostcentre": "",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/workspaces/B7BFEF555F0F7F81?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
   ]
}

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

An array of Workspaces will be returned to you in the HTTP response body.

Each of these workspace will provide the following information:

High-Level Response Elements
projectName : String
Specifies the name of the Workspace to be created.
projectNumber: String
Specifies the reference ID for the workspace from the User Side. Generally not used.
Note: This is not the actual workspace ID. It is just a custom reference ID given by you for your own purposes.
status: String
Specifies the status of the Workspace being created. The status can be one of -
  • Active (A)
  • Disabled (D)
billingcostcentre: String
Only applicable to customers with the Billing Cost Centre Module enabled. Allows the user to set a billing cost centre for the Workspace.
link: Array
Provides a list of URLs that can be used to manipulate or access the workspace.
  • uri - the link to access the workspace
  • rel - the descriptor for what the link will do
  • method - the HTTP method to use with this particular link

Updating, Deleting a workspace

Workspaces can only be created and retrieved. They cannot be updated or deleted via the API.

One has to use the Platform for this need.

Messages

API Endpoint

The following calls describe how to access messages from within your workspaces

<!-- From the default workspace -->

https://api.<region>.whispir.com/messages/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.message-v1+xml
// From the default workspace

https://api.<region>.whispir.com/messages/?apikey=<your_api_key>
Accept: application/vnd.whispir.message-v1+json
<!-- Or from a defined workspace -->

https://api.<region>.whispir.com/workspaces/{:id}/messages/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.message-v1+xml
// Or from a defined workspace

https://api.<region>.whispir.com/workspaces/{:id}/messages/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.message-v1+json

The following resource types are supported for messages.

- application/vnd.whispir.message-v1+xml
- application/vnd.whispir.message-v1+json

The following methods are supported for the messages endpoint.

- GET
- POST
- DELETE

Messages

Sample to send an SMS, Email, Voice call, and Web Publishing in one request

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]
Authorization: Basic <YOUR AUTH HEADER>
x-api-key: your_api_key
Content-Type: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test Message</subject>
    <body>This is the body of my test SMS message</body>
    <email>
        <body>This is the body of my test Email message</body>
        <footer>This is footer of test email</footer>
        <type>text/plain</type>
    </email>
    <voice>
        <header>test header</header>
        <body>This is test voice body</body>
        <footer>test footer</footer>
        <type>
            ConfCall:,
            ConfAccountNo:,
            ConfPinNo:,
            ConfModPinNo:,
            Pin:
        </type>
    </voice>
    <web>
        <body>This is web body of my test message</body>
        <type>text/plain</type>
    </web>
    <social>
        <social id="social">
            <body>Twitter Content.</body>
        </social>
        <social id="social_long">
            <body>Facebook Content.</body>
            <type>text/plain</type>
        </social>
    </social>
    <type>defaultNoReply</type>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "$mobile",
    "subject" : "Test Message",
    "body" : "This is the body of my test SMS message",
    "email" : {
        "body" : "This is the body of my test Email message",
        "footer" : "This is the footer of my message
                    (generally where a signature would go)",
        "type" : "text/plain"
    },
    "voice" : {
        "header" : "This is the introduction,
                    read out prior to any key press",
        "body" : "This is the body of the voice call,
                  read out after the key press",
        "type" : "ConfCall:,
                  ConfAccountNo:,
                  ConfPinNo:,
                  ConfModPinNo:,
                  Pin:"
    },
    "web" : {
        "body" : "This is the content of my web publishing
                 or Rich Push Message",
        "type" : "text/plain"
    },
    "social" : {
        "social" : [
        {
            "id" : "social",
            "body" : "Twitter Content."
        },
        {
            "id" : "social_long",
            "body" : "Facebook Content.",
            "type" : "text/plain"
        }
    ]
    },
    "type" : "defaultNoReply",
    "features" : {
        "pushOptions" : {
            "notifications" : "enabled",
            "escalationMins" : "3"
        }
    }
}

Communications are the core of what the Whispir.io API offers as a service to customers.

Whispir has the ability to send communications across 8 different channels in a single API request:

SMS - up to 1600* characters per message, premium routes, delivery receipts
Email - free email messaging with HTML and Plain Text support
Voice - high quality outbound voice calls delivered to mobiles and landlines within seconds
Rich Messages - personalised, targeted rich messaging to drive conversations
Push - easily sent push notifications to your apps
Twitter - support for instant publishing to multiple twitter accounts
Facebook - simplify the process of publishing to multiple facebook accounts instantaneously
RSS - easily generate RSS feeds for consumption by other services

All communications are driven from the /messages endpoint within the API. This endpoint allows a user to perform the following tasks:

  1. Create and Send a new message in a given workspace
  2. Retrieve a list of previously sent messages in the given workspace

These are described in more detail below:

As message resources can exist in the default (Company) workspace or other workspace, messages have two access URLs:

https://api.<region>.whispir.com/messages - for Company Workspace messages

https://api.<region>.whispir.com/workspaces/:id/messages - for other Workspace messages where :id is the id of the specific workspace.

High-Level Request Elements
to: String
Specifies the recipients of the message e.g.
  • Mobile Phone: 61423456789
  • Email Address: john.smith@test.com.au
  • Landline: 61386000000
Note: Multiple recipients can be specified using semicolons
subject: String
Specifies the first line of the SMS message or Voice call, and the subject of the Email message.
body: String
Specifies the content of the SMS message.
email: Object
Email object described below. Used for sending email messages.
voice: Object
Voice object described below. Used for sending voice calls to mobile phones and landlines.
web: Object
Web object described below. Used for web publishing and Rich Messages.
social: Object
Social object described below. Used for publishing content to social media (Twitter, Facebook, LinkedIn).
type: String
Allows the user to modify the message behaviour for replies e.g.
  • defaultNoReply - Used to reject any replies to this message. This is also used to mask the sender’s phone number when not using a Message Alias.
dlr: Object
Allows the user to specify the turn ON or turn OFF the DLRs (delivery receipts) via the `type` option e.g.
  • NoDlr - Used to specify that DLRs should not be enabled for this message.

Usage:
  • for XML:
  • NoDlr
  • for JSON:
  • "dlr":{ "type": "NoDlr" }
features: Object
Allows the user to modify the push notifications properties if these are configured in the company.

pushOptions:
  • notifications - enabled/disabled
  • escalationMins - # mins to await a push notifications response
  • appId - the appId to which the push notifications has to be sent to

SMS Messages

SMS Messages

Sending SMS messages using Whispir is as easy as providing the destination phone number(s), a message subject, and the content of the message.

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+xml
Accept: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test SMS Message</subject>
    <body>This is the body of my test SMS message</body>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
   "to" : "$mobile",
   "subject" : "Test SMS Message",
   "body" : "This is the body of my test SMS message"
}
Response: 202 Accepted
Location: https://api.<region>.whispir.com/messages/{id}?apikey=[your_api_key]

Sending SMS from Whispir is as easy as providing the recipient information and the content of the message.

Only 3 fields are required:

  1. To - the mobile phone number of the recipient
  2. Subject - the first line or identifier of the SMS
  3. Body - the remainder of the SMS content

The ‘to’ field can be provided in the following formats:

'To’ field options
Ad-hoc Recipients String
  • Mobile Phone: 61423456789
  • Email Address: john.smith@test.com.au
  • Landline: 61386000000
Defined Whispir Recipients String
  • Contact MRI:
    John_Smith.782749@Contact.whispir.com
  • User MRI:
    John_Smith@User.whispir.com
  • Distribution List MRI:
    Incidents.373947@List.whispir.com

Notes:

* SMS character counts are limited in some countries. Contact your local Whispir Representative for information about the supported number of characters in your region.

Response

Email Messages

Email Messages

Sending Plain Text Emails

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>john.smith@test.com</to>
    <subject>Test Email Message</subject>
    <email>
        <body>Email Body goes here.</body>
        <footer>Email signature goes here.</footer>
        <type>text/plain</type>
    </email>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
    "to" : "john.smith@test.com",
    "subject" : "Test Email Message",
    "email" : {
        "body" : "Email Body goes here.",
        "footer" : "Email signature goes here.",
        "type" : "text/plain"
    }
}

Sending Rich Text (HTML) Emails

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>john.smith@test.com</to>
    <subject>Test Email Message</subject>
    <email>
        <body>
            <![CDATA[
                <div id="content">
                    <p>This is my content</p>
                </div>
            ]]>
        </body>
        <type>text/html</type>
    </email>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
    "to" : "john.smith@test.com",
    "subject" : "Test Email Message",
    "email" : {
        "body" : "<div id='content'><p>This is my content</p></div>",
        "type" : "text/html"
    }
}

Whispir can easily be used as an API email gateway to deliver thousands of rich content emails for your campaigns.

Mandatory fields

Only 4 fields are required in order to send an email message.

  1. To - the recipient of the email message.
  2. Subject - the subject line of the email message.
  3. Body - the content of the email (either HTML or Plain Text content).
  4. Type - either 'text/plain’ or 'text/html’ to describe the content of the message.

Whispir’s support of Rich (HTML) Emails

Sending Emails with Attachments

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>john.smith@test.com</to>
    <subject>Test e-mail message with attachment</subject>
    <email>
        <body>Test Message Content</body>
        <type>text/plain</type>
    <resources>
            <attachment>
                <attachmentName>TestIcon.png</attachmentName>
                <attachmentDesc>TestIcon.png</attachmentDesc>
                <derefUri>iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAIAAADUsmlHAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAMvSURBVDhPTVT5S1RhFD3fezOOOePTXHKriWgj
sogWC1TSMuuHIFqoX0KsIIgSWwiq/6FFU8MKK6KyXYSKpkUKR4QMSSpCLQpyxHHUZpztzdu63xub
5vKWj/fu+c6599z3mMfjSU9P13UdZoiCaLfZYQWiUGKq1WrBLEBDOBpWNTWeQyEIwvT0NAsEAgRO
PKXFxceNbQOtv4ShkKCkaZZ5kYU1Sw6dqT0NMTkLBIbf7zf+xaOuJzgG4RmyPyP/Kwq/oWAYeT+R
6gYOofnmlUQmLQjI6JQkifasu368KdCQWwFEwBiYQOIgiDBETDFIORh/iZ0De55cehgXQJIphce9
d/ebJhuyV0P3QY9Cj/HDUKhseIPomP/CW2QYB42nSx+db76YUM9IusPhYHVM2g5Bpo5xNuIkZibC
F8On0oGVjhWabmR8EBx5GDuHaItsy0zhzA6bo/H5ZSyDMQ1d4YQa0Sqc1hdAe3E7IYkqp9tiUcHG
kXIQZ8+fm+k5uXK3/46YAV3mMMLEt/BHUJ1Vua9oH+WV9ayLyLpVhRYFkT8d4mUzRuI0DAcHmQng
SLrGoBJ/GC/L31JSy/cm91ifXTcboYDJGLX+1kI6WS3AQFSRCUDvwhGEwubiD1yVLkLKWuxoT50k
zGwab6Ru6HIsahpiwTybkwTLU9iUU1Ezf394CmuyV20p2kLg8mcbRHLLxGimLlWFFMpMc6TRFlx2
9aJqePBgx4M3u7tubb1dMXfjw6rHhOwb+/jhV3+qNtMFKspQEZnA+oxSPr9UdjgUllV59pHZhSUF
I/We5AnMv5o7bvhsFu5f3DlmR7ATr/a+rtq2mVulqEqmlFlbUuv5MbqudW0C7PrhGpvwidRhIoyX
qiHoRam/tGrT5n9Wmfcb9TfmBOf0DXy80H0h/uKU6yQRcqlmk+mji0RhbbN2XOpAygzF/9nmfp4o
c4+4y6vLqRnuUTdsfNqYFRop/4JFw4t723qz52YlZpvPd/K30vm+03nAie1ADXAYOADsgHOXs/la
ix7RkzMJyJJ/BjQ09lQ7me8f9/cP9nsnvemzpOIFy3PzclkK0wyNgvDEHP8Z/AXQ58rAz69IBAAA
AABJRU5ErkJggg==</derefUri>
            </attachment>
        </resources>
    </email>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
    "to" : "jsmith@test.com",
    "subject" : "Test e-mail message with attachment",
    "email" : {
        "body" : "This is my content",
        "type" : "text/plain",
        "resources" : {
            "attachment" : [{
                "attachmentName" : "TestIcon.png",
                "attachmentDesc" : "TestIcon.png",
                "derefUri" : "iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAIAAADUsmlHAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAMvSURBVDhPTVT5S1RhFD3fezOOOePTXHKriWgj
sogWC1TSMuuHIFqoX0KsIIgSWwiq/6FFU8MKK6KyXYSKpkUKR4QMSSpCLQpyxHHUZpztzdu63xub
5vKWj/fu+c6599z3mMfjSU9P13UdZoiCaLfZYQWiUGKq1WrBLEBDOBpWNTWeQyEIwvT0NAsEAgRO
PKXFxceNbQOtv4ShkKCkaZZ5kYU1Sw6dqT0NMTkLBIbf7zf+xaOuJzgG4RmyPyP/Kwq/oWAYeT+R
6gYOofnmlUQmLQjI6JQkifasu368KdCQWwFEwBiYQOIgiDBETDFIORh/iZ0De55cehgXQJIphce9
d/ebJhuyV0P3QY9Cj/HDUKhseIPomP/CW2QYB42nSx+db76YUM9IusPhYHVM2g5Bpo5xNuIkZibC
F8On0oGVjhWabmR8EBx5GDuHaItsy0zhzA6bo/H5ZSyDMQ1d4YQa0Sqc1hdAe3E7IYkqp9tiUcHG
kXIQZ8+fm+k5uXK3/46YAV3mMMLEt/BHUJ1Vua9oH+WV9ayLyLpVhRYFkT8d4mUzRuI0DAcHmQng
SLrGoBJ/GC/L31JSy/cm91ifXTcboYDJGLX+1kI6WS3AQFSRCUDvwhGEwubiD1yVLkLKWuxoT50k
zGwab6Ru6HIsahpiwTybkwTLU9iUU1Ezf394CmuyV20p2kLg8mcbRHLLxGimLlWFFMpMc6TRFlx2
9aJqePBgx4M3u7tubb1dMXfjw6rHhOwb+/jhV3+qNtMFKspQEZnA+oxSPr9UdjgUllV59pHZhSUF
I/We5AnMv5o7bvhsFu5f3DlmR7ATr/a+rtq2mVulqEqmlFlbUuv5MbqudW0C7PrhGpvwidRhIoyX
qiHoRam/tGrT5n9Wmfcb9TfmBOf0DXy80H0h/uKU6yQRcqlmk+mji0RhbbN2XOpAygzF/9nmfp4o
c4+4y6vLqRnuUTdsfNqYFRop/4JFw4t723qz52YlZpvPd/K30vm+03nAie1ADXAYOADsgHOXs/la
ix7RkzMJyJJ/BjQ09lQ7me8f9/cP9nsnvemzpOIFy3PzclkK0wyNgvDEHP8Z/AXQ58rAz69IBAAA
AABJRU5ErkJggg=="
            }]
        }
    }
}

Including attachments in e-mail messages

The Whispir API provides users with the ability to compose e-mail messages that also contain message attachments.

Attachments can be of any type (e.g. PDF, Images, Documents), and can be up to 10MB in size (maximum for all attachments).

Attachments must be provided in the payload of the message. URLs can be referenced in the Email, but will not be added as message attachments.

Notes:

Voice Messages

Voice Messages

Sending Voice Calls

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test Voice Call</subject>
    <voice>
        <header>
            This is the introduction of the voice call
        </header>
        <body>This is the body of the message</body>
        <!-- Do not include line breaks in your API calls -->
        <type>
            ConfCall:,
            ConfAccountNo:,
            ConfPinNo:,
            ConfModPinNo:,
            Pin:
        </type>
    </voice>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "$mobile",
    "subject" : "Test Voice Call",
    "voice" : {
        "header" : "This is the introduction of the voice call",
        "body" : "This is the body of the message",
        "type" : "ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:"
    }
}

Sending Voice Calls with Teleconferences

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test Voice Call</subject>
    <voice>
        <header>
            This is the introduction of the voice call
        </header>
        <body>This is body of the message</body>
        <footer>This is the footer of the message</footer>
        <!-- Do not include line breaks in your API calls -->
        <type>
            ConfCall:1800500536,
            ConfAccountNo:12345678,
            ConfPinNo:1234,
            ConfModPinNo:1234,
            Pin:0000
        </type>
    </voice>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "$mobile",
    "subject" : "Test Voice Call",
    "voice" : {
        "header" : "This is the introduction of the voice call",
        "body" : "This is body of the message",
        "footer" : "This is the footer of the message",
        "type" : "ConfCall:1800500536,
                  ConfAccountNo:12345678,
                  ConfPinNo:1234,
                  ConfModPinNo:1234,
                  Pin:"
    }
}

Whispir’s API provides users the ability to send a Voice Call to any landline or mobile phones around the world.

Whispir supports both Text to Speech and Pre-recorded WAV file approaches to sending Voice Calls.

Using Whispir’s Voice Module, you can easily connect all recipients onto a single bridged call, simplifying your teleconferences and ensuring your message gets through.

Notes:

Your account must be enabled to use the Voice capability within Whispir for this to function. If you are unsure whether you can use Voice please contact support@whispir.io.

Custom Variables for Voice Calls
@@teleconf_number@@ When Teleconferencing Services are used as part of voice calls, the Teleconference line that is used in the voice call can be accessed via this variable.
e.g. 1800 123 123
@@teleconf_account@@ When Teleconferencing Services are used as part of voice calls, the Teleconference Account or Room number that is used in the voice call can be accessed via this variable.
e.g. 098711234
@@teleconf_pin@@ When Teleconferencing Services are used as part of voice calls, the Teleconference Room PIN that is used in the voice call can be accessed via this variable.
e.g. 8181
@@teleconf_mod_pin@@ When Teleconferencing Services are used as part of voice calls, the Teleconference Moderator PIN that is used in the voice call can be accessed via this variable.
e.g. 8181

Using custom WAV files as the content for Voice Calls

The Whispir API provides users with the ability to compose voice calls using Text-To-Speech (TTS) as well as allowing users to provide custom WAV files to be played over the phone.

Attachments must be WAV files and can be up to 10MB in size (maximum for all attachments).

Each Voice Call is made up of four parts:

  1. Message Introduction - Either TTS or WAV file, mandatory for all messages
  2. Message Acceptance - Requests the recipient to press a button to accept the message
  3. Message Content - The concatenation of the Message Subject and Message Body (either TTS or WAV file)
  4. Message Response - Allows the recipient to provide an acknowledgement to the message, either default options or based off a response rule
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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>61423568958</to>
    <subject>Test voice call with attachment</subject>
    <voice>
        <body>Will be replaced by the voicebody.wav file</body>
        <header>Will be replaced by the voiceintro.wav file</header>
        <type>ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:</type>
        <resources>
            <attachment>
                <attachmentName>Introduction.wav</attachmentName>
                <attachmentDesc>voiceintro.wav</attachmentDesc>
                <derefUri>...</derefUri>
            </attachment>
            <attachment>
                <attachmentName>Body.wav</attachmentName>
                <attachmentDesc>voicebody.wav</attachmentDesc>
                <derefUri>...</derefUri>
            </attachment>
        </resources>
    </voice>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json


{
    "to" : "61423568958",
    "subject" : "Test voice call with attachments",
    "voice" : {
        "body" : "Will be replaced by the voicebody.wav file",
        "header" : "Will be replaced by the voiceintro.wav file",
        "type" : "ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:",
        "resources" : {
            "attachment" : [{
                "attachmentName" : "Introduction.wav",
                "attachmentDesc" : "voiceintro.wav",
                "derefUri" : "..."
            },{
                "attachmentName" : "Body.wav",
                "attachmentDesc" : "voicebody.wav",
                "derefUri" : "..."
            }]
        }
    }
}

WAV File Criteria

Before a WAV file will be played, it needs to conform to a certain criteria.

Notes:

Rich Messages

Rich Messages

Simple Rich Message using SMS with a Web Link

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test Rich Message</subject>
    <body>This is some content followed by the Rich Message link @@web_link@@</body>
    <web>
        <type>text/html</type>
        <body>
            <![CDATA[
                <div id="content">
                    <p>This is the body of my Rich Message</p>
                </div>
            ]]>
        </body>
    </web>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
   "to" : "$mobile",
   "subject" : "Test Rich Message",
   "body" : "This is some content followed by the Rich Message link @@web_link@@",
   "web" : {
      "type" : "text/html",
      "body" : "<div class='content'>This is the body of my Rich Message</div>"
   }
}

Whispir’s Javascript API

Users can use Whispir’s Javascript API to perform different functions from within Rich Messages. The following example uses javascript to personalise the Rich Message

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test Rich Message</subject>
    <body>This is some content followed by the Rich Message link @@web_link@@</body>
    <web>
        <type>text/html</type>
        <body>
            <![CDATA[
                <div id='content'>
                    <p>Hi <span id='first_name'></span></p>
                    <p>This is the body of my Rich Message</p>
                    <script type='text/javascript'>
                        document.getElementById('first_name').innerHTML = Whispir.data.profile.firstname;
                    </script>
                </div>
            ]]>
        </body>
    </web>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
   "to" : "$mobile",
   "subject" : "Test Rich Message",
   "body" : "This is some content followed by the Rich Message link @@web_link@@",
   "web" : {
      "type" : "text/html",
      "body" : "<div id='content'><p>Hi <span id='first_name'></span></p><p>This is the body of my Rich Message</p><script type='text/javascript'>document.getElementById('first_name').innerHTML = Whispir.data.profile.firstname;</script></div>"
   }
}
<!--For ease of reading, the above HTML looks like-->
<div id='content'>
    <p>Hi <span id='first_name'></span></p>
    <p>This is the body of my Rich Message</p>
    <script type='text/javascript'>
        var firstName = Whispir.data.profile.firstname;
        document.getElementById('first_name').innerHTML = firstName;
    </script>
</div>

Whispir’s Rich Messages provide you with the capability to seamlessly 'push’ HTML content to your audience.

This can be in the form of a simple web page, through to a mini web application with interactive widgets such as video, a data visualisation, or map.

For example;

The inclusion of the @@web_link@@ tag anywhere in the body of the SMS or Email will automatically generate a URL and embed any content specified in the web body of the same message.

Requirements to use Rich Messaging

Rich push is utilised when delivered to a mobile device. The receiving device requires the following features to be enabled to ensure the experience is optimised.

The target device:

Guidelines for authoring the Rich Message HTML

Whispir allows you to control the entire content to be delivered to the end users device. Therefore, it’s important that you build to a responsive design to display the content appropriately for every screen size.

HTML Resources

Any HTML resources (Images, videos and visual assets) must be hosted externally, and referenced in the HTML. This allows you to control and link to resources using your existing CDN assets.

Response rules

Response Rules allow you to define pre-canned responses to your message. Your stakeholders can review these responses and optional reply to your message by selecting one.

More information about Rich Messages and the Whispir object is included later in this documentation.

Push Messages

Push Messages

HTTP 1.1 POST https://api.<region>.whispir.com/workspaces/{:wid}/messages?apikey=[your_api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.message-v1+xml
Accept: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>contact-mri-value</to>
    <subject>Test Push Message</subject>
    <body>This is the body of my test Push message</body>
    <features>
        <notifications>enabled</notifications>
        <appId>{:appId}</appId>
    </features>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
    "to" : "contact-mri-value",
    "subject" : "Test Push Message",
    "body" : "This is the body of my test Push message",
    "features" : {
        "pushOptions" : {
            "notifications" : "enabled",
            "appId" : "{appId}"
        }
    }
}
Response: 202 Accepted
Location: https://api.<region>.whispir.com/workspaces/{:wid}/messages/{:mid}?apikey=[your_api_key]

Whispir allows to send Push notifications to any IOS, and Android based apps. Sending Push notifcation is done via the /messages endpoint in the REST api, and the recipient is usually a Whispir contact MRI.

Setting up the platform to do Push involves some 1 time steps, and some periodically repeated steps (updating push tokens). Please refer to the Apps endpoint to get a clear understanding of the related steps, and endpoints. Whispir does not support sending push to device tokens directly. Read more in the Contact Devices on how to register the device tokens under contacts.

The following fields are required:

  1. To - the Whispir Contact MRI value
  2. Subject - the first line or the badge header text in the Push Note
  3. Body - the remainder of the Push Content
  4. appId - the id given by Whispir upon your app registration at the \apps endpoint
High-Level Request Elements
to: String
Specifies the mri value of the contact whose devices needs to receive the push
subject: String
Specifies the first line or the badge header text in the Push Note
Body: String
Specifies the text that goes into the “alert”/“data” section of push structure
appId: String
Specifies the appId of the registered app in Whispir

Or if you have a template, which has the details already set (in the mobile channel), and the features too set, which states the appId and has the notifications set to enabled, you can do.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>contact-mri-value</to>
    <messageTemplateName>Name-Of-the-Template-Goes-Here</messageTemplateName>
</ns2:message> 

{
    "to" : "contact-mri-value",
    "messageTemplateName" : "Name-Of-the-Template-Goes-Here"
}

So what happens in the background ?

Notes

Web and Social Messaging

Web and Social Messaging

Social Media Request/Response Example

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test Web Message</subject>
    <web>
        <body>This is web body of my test message</body>
        <type>text/plain</type>
    </web>
    <social>
        <social id="social">
            <body>This is the content of social message for Twitter</body>
         </social>
        <social id="social_long">
            <body>This is the content of social message for Facebook</body>
            <type>text/plain</type>
        </social>
    </social>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "$mobile",
    "subject" : "Test Web Message",
    "web" : {
        "body" : "This is the body of the web content",
        "type" : "text/plain"
    },
    "social" : {
        "social" : [{
            "id" : "social",
            "body" : "This is the content of social message for Twitter"
        }, {
            "id" : "socialType",
            "body" : "text/plain"
        }, {
            "id" : "social_long",
            "body" : "This is the content of social message for Facebook"
        }]
    }
}

The Whispir API supports publishing to Web, RSS and Social Media through existing configurations set up in the Whispir Platform.

If your existing Whispir setup already allows you to publish to these destinations, you can simply specify the information in the message, and it will automatically be published as per your existing setup.

Web Publishing

The Web section is used to publish information to Whispir’s Contact Portal or Whispir Community, or to a pre-defined web destination e.g. your company intranet.

Whispir can automatically export this content as plain text or HTML and export it to a location for you to either iFrame into your webpage, or include via AJAX.

For more information on web publishing, please contact support@whispir.io.

Social Publishing

The Social section is used to publish information to Twitter or Facebook as per your Whispir implementation.

Whispir can automatically publish content to your pre-configured Twitter and Facebook pages based on the information you have provided us.

For more information about configuring Social Publishing, please contact support@whispir.io.

Schedule Delivery

Sending messages at a later date

ONCE

HTTP 1.1 POST http://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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <to>john.smith@test.com</to>
    <subject>Test scheduled e-mail message</subject>
    <email>
        <body>This is my scheduled content</body>
        <type>text/plain</type>
    </email>
    <messageType>SCHEDULED</messageType>
    <scheduleType>ONCE</scheduleType>
    <scheduleDate>14/02/2017 15:55</scheduleDate>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "john.smith@test.com",
    "subject" : "Test scheduled e-mail message",
    "email" : {
        "body" : "This is my scheduled content",
        "type" : "text/plain"
    },
    "messageType" : "SCHEDULED",
    "scheduleType" : "ONCE",
    "scheduleDate" : "14/02/2017 15:55"
}

Scheduling messages to be delivered later

Using the Whispir API, users can schedule messages to be sent later.

Users can configure the schedule of message delivery as part of the message sendout.

For example. the code will schedule a single message to be delivered at 3:55pm on the 14th February 2017.

Scheduling messages for repeated delivery

REPEAT

HTTP 1.1 POST http://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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <to>john.smith@test.com</to>
    <subject>Test scheduled e-mail message</subject>
    <email>
        <body>This is my scheduled content</body>
        <type>text/plain</type>
    </email>
    <messageType>SCHEDULED</messageType>
    <scheduleType>REPEAT</scheduleType>
    <scheduleDate>14/02/2017 15:55</scheduleDate>
    <repetitionCount>10</repetitionCount>
    <repeatDays>0</repeatDays>
    <repeatHrs>1</repeatHrs>
    <repeatMin>0</repeatMin>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "john.smith@test.com",
    "subject" : "Test scheduled e-mail message",
    "email" : {
        "body" : "This is my scheduled content",
        "type" : "text/plain"
    },
    "messageType" : "SCHEDULED",
    "scheduleType" : "REPEAT",
    "scheduleDate" : "14/02/2017 15:55",
    "repetitionCount" : "10",
    "repeatDays" : "0",
    "repeatHrs" : "1",
    "repeatMin" : "0"
}

A second method of scheduling messages is where users can schedule messages to be sent multiple times/repeatedly (e.g. every hour, every day or every 7 days).

Users can configure the repeat rate of the message delivery as part of the message sendout.

For example. the code will schedule a single message to be delivered at 3:55pm on the 14th February 2017, and repeated every hour for 10 times.

Time Zone

When a message is scheduled, it is scheduled as per the timezone setting of the user who initiated the message request. Each user in Whispir has a timezone set in their profile. So, messages are sent relative to the user’s timezone, not from the timezone from where the user is located now.

For ex:

This is very important and has to be understood as Whispir does not honor the timezone the recipient is located in. So ensure that communication is sent in appropriate/preferred time given by them.

Note: Changing the user timezone after the message is triggered DOES NOT change the original scheduled time.

Bulk Sending

Both of the schedule types are also allowed in bulk messaging. You can upload a resource and trigger a bulk message to be sent using that resource at a scheduled time.

However, at this point of time, Whispir does not allow each message row inside the resource file to be sent at different time. They should all be sent at once.

Message Variables

Message Variables

Demonstration of sending messages with variables (or tags).

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>John_Wick.1143139@Contact.whispir.sg</to>
    <subject>Test SMS Message with tags</subject>
    <body>Hi @@first_name@@.  This is your message.</body>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
   "to" : "John_Wick.1143139@Contact.whispir.sg",
   "subject" : "Test SMS Message with tags",
   "body" : "Hi @@first_name@@.  This is your message."
}

When sending messages using the Whispir API, users have the ability to automatically include recipient information as part of the message. This is facilitated using tags.

The following tags can be included in any SMS, Email or Voice message:

Recipient Message Tags
@@first_name@@ Recipients first name.
e.g. John
@@last_name@@ Recipients last name.
e.g. Smith
@@recipient_email@@ Recipients primary email address.
e.g. jsmith@email.com
@@recipient_sms@@ Recipients primary mobile phone number.
e.g. 61412345678
@@recipient_voice@@ Recipients primary phone number for voice calls.
e.g. 61412345678
@@pin@@ Whispir message retrieval service call back PIN (only populated when voice is used).
e.g. 1234
@@recipient_role@@ Resolves to the recipient’s 'Role’ field.
e.g. Manager
@@recipient_additionalrole@@ Resolves to the recipient’s 'Additional Role’ field.
e.g. Team Leader
@@team_name1@@ Resolves to the recipient’s 'Team Name’ field.
e.g. Red Team
@@messagelabel@@ Resolves to the label field of the sent message.
e.g. Incident #1234
@@messagecategories@@ Resolves to the list of categories used in the message, separated with commas.
e.g. Product Update

Each of these tags will resolve on send of the message to the individual recipient’s information. As Whispir needs to know about this information prior to sending the message, the tags will only work when sending messages to Contacts or Distribution Lists.

For more information about sending messages to Contacts or Distribution Lists, please consult the documentation under Messaging.

*Note: * Tags do not work in Rich Messages. The Whispir javascript object must be used instead to populate recipient specific fields.

Using auto-populated system variables in messages

Using auto-populated system variables in messages

Demonstration of sending messages with system variables (or tags).

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test SMS Message with tags</subject>
    <body>The date is @@dd@@ / @@mm@@ / @@yyyy@@.</body>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

{
   "to" : "$mobile",
   "subject" : "Test SMS Message with tags",
   "body" : "The date is @@dd@@ / @@mm@@ / @@yyyy@@."
}

When sending messages using the Whispir API, users have the ability to automatically include system generated information as part of the message. This is facilitated using system tags.

The following system tags can be included in any message:

System Tags
@@dd@@ Current day with leading zero.
e.g. 25
@@mm@@ Current month with leading zero.
e.g. 10
@@yy@@ Current year, short form.
e.g. 14
@@yyyy@@ Current year, long form.
e.g. 2014
@@day@@ Day in spoken form.
e.g. Wednesday
@@month@@ Month in spoken form.
e.g. June
@@hrs@@ Current hour with leading zero in 24hrs.
e.g. 16
@@min@@ Current minute with leading zero .
e.g. 37
@@date@@ Current date in format (yyyy-mm-dd)
e.g. 2014-09-02
@@time@@ Current time in 24hr format.
e.g. 14:37

Each of these system tags will resolve on send of the message to the system information. The system tags will only work when sending messages to any recipient.

Message Attributes

Message Attributes

Sending an invitation message

HTTP 1.1 POST http://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" : "john@api-example.com", 
   "subject" : "Reminder:", 
   "body" : "Your invitation to the Acme Event will expire on 13/06/2014.", 
   "email" : { 
      "type" : "text/plain", 
      "body" : "Your invitation to the Acme Event will expire on 13/06/2014." 
   }
}

Whispir’s API customers who have Message Attributes configured within the Whispir Platform have the ability to simplify their API message requests by using the Message Attributes directly from the API.

Using Message Attributes allows developers to focus on the data behind a message, rather than focusing on the presentation or messaging channels within the message.

This separation ensures that the marketing or communications teams within an organisation can focus on what they are best at, and the developers can ensure the system integrations are working as effectively as possible.

A message could contain some content, and a potential variable such as the expiry of the invitation:

Reminder: your invitation to the Acme Event will expire on 13/06/2014.

The API call to populate this without Message Attributes could look as shown in the code example-

Using Templates to add in attributes

Using Templates to add in attributes

HTTP 1.1 POST http://api.<region>.whispir.com/templates?apikey=<[your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.template-v1+json

{ 
   "messageTemplateName" : "Event Reminder", 
   "subject" : "Reminder:", 
   "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@.", 
   "email" : { 
      "type" : "text/plain", 
      "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@." 
   }
}

Response - Template Created

HTTP 1.1 201 Created
Location: http://api.<region>.whispir.com/templates/DACADB02209CC93C
{ 
   "id": "DACADB02209CC93C", 
   "messageTemplateName" : "Event Reminder", 
   "subject" : "Reminder:", 
   "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@.", 
   "email" : { 
      "type" : "text/plain", 
      "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@." 
   }
}

Using Message Attributes and Message Templates allows developers to cleanly separate these responsibilities. This is done by combining both the channels being selected for the message, and the data driving the message.

The same message could be saved into a Whispir Message Template (see code example).

Using this Message Template ID and now using the Message Attribute @@event_expiry@@, the updated is far simpler to implement and is more efficient.

Using Template (with attributes)

to send the Message

HTTP 1.1 POST http://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" : "john@api-example.com", 
   "messageTemplateId" : "DACADB02209CC93C", 
   "messageattributes" : {
      "attribute" : [{
         "name" : "event_expiry",     
         "value" : "13/06/2014"   
      }]
   } 
} 

Using Template (with more than 1 attribute)

to send the Message

HTTP 1.1 POST http://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" : "john@api-example.com", 
   "messageTemplateId" : "DACADB02209CC93C", 
   "messageattributes" : {
      "attribute" : [{
         "name" : "event_expiry",     
         "value" : "13/06/2014"   
      },{
         "name" : "event_expiry_time",     
         "value" : "23:59:59"   
      }]
   } 
} 

Note:

Dynamic and Bulk Messages

Dynamic Messages

Whispir’s API allows users to upload structured data, and process this line by line into outbound communications via SMS, Email, Voice, Web or Social Media.

|------------|------------|-------------|-------------|------------|
| First Name | Last Name  | Mobile      | Amount Owed | Date Due   |
|------------|------------|-------------|-------------|------------|
| Jono       | Johnson    | +6590091234 | S$1000      | 21/08/2015 |
| Steve      | Smith      | +6590091235 | S$1100      | 22/08/2015 |
|------------|------------|-------------|-------------|------------|
"Content-Type": "application/vnd.whispir.bulkmessage-v1+json"
"Accept": "application/vnd.whispir.bulkmessage-v1+json"

#ToDo
"Content-Type": "application/vnd.whispir.bulkmessage-v1+json"
"Accept": "application/vnd.whispir.bulkmessage-v1+json"

{
  "resource" : {
    "resourceId" : resource_id,  # From the resource you created
    "smsMappingField" : "mobile",
    "emailMappingField" : "",
    "voiceMappingField" : "",
    "options" : {
        "resolveRecipients" : ""
      }
  },
  "subject" : "Bulk Send Example,
  "body" : "Hi @@first_name@@. Your account is currently outstanding, with the amount @@amount_due@@ being due on @@due_date@@.  Please make every effort to pay your account on time.  If you would like more information, please contact us on 1800 000 000, regards.",
}

After processing, the first recipient would receive a message that looks as follows:

Hi Jono. Your account is currently outstanding, with the amount S$1000.00 being due on 21/08/2015.  Please make every effort to pay your account on time.  If you would like more information, please contact us on 1800 000 000, regards.

Whispir allows you send messages with dynamic content. This is very useful when you are sending SMS or emails in bulk and want to simply replace the placeholders or variables with values from a spreadsheet, data file or database table.

This can be achieved easily by uploading a file with the message content and the message recipient information. Whispir’s messaging engine takes this information and processes it in bulk sendout.

This process allows users to easily specify recipient information within the file, and this can be processed within the message content.

This file could be saved and uploaded to Whispir’s bulk messaging engine. As a result, Whispir would then propose the following variables to be available for use in the message:

@@first_name@@
@@last_name@@
@@mobile@@
@@amount_owed@@
@@date_due@@

The user then has the option to construct a message using this information, and Whispir will dynamically replace these variables at send time. For example your message content could be as follows:


Sending Dynamic Messages

The bulk message sending is an easy two-step process.

  1. Upload the resource file via API (CSV, JSON or XML)
  2. Create a new message using the resource file as source data.


Step 1: Upload the Resource file via API

HTTP 1.1 POST https://api.<region>.whispir.com/resources?apikey=[your_api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.resource-v1+xml
Accept: application/vnd.whispir.resource-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:resource xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <name>sample.json</name>
    <scope>private</scope>
    <mimeType>application/json</mimeType>
    <derefUri><!--base64 encoded JSON content --></derefUri>
</ns3:resource>
Content-Type: application/vnd.whispir.resource-v1+json
Accept: application/vnd.whispir.resource-v1+json

{
  "name" : "sample.json",
  "scope" : "private",
  "mimeType" : "application/json",
  "derefUri" : "//base64 encoded JSON content"
}

This will return a Resource ID that applications can use in the next step.

To upload a file to Whispir’s API, users will make an API call to the /resources endpoint.

Applications can use this endpoint to store the source files for dynamic messages. This endpoint can also be used to store any file based data (e.g. images, pdf documents, spreadsheets) for an unlimited amount of time.

Note: The types of files allowed are - CSV, JSON, XML, Images [JPEG, PNG], and WAV.

Information about the resources endpoint is documented in the Resources section of the documentation.


Step 2: Invoke the bulk message with reference to the resource ID and the desired content

Once the resource file has been uploaded and the location of the resource being returned, applications can use this to populate a dynamic message using the /messages endpoint.

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.bulkmessage-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <resource>
      <resourceId/>
      <smsMappingField/>
      <emailMappingField/>
      <voiceMappingField>
      <options>
        <resolveRecipients/>
      </options>
    </resource>
    <messageTemplateId>
    <subject></subject>
    <body></body>
    <email>
        <body></body>
        <footer></footer>
        <type></type>
    </email>
    <voice>
        <header></header>
        <body></body>
        <footer></footer>
        <other></other>
        <type></type>
    </voice>
    <web>
        <body></body>
        <type></type>
    </web>
    <callbackId/>
</ns2:message>
Content-Type: application/vnd.whispir.bulkmessage-v1+json

{
   "resource" : {
        "resourceId" : "",
        "smsMappingField" : "",
        "emailMappingField" : "",
        "voiceMappingField" : "",
        "options" : {
            "resolveRecipients" : ""
        }
    },
    "messageTemplateId" : "",
    "subject" : "",
    "body" : "",
    "email" : {
        "body" : "",
        "footer" : "",
        "type" : ""
    },
    "voice" : {
        "header" : "",
        "body" : "",
        "footer" : "",
        "other" : "",
        "type" : ""
    },
    "web" : {
        "body" : "",
        "type" : ""
    },
    "callbackId" : ""
}

Dynamic Messaging

Method Definition and Descriptions

Name Value
Service URL https://api..whispir.com/messages
https://api..whispir.com/workspaces/[id]/messages
Methods Supported GET, POST
Request MIME Type application/vnd.whispir.bulkmessage-v1+xml
application/vnd.whispir.bulkmessage-v1+json
/messages
GET: Provides a List of all the currently sent messages within the company or workspace (URIs)
POST: Creates and sends a new message/bulk message.
/messages/{id}
GET: Retrieves the representation of the requested message.
POST: NOT SUPPORTED

Note: The endpoint does not support PUT and DELETE in bulk messages. Similarly there is no POST for the /messages/{id}.

Request Components

The structure of the Bulk Message is used to define the resource that should be used in the sendout, while also giving the user the capability to override the message content in the event a message template is not desired.

Main Section
messageTemplateId The resource identifier of the Message Template that should be used for this request.
Sample Value: 4FBBC384BCE3DAABFE3
callbackId The id of the callback to be used for responses to this message.
Sample Value: SampleCallback

Note: callback IDs are configured by Administrators within the Whispir Platform.
Resource Section
resourceId The resource identifier returned from the POST to /resources.
Resource referred to must be a valid CSV file.
Sample Value: 384BCE34FBBCDAABFE3
smsMappingField The column name from within the CSV file that refers to the field on each row that should be used for SMS messages.
Sample Value: Mobile

Note: This field will default to ‘mobile’ if present in the file and this field is not populated.
emailMappingField The column name from within the CSV file that refers to the field on each row that should be used for Email messages.
Sample Value: Email

Note: This field will default to ‘email’ if present in the file and this field is not populated.
voiceMappingField The column name from within the CSV file that refers to the field on each row that should be used for Voice messages.
Sample Value: Mobile

Note: This field will default to ‘mobile’ if present in the file and this field is not populated.
options This specifies other options that are available within this bulk message.
  • resolveRecipients (true/false) - Whether recipients should be resolved to contacts in the Whispir Workspace. Default: true for less than 5000 recipients
Message Content Section – *Required when no template is used.*
Subject Defines the subject of the message. The subject also acts as the first line of the SMS message.
Sample Value: Mary had a little lamb.
Body The body of the SMS message being delivered.
Sample Value: And its fleece was white as snow. Everywhere that Mary went, the lamb was sure to check her in 4Square. Soon, Mary was the president of the town.
Email Section – *Required for email messages*
Body The body of the email message being delivered.
Sample Value: Jack and Jill went up the hill.
Footer The footer of the email message being delivered. Usually used as an area for a signature.
Sample Value: Regards, the well.
Type The type of the email content.
Sample Value: text/plain (default) / text/html.
Voice Section – *Required for voice messages*
Header The header of the voice content.
Sample Value: The text to speech content of the introduction message for the voice call.
Body The content of the voice message.
Sample Value: The text to speech content of the body message for the voice call.
Type The type parameter defines the other optional elements of the voice call.
Sample Value: ConfCall:ConfAccountNo:ConfPinNo:ConfModPinNo:Pin:
Web Section – *Required for web/rich push messages*
Body The body of the web message
Sample Value: The body content of the web message to be delivered.
Type The type of the web message
Sample Value: text/plain (default) / text/html.

Response Structure

If the /message call is successful, the following response will be received.

HTTP 1.1 202 Accepted
Location: https://api.<region>.whispir.com/messages/4FBBC384BCE3DAABFE3?apikey=<your_api_key>

Your request has been accepted for processing.

The Location value in the Header contains the messageId (for the sent message) as shown in the response above.

If the request was successful, the response contains the information for the calling application to retrieve information about the message.

If the request was not successful, the response will contain the information about why the request could not be processed. This will be as per the standard Whispir API response code rules.

In case of a dynamic message, the outcome of this message will be a complete message with placeholder variables @@ replaced with the supplied values.

For more information about retrieving the responses and status of the sent message, refer to message status below.

Recipient Information

Using the Whispir API, users can send message to either ad-hoc or predefined recipients.

The details below describe how these can be used in the <to> field for any type of message.

For ad-hoc recipients:

Any valid E-mail address

Any valid Mobile number for SMS or Voice calls (countrycode prefixed)

Any valid Landline number for Voice calls only (countrycode prefixed)

For pre-entered Whispir recipients:

Contacts can be used as a message recipient simply by specifying any valid Whispir Contact MRI

Users can be used as a message recipient simply by specifying any valid Whispir User MRI

Distribution Lists can be used as a message recipient simply by specifying any valid Whispir Distribution List MRI

Each of these can be found by using the Whispir API to search for the resource type and locate the MRI field in the response.

Retrieve a previously sent Message

HTTP 1.1 GET https://api.<region>.whispir.com/messages/069BF68E5E0FE99B?apikey=[your_api_key]
Authorization: Basic <YOUR AUTH HEADER>
x-api-key: your_api_key
Content-Type: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <to>$mobile</to>
    <subject>Test Message</subject>
    <body>This is the body of my test SMS message</body>
    <label/> 
    <voice/>
    <from></from>
    <direction>OUTGOING</direction>
    <responseCount>0</responseCount>
    <social/>
    <createdTime>2012-09-24T15:36:16+10:00</createdTime>

    ...

    <ns3:link method="GET" 
       rel="self" 
       uri="http://api.<region>.whispir.com/messages/069BF68E5E0FE99B?apikey=[your-api-key]"/>
</ns2:message> 
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "$mobile",
    "subject" : "Test Message",
    "body" : "This is the body of my test SMS message",
    "label" : "",
    "voice" : "",
    "web" : "",
    "from" : "",
    "direction" : "OUTGOING",
    "social" : "",
    "createdTime" : "1469414786000"
    "responseCount" : 0,

    ...

    "link": [
        {
          "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B?apikey=[your-api-key]",
          "rel": "self",
          "method": "GET"
        }
      ]
}

A call to GET /messages gives you the list of last 20 sent messages. You can use the Pagination to retrieve further messages.

If a specific message has to retrieved then, you must know the message ID of the message. This can be done by retrieving the list of messages using GET /messages (include workspace if needed) and then loop through them to get details of each and every individual message.

Note: GET /messages will only retrieve the messages sent by you. But if you want to retrieve all the messages sent in the workspace (sent by others aswell), then append &viewType=shared in the URL query.

Message Status

API Endpoint

The following calls describe how to access message status information from within your message resource

<!-- From the default workspace -->

https://api.<region>.whispir.com/messages/{:messageId}/messagestatus/?apikey=<your_api_key>
Accept: application/vnd.whispir.messagestatus-v1+xml
//From the default workspace

https://api.<region>.whispir.com/messages/{:messageId}/messagestatus/?apikey=<your_api_key>
Accept: application/vnd.whispir.messagestatus-v1+json
<!-- or from a defined workspace -->

https://api.<region>.whispir.com/workspaces/{:id}/messages/{:messageId}/messagestatus/?apikey=<your_api_key>
Accept: application/vnd.whispir.messagestatus-v1+xml
//or from a defined workspace

https://api.<region>.whispir.com/workspaces/{:id}/messages/{:messageId}/messagestatus/?apikey=<your_api_key>
Accept: application/vnd.whispir.messagestatus-v1+json

The following resource types are supported for messages status

- application/vnd.whispir.messagestatus-v1+xml
- application/vnd.whispir.messagestatus-v1+json

The following methods are supported for the message status endpoint

- GET

Whispir will automatically monitor the status of each message after it has been sent to each recipient.  Using the message status information, you are able to determine who received the message, what exact time they received it, on what message channel (SMS, Email, Voice, Web, Push Notification), whether they replied to the message, what time they replied, and on what messaging channel.

Each message progresses through various states, from Pending to Acknowledged.

Message Status Descriptions
Pending (PENDING): The message has not yet been processed by Whispir.  It is in a queue and will be processed shortly.
Sent (SENT): The message has been sent from Whispir to the recipient, however, there has been no acknowledgement from the recipient via read receipt that the message has arrived.
Received (DELIVRD): Email: Whispir has received acknowledgement via a read receipt that the message has arrived in the inbox.

SMS: Received status can mean one of two things for SMS.
  1. The message has been received by the network and is being processed for delivery to the handset.

    How long the message stays in this state is up to the telco.

  2. The message has been received by the handset and confirmed by the telco.
Acknowledged (READ): Whispir has received an intended response from the recipient, either by reply SMS, Email or Voice prompt
Undeliverable (FAILED): Whispir was not able to deliver the message to the intended recipient on the specified channel.  This may be due to incorrect information e.g. wrong phone number or email address, or due to poor network coverage.

Using the API, developers are able to access this status information at either a Summary or Detailed level.

The first thing a developer must do in order to retrieve the status of a sent message is retrieve the message using the API.

Retrieve a Message

Retrieve a message

Use the API to retrieve a sent Message

HTTP 1.1 GET https://api.<region>.whispir.com/messages?apikey=[your_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
 <to>$mobile</to>
 <subject>test subject</subject>
 <body>test body</body>
 <voice/>
 <from></from>
 <direction>OUTGOING</direction>
 <responseCount>0</responseCount>
 <social/>
 <createdTime>2012-09-24T15:36:16+10:00</createdTime>
 <ns3:link method="GET" 
   rel="self" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B?apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="summaryStatus" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="detailedStatus" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=detailed&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="summaryResponses" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="detailedResponses" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="summaryResponsesWithResponseRule" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=responserule&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="detailedResponsesWithResponseRule" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=responserule&apikey=498nadsasdff09fewdsafjaa90f"/>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to": "$mobile",
    "subject": "test subject",
    "body": "test body",
    "direction": "OUTGOING",
    "responseCount": "0",
    "createdTime": "1460070991",
    "link": [{
      "method": "GET",
      "rel": "self",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B?apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "summaryStatus",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "detailedStatus",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=detailed&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "summaryResponses",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "detailedResponses",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "summaryResponsesWithResponseRule",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=responserule&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "detailedResponsesWithResponseRule",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=responserule&apikey=498nadsasdff09fewdsafjaa90f"
    }]
}

The example request below returns the Message that the API user requested.  

GET /messages/069BF68E5E0FE99B?apikey=498nadsasdff09fewdsafjaa90f

Each of the URLs specified in the response can be accessed using the REL and appropriate METHOD to perform the specified functionality.

Rel Attribute Descriptions
self: Retrieves the current message.
summaryStatus: Returns the status information of the message as a messagestatus object, in a summary view.
detailedStatus: Returns the status information of the message as a messagestatus object, in a detailed view.
summaryResponses: Returns the response information of the message as a messageresponse object, in a summary view.
detailedResponses: Returns the response information of the message as a messageresponse object, in a detailed view.
summaryResponsesWithResponseRule: Returns the response information of the message as a messageresponse object, filtered by the Response Rule (if one was used) in a summary view.
detailedResponsesWithResponseRule: Returns the response information of the message as a messageresponse object, filtered by the Response Rule (if one was used) in a detailed view.

Retrieve Summary Status

Retrieve Summary Status

This sample of code will retrieve the Summary Status for a message

<ns3:link method="GET" 
   rel="summaryStatus" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f"/>
{
    "method": "GET",
    "rel": "summaryStatus",
    "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f"
}

Sample Summary Status Response

This sample of code will retrieve the Summary Status for a message

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
 <ns2:messageStatuses>
  <ns2:messageStatus>
    <ns2:link method="GET" 
             rel="self" 
             uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f"/>
    <categories>
      <status name="Sent">
        <percentageTotal>0.0%</percentageTotal>
        <recipientCount>0</recipientCount>
      </status>
      <status name="Pending">
        <percentageTotal>0.0%</percentageTotal>
        <recipientCount>0</recipientCount>
      </status>
      <status name="Received">
        <percentageTotal>0.0%</percentageTotal>
        <recipientCount>0</recipientCount>
      </status>
      <status name="Acknowledged">
        <percentageTotal>100.0%</percentageTotal>
        <recipientCount>2</recipientCount>
      </status>
      <status name="Undeliverable">
        <percentageTotal>0.0%</percentageTotal>
        <recipientCount>0</recipientCount>
      </status>
    </categories>
  </ns2:messageStatus>
 </ns2:messageStatuses>
</ns2:return>
{
  "messageStatuses" : [ {
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f",
      "rel" : "self",
      "method" : "GET"
    } ],
    "categories" : [ {
      "name" : "Sent",
      "recipientCount" : 0,
      "percentageTotal" : "0.0%"
    }, {
      "name" : "Pending",
      "recipientCount" : 0,
      "percentageTotal" : "0.0%"
    }, {
      "name" : "Received",
      "recipientCount" : 0,
      "percentageTotal" : "0.0%"
    }, {
      "name" : "Acknowledged",
      "recipientCount" : 2,
      "percentageTotal" : "100.0%"
    }, {
      "name" : "Undeliverable",
      "recipientCount" : 0,
      "percentageTotal" : "0.0%"
    } ]
  } ],
  "link" : [ ]
}

Using the links provided in the message response, the user can simply make a new API request to retrieve the summaryStatus URL. 

In the example above, the summaryStatus URL is:

So the request would look as follows:

GET https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f

As this is a GET request we don’t have to provide any message body.

This response states that of the 2 people that were sent the message, both of them Acknowledged it by sending a response. 

Your application can use this information to easily determine the numbers of recipients in each state and show a small graph.

Retrieve Detailed Status

Retrieve Detailed Status

This snippet will retrieve the detailed status for a message.

<ns3:link method="GET" 
   rel="detailedStatus" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=detailed&apikey=498nadsasdff09fewdsafjaa90f"/>
{
    "method": "GET",
    "rel": "detailedStatus",
    "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=detailed&apikey=498nadsasdff09fewdsafjaa90f"
}

Sample Detailed Status Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
  <status>1 to 2 of 2</status>
  <ns2:messageStatuses>
    <ns2:messageStatus>
      <ns2:link method="GET" 
            rel="self" 
                uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?apikey=498nadsasdff09fewdsafjaa90f&view=detailed"/>
      <status type="email">
        <destination></destination>
        <status></status>
      </status>
      <status type="sms">
        <acknowlegedTimestamp>2012-09-28T08:47:50+10:00</acknowlegedTimestamp>
        <destination>$mobile</destination>
        <receivedTimestamp>2012-09-28T08:47:20+10:00</receivedTimestamp>
        <sentTimestamp>2012-09-28T08:47:17+10:00</sentTimestamp>
        <status>READ</status>
      </status>
      <status type="voice">
        <destination></destination>
        <status></status>
      </status>
      <info> Out bound SMS text message sent OK. </info>
      <name>John Smith</name>
    </ns2:messageStatus>
    <ns2:messageStatus>
      <ns2:link method="GET" 
            rel="self" 
                uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?apikey=498nadsasdff09fewdsafjaa90f&view=detailed"/>
      <status type="email">
        <destination></destination>
        <status></status>
      </status>
      <status type="sms">
        <acknowlegedTimestamp>2012-09-28T08:47:49+10:00</acknowlegedTimestamp>
        <destination>$mobile</destination>
        <receivedTimestamp>2012-09-28T08:47:20+10:00</receivedTimestamp>
        <sentTimestamp>2012-09-28T08:47:17+10:00</sentTimestamp>
        <status>READ</status>
      </status>
      <status type="voice">
        <destination></destination>
        <status></status>
      </status>
      <info> Out bound SMS text message sent OK. </info>
      <name>Fred Smith</name>
    </ns2:messageStatus>
  </ns2:messageStatuses>
</ns2:return>
{
  "messageStatuses" : [ {
    "name" : "John Smith",
    "info" : "Out bound SMS text message sent OK.",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?apikey=498nadsasdff09fewdsafjaa90f&view=detailed",
      "rel" : "self",
      "method" : "GET"
    } ],
    "status" : [ {
      "type" : "email",
      "status" : "",
      "destination" : ""
    }, {
      "type" : "sms",
      "status" : "READ",
      "destination" : "$mobile",
      "sentTimestamp" : "1460070991",
      "receivedTimestamp" : "1460070991",
      "acknowlegedTimestamp" : "1460070991"
    }, {
      "type" : "voice",
      "status" : "",
      "destination" : ""
    },{
    "name" : "Fred Smith",
    "info" : "Out bound SMS text message sent OK.",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?apikey=498nadsasdff09fewdsafjaa90f&view=detailed",
      "rel" : "self",
      "method" : "GET"
    } ],
    "status" : [ {
      "type" : "email",
      "status" : "",
      "destination" : ""
    }, {
      "type" : "sms",
      "status" : "READ",
      "destination" : "$mobile",
      "sentTimestamp" : "1460070991",
      "receivedTimestamp" : "1460070991",
      "acknowlegedTimestamp" : "1460070991"
    }, {
      "type" : "voice",
      "status" : "",
      "destination" : ""
    } ],
  "status" : "1 to 2 of 2",
  "link" : [ ]
}

Similar to the summaryStatus, using the links provided in the message response, the user can simply make a new API request to retrieve the detailedStatus URL. 

GET https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=detailed&apikey=

As this is a GET request we don’t have to provide any message body.

The user can easily use this information to receive a far more detailed status breakdown of (for each recipient):

Once you have processed the status information, the next likely piece of information you will be looking to find is the content of the responses (if any). The section on Message Responses describes how to retrieve this information.

Message Responses

API Endpoint

  • generic
https://api.<region>.whispir.com/messages/{:messageId}/messageresponses/?apikey=<your_api_key>
Accept: application/vnd.whispir.messageresponse-v1+xml
https://api.<region>.whispir.com/messages/{:messageId}/messageresponses/?apikey=<your_api_key>
Accept: application/vnd.whispir.messageresponse-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/messages/{:messageId}/messageresponses/?apikey=<your_api_key>
Accept: application/vnd.whispir.messageresponse-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/messages/{:messageId}/messageresponses/?apikey=<your_api_key>
Accept: application/vnd.whispir.messageresponse-v1+json
> Resource type

- application/vnd.whispir.messageresponse-v1+xml
- application/vnd.whispir.messageresponse-v1+json


> Methods supported

- GET

Recipients of Whispir Messages have the ability to respond directly to the message via the channels that they received the message on. 

If they received the message via SMS, they can respond directly to the SMS message, and this will be visible through the Whispir.io API.

The sections below describe the process to retrieve the responses to any messages that you have sent via the Whispir.io API.

Retrieve a Message

Retrieve a message

Use the API to retrieve a sent Message

HTTP 1.1 GET https://api.<region>.whispir.com/messages?apikey=[your_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
 <to>$mobile</to>
 <subject>test subject</subject>
 <body>test body</body>
 <voice/>
 <from></from>
 <direction>OUTGOING</direction>
 <responseCount>0</responseCount>
 <social/>
 <createdTime>2012-09-24T15:36:16+10:00</createdTime>
 <ns3:link method="GET" 
   rel="self" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B?apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="summaryStatus" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="detailedStatus" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=detailed&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="summaryResponses" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="detailedResponses" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="summaryResponsesWithResponseRule" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=responserule&apikey=498nadsasdff09fewdsafjaa90f"/>
 <ns3:link method="GET" 
   rel="detailedResponsesWithResponseRule" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=responserule&apikey=498nadsasdff09fewdsafjaa90f"/>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to": "$mobile",
    "subject": "test subject",
    "body": "test body",
    "direction": "OUTGOING",
    "responseCount": "0",
    "createdTime": "1460070991",
    "link": [{
      "method": "GET",
      "rel": "self",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B?apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "summaryStatus",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "detailedStatus",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=detailed&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "summaryResponses",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "detailedResponses",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "summaryResponsesWithResponseRule",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=responserule&apikey=498nadsasdff09fewdsafjaa90f"
    },{
      "method": "GET",
      "rel": "detailedResponsesWithResponseRule",
      "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=responserule&apikey=498nadsasdff09fewdsafjaa90f"
    }]
}

The example request below returns the Message that the API user requested.  

GET /messages/069BF68E5E0FE99B?apikey=498nadsasdff09fewdsafjaa90f

Each of the URLs specified in the response can be accessed using the REL and appropriate METHOD to perform the specified functionality.

Rel Attribute Descriptions
self: Retrieves the current message.
summaryStatus: Returns the status information of the message as a messagestatus object, in a summary view.
detailedStatus: Returns the status information of the message as a messagestatus object, in a detailed view.
summaryResponses: Returns the response information of the message as a messageresponse object, in a summary view.
detailedResponses: Returns the response information of the message as a messageresponse object, in a detailed view.
summaryResponsesWithResponseRule: Returns the response information of the message as a messageresponse object, filtered by the Response Rule (if one was used) in a summary view.
detailedResponsesWithResponseRule: Returns the response information of the message as a messageresponse object, filtered by the Response Rule (if one was used) in a detailed view.

Summary Responses

Summary of Responses

This snippet of code will allow users to retrieve the summary of responses to a message.

<ns3:link method="GET" 
   rel="summaryResponses" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=498nadsasdff09fewdsafjaa90f"/>
{
    "method": "GET",
    "rel": "summaryResponses",
    "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=498nadsasdff09fewdsafjaa90f"
}

Sample Summary Responses Response

This response contains the summary of responses to the message

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <ns2:link method="GET" 
              rel="self" 
              uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=498nadsasdff09fewdsafjaa90f"/>
    <ns2:messageresponses>
        <ns2:response type="noresponse">
            <percentageTotal>50%</percentageTotal>
            <responseCount>1</responseCount>
        </ns2:response>
        <ns2:response type="notmatched">
            <percentageTotal>50%</percentageTotal>
            <responseCount>1</responseCount>
        </ns2:response>
    </ns2:messageresponses>
</ns2:return>
{
  "messageresponses" : [ {
    "percentageTotal" : "50%",
    "responseCount" : "1",
    "link" : [ ],
    "type" : "noresponse"
  },{
    "percentageTotal" : "50%",
    "responseCount" : "1",
    "link" : [ ],
    "type" : "notmatched"
  } ],
  "link" : [ {
    "uri" : "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=498nadsasdff09fewdsafjaa90f",
    "rel" : "self",
    "method" : "GET"
  } ]
}

Using the links provided in the message response, the user can simply make a new API request to retrieve the summaryStatus URL. 

The request for this information would look as follows:

GET https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=498nadsasdff09fewdsafjaa90f

This request is asking for a couple of things:

  1. The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
  2. The View parameter is specifying that the message responses should be shown in a summary view
  3. The Filter parameter is specifying that the filter should not use a response rule, it should show the default filter

As this is a GET request we don’t have to provide any message body.

This response states that of the 2 people that were sent the message, both of them Acknowledged it by sending a response. 

Your application can use this information to easily determine the numbers of recipients in each state and show a small graph.

Detailed Responses

Detailed Responses

This snippet allows the user to retrieve the detailed response report for a message

<ns3:link method="GET" 
   rel="detailedResponses" 
   uri="https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=498nadsasdff09fewdsafjaa90f"/>
{
    "method": "GET",
    "rel": "detailedResponses",
    "uri": "https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=498nadsasdff09fewdsafjaa90f"
}

Sample Detailed Responses Response

This is the detailed response report for a message

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 2 of 2</status>
    <ns2:messageresponses>
        <ns2:response>
            <from>
                <email>jsmith@test.com</email>                
                <mobile>$mobile</mobile> 
                <mri>John_Smith.484215.Critical_Incident_Management@Contact.whispir.com</mri>
                <name>John Smith</name>
                <voice>$mobile</voice> 
            </from>
            <responseCategory>noresponse</responseCategory>
            <responseMessage channel="N/A">
                <acknowledged>N/A</acknowledged>
                <content>N/A</content>
            </responseMessage>
        </ns2:response>
        <ns2:response>
            <from>
                <email>fsmith@test.com</email>
                <mobile>$mobile</mobile>  
                <mri>Fred_Smith.341550.Critical_Incident_Management@Contact.whispir.com</mri>
                <name>Fred Smith</name>
                <voice>$mobile</voice> 
            </from>
            <responseCategory>notmatched</responseCategory>
            <responseMessage channel="SMS">
                <acknowledged>28/09/12 08:48</acknowledged>
                <content>OK, got it. Thanks.</content>
            </responseMessage>
        </ns2:response>
    </ns2:messageresponses>
</ns2:return>
{
  "status" : "1 to 2 of 2    ",
  "messageresponses" : [ {
    "from" : {
      "name" : "John Smith",
      "mri" : "John_Smith.484215.Critical_Incident_Management@Contact.whispir.com",
      "mobile" : "$mobile",
      "email" : "jsmith@test.com",
      "voice" : "$mobile"
    },
    "responseCategory" : "noresponse",
    "responseMessage" : {
      "content" : "N/A",
      "acknowledged" : "N/A",
      "channel" : "N/A"
    }
  },{
    "from" : {
      "name" : "Fred Smith",
      "mri" : "Fred_Smith.341550.Critical_Incident_Management@Contact.whispir.com",
      "mobile" : "$mobile",
      "email" : "fsmith@test.com",
      "voice" : "$mobile"
    },
    "responseCategory" : "notmatched",
    "responseMessage" : {
      "content" : "OK, got it. Thanks.",
      "acknowledged" : "28/09/12 08:48",
      "channel" : "SMS"
    }
  } ],
  "link" : [ ]
}

This shows the application client that there were two intended recipients of this message.

One of the recipients is in the noresponse category, meaning they have not provided a response.  The other recipient is in the notmatched category, meaning the response did not match any search criteria.

Using the links provided in the message response, the user can simply make a new API request to retrieve the detailedResponses URL. 

The resulting request would look as follows:

GET https://api.<region>.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=498nadsasdff09fewdsafjaa90f

This request is asking for a couple of things:

  1. The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
  2. The View parameter is specifying that the message responses should be shown in a detailed view
  3. The Filter parameter is specifying that the filter should not use a response rule, it should show the default filter

As this is a GET request we don’t have to provide any message body.

Note: Searching responses will be described further on in this documentation.

Templates

API Endpoint

  • generic
https://api.<region>.whispir.com/templates/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.template-v1+xml
https://api.<region>.whispir.com/templates/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.template-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/templates/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.template-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/templates/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.template-v1+json
> Resource type

- application/vnd.whispir.template-v1+xml
- application/vnd.whispir.template-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

Using the Whispir.io API, messages can be stored as Message Templates that can be easily referenced within your API calls.

The purpose of using a Message Template rather than including your content directly into your messages API call is to ensure a separation of message content/design and application code.

If you are including the content and design of messages within your application code, in the event these need to change, this is often a task for a developer, resulting in potentially lengthy change request cycles.

The simple inclusion of a Message Template can alleviate this completely, allowing the designers to control the look and feel of the message, while the developer can control when it is triggered.

Creating Templates

Creating Templates

The following API calls allow users to manage Templates using the Whispir API.

HTTP 1.1 POST https://api.<region>.whispir.com/templates?apikey=[your_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.template-v1+xml

<?xml version="1.0" encoding="UTF-8"?>
<ns3:template xmlns:ns3="http://schemas.api.whispir.com" 
              xmlns:ns2="http://schemas.api.whispir.com/dap">
  <messageTemplateName>Sample SMS Template</messageTemplateName>
  <messageTemplateDescription>
    Template to provide an example on whispir.io
  </messageTemplateDescription>
  <subject>Test SMS Message</subject>
  <body>This is the body of my test SMS message</body>
  <email></email>
  <voice></voice>
  <web></web>
</ns3:template>
Content-Type: application/vnd.whispir.template-v1+json

{ 
   "messageTemplateName": "Sample SMS Template", 
   "messageTemplateDescription": "Template to provide an example on whispir.io",
   "subject" : "Test SMS Message",
   "body" : "This is the body of my test SMS message",
   "email" : {},
   "voice" : {},
   "web" : {}
}

The sample code above will create a simple SMS only message template within the default workspace.

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

To create a new message template, you can use the /templates endpoint.

The following fields are required:

  1. messageTemplateName - the name of the template to be stored
  2. subject - the first line or identifier of the SMS
  3. body - At least one of the Body fields must be populated (SMS, Email, Voice or Web).
  4. email - The email content for the message. If no email is required, an empty object must be presented.
  5. voice - The voice content for the message. If no voice call is required, an empty object must be presented.
  6. web - The web content for the message. If no web content is required, an empty object must be presented.
High-Level Request Elements
messageTemplateName: String
Specifies the name of the message template to be used within message requests.
messageTemplateDescription: String
Specifies the description of the message template for others to understand it’s purpose.
responseTemplateId: String
Specifies the ID of the Response Rule that should be associated with this Message Template.

Response Rules are further described later in this documentation.
subject: String
Specifies the first line of the SMS message or Voice call, and the subject of the Email message.
body: String
Specifies the content of the SMS message.
email: Object
Email object described below. Used for sending email messages.
voice: Object
Voice object described below. Used for sending voice calls to mobile phones and landlines.
web: Object
Web object described below. Used for web publishing and Rich Messages.
social: Object
Social object described below. Used for publishing content to social media (Twitter, Facebook, LinkedIn).
type: String
Allows the user to modify the message behaviour for replies and DLRs (delivery receipts) e.g.
  • defaultNoReply - Used to reject any replies to this message.
  • noDlr - Used to specify that DLRs should not be enabled for this message.
features: Object
Allows the user to modify the push notifications properties if these are configured in the company.

pushOptions:
  • notifications - enabled/disabled
  • escalationMins - # mins to await a push notifications response

Note: All of the options above are the same as provided in the /messages endpoint here

Retrieving Templates

Retrieving Templates

The following API Methods allow you to access templates via the API

HTTP 1.1 GET https://api.<region>.whispir.com/templates?apikey=[your_api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.template-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 4 of 4</status>
    <ns2:messagetemplates>
        <ns2:template>
            <ns2:link uri="https://api.<region>.whispir.com/templates/F0547F6F2E4839F8?apikey=[your_api_key]" rel="self" method="GET"/>
            <id>F0547F6F2E4839F8</id>
            <messageTemplateDescription>
            </messageTemplateDescription>
            <messageTemplateName>
              Appointment Reminder
            </messageTemplateName>
        </ns2:template>
        <ns2:template>
            <ns2:link uri="https://api.<region>.whispir.com/templates/DDE10AC13FB0E457?apikey=[your_api_key]" rel="self" method="GET"/>
            <id>DDE10AC13FB0E457</id>
            <messageTemplateDescription>
            </messageTemplateDescription>
            <messageTemplateName>
              Customer Survey
            </messageTemplateName>
        </ns2:template>
        <ns2:template>
            <ns2:link uri="https://api.<region>.whispir.com/templates/900972D1C916FE84?apikey=[your_api_key]" rel="self" method="GET"/>
            <id>900972D1C916FE84</id>
            <messageTemplateDescription>
            </messageTemplateDescription>
            <messageTemplateName>
              Service announcement
            </messageTemplateName>
        </ns2:template>
        <ns2:template>
            <ns2:link uri="https://api.<region>.whispir.com/templates/9CB9BE20B885542D?apikey=[your_api_key]" rel="self" method="GET"/>
            <id>9CB9BE20B885542D</id>
            <messageTemplateDescription>
            </messageTemplateDescription>
            <messageTemplateName>
              Shift Opportunity
            </messageTemplateName>
        </ns2:template>
    </ns2:messagetemplates>
</ns2:return>
Accept: application/vnd.whispir.template-v1+json

{
  "status" : "1 to 4 of 4    ",
  "messagetemplates" : [ {
    "messageTemplateName" : "Appointment Reminder",
    "messageTemplateDescription" : "",
    "id" : "F0547F6F2E4839F8",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/templates/F0547F6F2E4839F8?apikey=[your_api_key]",
      "rel" : "self",
      "method" : "GET"
    } ]
  }, {
    "messageTemplateName" : "Customer Survey",
    "messageTemplateDescription" : "",
    "id" : "DDE10AC13FB0E457",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/templates/DDE10AC13FB0E457?apikey=[your_api_key]",
      "rel" : "self",
      "method" : "GET"
    } ]
  }, {
    "messageTemplateName" : "Service announcement",
    "messageTemplateDescription" : "",
    "id" : "900972D1C916FE84",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/templates/900972D1C916FE84?apikey=[your_api_key]",
      "rel" : "self",
      "method" : "GET"
    } ]
  }, {
    "messageTemplateName" : "Shift Opportunity",
    "messageTemplateDescription" : "",
    "id" : "9CB9BE20B885542D",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/templates/9CB9BE20B885542D?apikey=[your_api_key]",
      "rel" : "self",
      "method" : "GET"
    } ]
  } ],
  "link" : [ ]
}

To retrieve a list of templates from the Whispir.io API you can execute an HTTP GET using the /templates endpoint.

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

An array of Message Templates will be returned to you in the HTTP response body.

Each of these templates will provide the following information:

Response Elements
messageTemplateName: String
Specifies the name of the message template to be used within message requests.
messageTemplateDescription: String
Specifies the description of the message template for others to understand it’s purpose.
id: String
Specifies the ID of the template that can be used for message sending.
link: Array
Provides a list of URLs that can be used to manipulate or access the message template.
  • uri - the link to access the message template
  • rel - the descriptor for what the link will do
  • method - the HTTP method to use with this particular link

Updating Templates

Updating Templates

The following API calls allow users to update Template content using the Whispir API.

HTTP 1.1 PUT https://api.<region>.whispir.com/templates/C37DCBAEFF73FEDA45?apikey=[your_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.template-v1+xml
Accept: application/vnd.whispir.template-v1+xml

<?xml version="1.0" encoding="UTF-8"?>
<ns3:template xmlns:ns3="http://schemas.api.whispir.com" 
              xmlns:ns2="http://schemas.api.whispir.com/dap">
  <messageTemplateName>Sample SMS Template</messageTemplateName>
  <messageTemplateDescription>
    Template to provide an example on whispir.io
  </messageTemplateDescription>
  <subject>Test SMS Message</subject>
  <body>This is the body of my test SMS message</body>
  <email>
    <type>text/plain</type>
    <body>
      This is the content of my plain text email in the template
    </body>
  </email>
  <voice>
    <!-- Don't put line breaks in this section -->
    <type>
        ConfCall:,
        ConfAccountNo:,
        ConfPinNo:,
        ConfModPinNo:,
        Pin:
    </type>
    <header>This is the intro of my voice call</header>
    <body>This is the content of my voice call</body>
  </voice>
  <web> 
    <body>This is web body of my test message</body> 
    <type>text/plain</type> 
  </web> 
  <social>
    <social id="social">
        <body>Twitter Content.</body>
    </social>
    <social id="social_long">
        <body>Facebook Content.</body>
        <type>text/plain</type>
    </social>
  </social>
  <type>defaultNoReply</type>
  <features>
    <pushOptions>
      <notifications>enabled</notifications>
      <escalationMins>3</escalationMins>
    </pushOptions>
  </features>
</ns3:template>
Content-Type: application/vnd.whispir.template-v1+json
Accept: application/vnd.whispir.template-v1+json

{ 
   "messageTemplateName": "Sample SMS Template", 
   "messageTemplateDescription": "Template to provide an example on whispir.io",
   "responseTemplateId": "Template to provide an example on whispir.io",
   "subject": "Test SMS Message",
   "body" : "This is the body of my test SMS message",
    "email" : {
        "body" : "This is the body of my test Email message",
        "footer" : "This is the footer of my message 
                    (generally where a signature would go)",
        "type" : "text/plain"
    },
    "voice" : {
        "header" : "This is the introduction, 
                    read out prior to any key press",
        "body" : "This is the body of the voice call, 
                  read out after the key press",
        "type" : "ConfCall:,
                  ConfAccountNo:,
                  ConfPinNo:,
                  ConfModPinNo:,
                  Pin:"
    },
    "web" : {
        "body" : "This is the content of my web publishing 
                 or Rich Push Message",
        "type" : "text/plain"
    },
    "social" : {
        "social" : {
            "id" : "social",
            "body" : "Twitter Content."
        },
        "social" : {
            "id" : "social_long",
            "body" : "Facebook Content.",
            "type" : "text/plain"
        }
    },
    "type" : "defaultNoReply",
    "features" : {
        "pushOptions" : {
            "notifications" : "enabled",
            "escalationMins" : "3"
        }
    }
}

The sample code above will update the message template specified by ID: C37DCBAEFF73FEDA45 within the default workspace.

The expected response to this call is an HTTP 204 - No Content.

To update existing message templates, you can use a PUT request the /templates endpoint.

The following fields are required:

  1. messageTemplateName - the name of the template to be stored
  2. subject - the first line or identifier of the SMS
  3. body - At least one of the Body fields must be populated (SMS, Email, Voice or Web).

Note: Currently users cannot update templates with the same name as a template that already exists in Whispir. Users can overcome this by saving the updated template with a new name, then either changing this back in a subsequent save, or retaining the updated name.

High-Level Request Elements
messageTemplateName: String
Specifies the name of the message template to be used within message requests.
messageTemplateDescription: String
Specifies the description of the message template for others to understand it’s purpose.
responseTemplateId: String
Specifies the ID of the Response Rule that should be associated with this Message Template.

Response Rules are further described later in this documentation.
subject: String
Specifies the first line of the SMS message or Voice call, and the subject of the Email message.
body: String
Specifies the content of the SMS message.
email: Object
Email object described below. Used for sending email messages.
voice: Object
Voice object described below. Used for sending voice calls to mobile phones and landlines.
web: Object
Web object described below. Used for web publishing and Rich Messages.
social: Object
Social object described below. Used for publishing content to social media (Twitter, Facebook, LinkedIn).
type: String
Allows the user to modify the message behaviour for replies and DLRs (delivery receipts) e.g.
  • defaultNoReply - Used to reject any replies to this message.
  • noDlr - Used to specify that DLRs should not be enabled for this message.
features: Object
Allows the user to modify the push notifications properties if these are configured in the company.

pushOptions:
  • notifications - enabled/disabled
  • escalationMins - # mins to await a push notifications response

Note: All of the options above are the same as provided in the /messages endpoint here

Deleting Template

> Deleting a template

> > Exact URI of the template has to be provided. 

HTTP 1.1 DELETE https://api.<region>.whispir.com/templates/C37DCBAEFF73FEDA45?apikey=[your_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
> Response

> > 204 No Content

Deleting a template is done via the DELETE method. The exact link url of the specific template has to be used as the end point. To get it, one can perform a GET /templates which returns the list of all templates and their link url. If the template is within a workspace, ensure that the workspace is included in the URI.

Note: When a template is DELETED, all the associated Scenarios, events, and references of template use in other endpoints will fail. So, ensure that the template is not used anywhere before it is deleted. Whispir will not do that check before it deletes the template.

Using Templates

Using Templates

The following methods allow you to use the templates that you’ve created in your Whispir Messages

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>john.smith@test.com</to>
    <messageTemplateId>BACEB8D46BEF5315</messageTemplateId>
</ns2:message> 
Content-Type: application/vnd.whispir.message-v1+json

{ 
   "to" : "$mobile",
   "messageTemplateId" : "BACEB8D46BEF5315"
}

Alternatively, you can enter the Message Template Name in place of the Message Template ID:

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <messageTemplateName>Sample SMS Template</messageTemplateName>
</ns2:message> 
Content-Type: application/vnd.whispir.message-v1+json

{ 
   "to" : "$mobile",
   "messageTemplateName" : "Sample SMS Template"
}

Whispir.io API messages can simply specify the Message Template ID in the messages request, instead of specifying the entire content payload.

The message template can then easily be changed (using either another API request or by logging in to the Whispir Platform) and the part of the application sending the messages does not need to be altered.

Overriding Templates

Overriding Templates

You can override content in the template by supplying it inline with the message request

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <messageTemplateName>Sample SMS Template</messageTemplateName>
    <subject>This will override the template Subject</subject>
    <body>This will override the template SMS Body</body>
</ns2:message> 
Content-Type: application/vnd.whispir.message-v1+json

{ 
   "to" : "$mobile",
   "messageTemplateName" : "Sample SMS Template",
   "subject" : "This will override the template Subject",
   "body" : "This will override the template SMS Body"
}

Users can easily override the content of the Message Template by supplying the content inline with the request to the /messages endpoint.

Any information provided in the message request will take precidence over the templated content.

All of the features that are specified on the template (for example, any message aliasing) will still be respected when the message is delivered.

Response Rules

API Endpoint

  • generic
https://api.<region>.whispir.com/responserules/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.responserule-v1+xml
https://api.<region>.whispir.com/responserules/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.responserule-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/responserules/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.responserule-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/responserules/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.responserule-v1+json
> Resource type

- application/vnd.whispir.responserule-v1+xml
- application/vnd.whispir.responserule-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

Using Response Rules in combination with Message Templates allows users to automatically group responses to messages into different response groups for reporting purposes.

Response Rules are useful when users are sending messages with known responses, e.g. Ratings (1-5), Yes/No, or Accept/Decline.

Once the Response Rule has been defined, it can be associated with a Message Template and any responses to messages sent using the template will be automatically categorised.

Note: Response Rules are sometimes called Response Templates. These names can be used interchangably.

Creating Response Rules

Creating Response Rules

The following API calls allow users to create new Response Rules using the Whispir API.

HTTP 1.1 POST https://api.<region>.whispir.com/responserules?apikey=[your_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.responserule-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:responserule xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <name>Response Rule 1</name>
    <description></description> 
    <responseTemplatePatterns>
        <responseTemplatePattern>
            <name>Yes Rule</name>
            <textPrompt>YES</textPrompt>
            <voicePrompt>1</voicePrompt>
            <spokenVoicePrompt>to select YES</spokenVoicePrompt>
            <pattern>startswith</pattern>
            <colour>#00947d</colour>
        </responseTemplatePattern>
    </responseTemplatePatterns>
</ns3:responserule>
Content-Type: application/vnd.whispir.responserule-v1+json

{
  "name" : "Response Rule 1",
  "description" : "",
  "responseTemplatePatterns" : {
    "responseTemplatePattern" : [ {
      "name" : "Yes Rule",
      "textPrompt" : "YES",
      "voicePrompt" : "1",
      "spokenVoicePrompt" : "to select YES",
      "pattern" : "startswith",
      "colour" : "#00947d"
    } ]
  }
}

The sample code above will create a simple Response Rule with a single rule within the default workspace.

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

To create a new Response Rule, you can use the /responserules endpoint.

The following fields can be utilised within the request:

High-Level Request Elements
name: String
Specifies the name of the Response Rule.
description: String
Specifies the description of the response rule for others to understand it’s purpose.
responseTemplatePatterns: Object
This object contains the responseTemplatePattern array which contains each of the response rule elements.

Response Template Patterns

Each Response Rule has a series of Patterns that allow the creator to specify what textual content should be matched in the response SMS or Email, and a number that should be entered when IVR (Voice) is being used.

The patterns specify the following information:

Response Template Pattern Elements
name: String
The name of the Response Category.
pattern: String
Specifies the mechanism for matching the textPrompt.

The following options are available:
  • startsWith
  • contains
  • exactmatch
textPrompt: String
Specifies the textual string that should be matched using the pattern (specified above) within the Email, SMS or Web response.
voicePrompt: String
The number (from 0-9, * or #) that the recipient of the voice call should enter to select this response category.
spokenVoicePrompt: String
The TTS (text-to-speech) that is dynamically read out when describing to the user what this response category is.
colour: String
The hexidecimal colour code that is used in the Message Response Report to show this category being used.

Each Response Rule can specify as many Response Template Patterns as required.

Each of the Patterns specified will also dynamically create buttons within any Rich Message that is associated with the Response Rule.

This provides an out of the box capability to quickly gather feedback from the field using a Rich User interface, and leveraging SMS as the delivery mechanism.

For more information about using Rich Messages, click here.

Using Response Rules

After creating a Response Rule, you must create a new Message Template (or update an existing one) and associate the Response Rule ID.

Note: The Response Rule ID will be returned in the Location header after a successful creation.

This association of Response Rule to Message Template is performed using the responseTemplateId field within the Message Template.

For more information on Creating Message Templates, click here.

Matched Rule

Matched Rule

Sending a message using template and callback

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <messageTemplateName>ReplyYesNoTemplate</messageTemplateName>
    <callbackId>myCallbackName</callbackId>
</ns2:message> 
Content-Type: application/vnd.whispir.message-v1+json

{ 
   "to" : "$mobile",
   "messageTemplateName" : "ReplyYesNoTemplate",
   "callbackId" : "myCallbackName"
}

If a message is sent using a template and associated ResponseRule, it would be helpful to know what response rule condition has matched when the reply is recieved from the end user. Whispir API facilitates this to be know in real time via the /callbacks endpoint.

How to use a callback to get the matched response rule condition?

After the Message is received:

Custom Parameters in Callback specifying the matched rule and category

<customParameters>
    <entry>
      <key>matchedCategory</key>
      <value>Reserved</value>
    </entry>
    <entry>
      <key>responseRule</key>
      <value>Reserved Words</value>
    </entry>

    ...

</customParameters>
"customParameters" : {
    "matchedCategory" : "Reserved",
    "responseRule" : "Reserved Words",

    ...
}

What is inside the custom Parameters?

For more details on the callbackParameters, refer to the /callbacks endpoint.

Contacts

API Endpoint

  • generic
https://api.<region>.whispir.com/contacts/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.contact-v1+xml
https://api.<region>.whispir.com/contacts/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.contact-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/contacts/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.contact-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/contacts/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.contact-v1+json
> Resource type

- application/vnd.whispir.contact-v1+xml
- application/vnd.whispir.contact-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

Contacts form the core of the Whispir offerings. They make up the base data to which and from all the communications are performed.

The Whispir API provides secure cloud based storage for your contact information. This can then easily be retrieved by any application or device that requires access, and has permission to do so.

Creating new Contacts

Creating new Contacts

Users can easily create new contacts by using the following request structure

POST https://api.<region>.whispir.com/contacts?apikey=[your api key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.contact-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:contact xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <firstName>John</firstName>
    <lastName>Wick</lastName>
    <status>A</status>
    <timezone>Australia/Melbourne</timezone>
    <workEmailAddress1>jsmith@testcompany.com</workEmailAddress1>
    <workMobilePhone1>61423456789</workMobilePhone1>
    <workCountry>Australia</workCountry>
    <messagingoptions>
        <messagingoption channel="sms">
            <enabled>true</enabled>
            <primary>WorkMobilePhone1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
        <messagingoption channel="email">
            <enabled>true</enabled>
            <primary>WorkEmailAddress1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
        <messagingoption channel="voice">
            <enabled>true</enabled>
            <primary>WorkMobilePhone1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
    </messagingoptions>
</ns2:contact>
Content-Type: application/vnd.whispir.contact-v1+json

{
    "firstName": "John",
    "lastName": "Wick",
    "status": "A",
    "timezone": "Australia/Melbourne",
    "workEmailAddress1": "jsmith@testcompany.com",
    "workMobilePhone1": "61423456789",
    "workCountry": "Australia",
    "messagingoptions": [{
          "channel": "sms",
          "enabled": "true",
          "primary": "WorkMobilePhone1"
    },{
          "channel": "email",
          "enabled": "true",
          "primary": "WorkEmailAddress1"
    },{
          "channel": "voice",
          "enabled": "true",
          "primary": "WorkMobilePhone1"
    }]
}

The successful response will be a 201 with the details of the contact created and its associated unique mri.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:contact xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <type>COMPANY</type>
    <firstName>John</firstName>
    <lastName>Wick</lastName>
    <locations>
        <location>
            <latitude>0.0</latitude>
            <longitude>0.0</longitude>
            <type>CurrentLocation</type>
        </location>
    </locations>
    <lastModifiedTime>2015-06-04T17:37:01+10:00</lastModifiedTime>
    <status>A</status>
    <timezone>+10</timezone>
    <workEmailAddress1>jsmith@testcompany.com</workEmailAddress1>
    <workMobilePhone1>61423456789</workMobilePhone1>
    <workCountry>Australia</workCountry>
    <mri>John_Wick.1143139@Contact.whispir.sg</mri>
    <messagingoptions>
        <messagingoption channel="sms">
            <enabled>true</enabled>
            <primary>WorkMobilePhone1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
        <messagingoption channel="email">
            <enabled>true</enabled>
            <primary>WorkEmailAddress1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
        <messagingoption channel="voice">
            <enabled>true</enabled>
            <primary>WorkMobilePhone1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
    </messagingoptions>
    <ns3:link uri="https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]" rel="self" method="GET"/>
    <ns3:link uri="https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]" rel="updateContact" method="PUT" type="application/vnd.whispir.contact-v1+json,application/vnd.whispir.contact-v1+xml"/>
    <ns3:link uri="https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]" rel="deleteContact" method="DELETE"/>
{
  "id": "CB4558257DD86D09",
  "type": "COMPANY",
  "firstName": "John",
  "lastName": "Wick",
  "locations": [
    {
      "latitude": "0.0",
      "longitude": "0.0",
      "type": "CurrentLocation"
    }
  ],
  "lastModifiedTime": "2015-06-04T17:37:01+10:00",
  "status": "A",
  "timezone": "+10",
  "workEmailAddress1": "jsmith@testcompany.com",
  "workMobilePhone1": "61423456789",
  "workCountry": "Australia",
  "mri": "John_Wick.1143139@Contact.whispir.sg",
  "messagingoptions": [
    {
      "channel": "sms",
      "enabled": "true",
      "primary": "WorkMobilePhone1"
    },
    {
      "channel": "email",
      "enabled": "true",
      "primary": "WorkEmailAddress1"
    },
    {
      "channel": "voice",
      "enabled": "true",
      "primary": "WorkMobilePhone1"
    }
  ],
  "link": [
    {
      "uri": "https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]",
      "rel": "self",
      "method": "GET"
    },
    {
      "uri": "https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]",
      "rel": "updateContact",
      "method": "PUT",
      "type": "application/vnd.whispir.contact-v1+json,application/vnd.whispir.contact-v1+xml"
    },
    {
      "uri": "https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]",
      "rel": "deleteContact",
      "method": "DELETE"
    }
  ]
}

To create a new contact, you can use the /contacts endpoint. The method is POST. Ensure that the following mandatory fields are provided for.

The following fields are required:

High-Level Request Elements
firstName: String
Specifies the firstName of the contact
lastName: String
Specifies the lastName of the contact
title: String
The title of the name
status: String
Specifies the validity status of the contact. The status can be one of -
  • Active (A)
  • Disabled (D)
companyName: String
Specifies the company name
jobTitle: String
Specifies the job title at the company
division: String
Specifies the Division in the company to which this contact is associated with
businessUnit: String
Specifies the Business Unit in the company to which this contact is associated with
department: String
Specifies the Department in the company to which this contact is associated with
Teams and Roles: String
Specifies the primary and Secondary values for each respective variable
  • teamName1, teamName2
  • role1, role2
Work Place Address: String
Specifies the primary and Secondary values for each respective type. Of all these the workEmailAddress1 is the mandatory field.
  • workEmailAddress1, workEmailAddress2
  • workAddress1, workAddress2
  • workSuburb, workState
  • workPostCode, workCountry
  • workPostalAddress1, workPostalAddress2
  • workPostalSuburb, workPostalState
  • workPostalPostCode, workPostalCountry
Work Place Phones: Number
Specifies the primary and Secondary values for each respective type. Of all these the workMobilePhone1 is the mandatory field.
  • workMobilePhone1, workMobilePhone2
  • workPhoneAreaCode1, workPhone1
  • workPhoneAreaCode2, workPhone2
  • workFaxAreaCode1, workFax1
  • workSetellitePhone, WorkOtherPhone
timezone: String
Specifies the timezone in which the contact lives in. Values in relation to GMT.

Supported values are:
  • Offset from GMT in the format `+/-NN` e.g. `+10`
  • Worldwide Timezone Format in the format `Country/City` e.g. `Australia/Melbourne`
For a list of available worldwide timezones, click here.
Personal Address: String
Specifies the primary and Secondary values for each respective type
  • personalEmailAddress1, personalEmailAddress2
  • personalAddress1, personalAddress2
  • personalSuburb, personalState
  • personalCountry, personalPostCode
Personal Phones: Number
Specifies the primary and Secondary values for each respective type
  • personalPhoneAreaCode1, personalPhone1
  • personalPhoneAreaCode2, personalPhone2
  • personalFaxAreaCode1, personalFax1
  • otherPhoneAreaCode1, otherPhone1
  • otherMobile
Alias Fields: String
The other (alias) name and title fields
  • otherFirstName, otherLastName, otherTitle
Messaging Options: Object
Read Format of Messaging Options below.
Other Fields : String
Whispir allows external developers to build a ‘Self-Subscription’ portal to allow their own contacts to self-register for internal systems. This is only applicable for customers using Whispir’s “Contact Portal” Product. To support this feature, the following fields are provided.
  • username - must be unique within the company (users and active contacts)
  • password - mandatory only in conjunction with the username
  • secretQuestion - mandatory (used for password reset)
  • secretAnswer - mandatory (used for password reset)

Format of Messaging Options

    <messagingoptions>
        <messagingoption channel="sms">
            <enabled>true</enabled>
            <primary>WorkMobilePhone1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
        <messagingoption channel="email">
            <enabled>true</enabled>
            <primary>WorkEmailAddress1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
        <messagingoption channel="voice">
            <enabled>true</enabled>
            <primary>WorkMobilePhone1</primary>
            <secondary></secondary>
            <tertiary></tertiary>
        </messagingoption>
    </messagingoptions>
"messagingoptions": [
    {
      "channel": "sms",
      "enabled": "true",
      "primary": "WorkMobilePhone1"
    },
    {
      "channel": "email",
      "enabled": "true",
      "primary": "WorkEmailAddress1"
    },
    {
      "channel": "voice",
      "enabled": "true",
      "primary": "WorkMobilePhone1"
    }
  ]

Whispir allows to define the different channels that needs to be enabled/used for communication. Using Messaging options, one can define the preferred/allowed channels and the respective primary, secondary, and tertiary contact numbers, emails to be used. These values again are derived from the above specified various personal, work attributes.

Available messaging options -

Each messaging options allows to specify the following 3 configuration settings

enabled
- true
- false
primary
workMobilePhone1 (Can be any of the valid attribute which has a value in it)
secondary
optional - workMobilePhone2
tertiary
optional - personalMobilePhone1

Retrieving Contacts

Retrieving a list of Contacts

Contacts can easily be retrieved from the Whispir API using the following endpoints:

HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.contact-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 1 of 1</status>
    <ns2:contacts>
        <ns2:contact>
            <id>AF48A9EC3F02E43C</id>
            <firstName>Fred</firstName>
            <lastName>Smith</lastName>
            <status>A</status>
            <messagingoptions/> > 
            <ns2:link method="GET" 
                      rel="self" 
                      uri="http://api.<region>.whispir.com/contacts/AF48A9EC3F02E43C?apikey=<your_api_key>"/>
        </ns2:contact>
    </ns2:contacts>
</ns2:return>
Accept: application/vnd.whispir.contact-v1+json

{
  "status": "1 to 1 of 1",
  "contacts": [
    {
      "id": "AF48A9EC3F02E43C",
      "firstName": "Fred",
      "lastName": "Smith",
      "status": "A",
      "messagingoptions": [],
      "link": {
        "method": "GET",
        "rel": "self",
        "uri": "http://api.<region>.whispir.com/contacts/AF48A9EC3F02E43C?apikey=<your_api_key>"
      }
    }
  ]
}

Contacts can be retrieved quite easily with a GET request to the /contacts. A simple /contacts will result in all contacts being retrieved with all of their information. No filters are applied.

Once the request is placed, the response will be a list of url’s to each of the contacts that the API user has access to/or has requested for via the search criteria.

Note: The sample request here shows contacts from the default workspace. If you need to retrieve contacts from a specific workspace, please ensure that the workspace information is passed in the URL.

URI for default workspace
- https://api..whispir.com/contacts?apikey=
URI for a specific workspace with id BC348DC83DF1AB34
- https://api..whispir.com/workspaces/BC348DC83DF1AB34/contacts?apikey=

Get a specific contact

Retrieving a specific Contact

Users can retrieve a specific contact by supplying the Contact ID in the URL.

HTTP 1.1 GET https://api.<region>.whispir.com/contacts/AF48A9EC3F02E43C?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.contact-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:contact xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
   <id>AF48A9EC3F02E43C</id>
   <firstName>Fred</firstName>
   <lastName>Smith</lastName>
   <status>A</status>
   <messagingoptions/> > 
   <ns2:link method="GET" 
             rel="self" 
             uri="http://api.<region>.whispir.com/contacts/AF48A9EC3F02E43C?apikey=<your_api_key>"/>
</ns2:contact>
Accept: application/vnd.whispir.contact-v1+json

{
   "id": "AF48A9EC3F02E43C",
   "firstName": "Fred",
   "lastName": "Smith",
   "status": "A",
   "messagingoptions": [],
   "link": {
     "method": "GET",
     "rel": "self",
     "uri": "http://api.<region>.whispir.com/contacts/AF48A9EC3F02E43C?apikey=<your_api_key>"
   }
}

To get details of a specific contact, the URI must be passed with the ID of the contact. So, the URI shall be:

https://api.<region>.whispir.com/contacts/AF48A9EC3F02E43C

Where AF48A9EC3F02E43C is the contact id.

Showing Custom Fields

Showing Custom Fields on Contacts

Within Whispir, contacts can have Custom Fields present to store data that is not supported on the default contact profile. Users can show this custom data for contacts by adding the customFields=true query parameter.

HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>&customFields=true
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.contact-v1+xml
Accept: application/vnd.whispir.contact-v1+json

Whispir supports extension of the default Contact Profile through the use of Custom Fields. Custom fields can support other fields that may be required to be stored on your Contacts, such as Staff ID, Internal Billing Codes, or One Up Manager.

These custom fields can be configured on any account through a Change Request to Whispir.

In order to reveal these custom fields on the contact profile, you can use the customFields=true flag within your API request.

/contacts/AB38CB3EFD38AFDB?customFields=true

Searching for Contacts

Searching for Contacts

Users can easily use further query parameters to search for specific contacts within Whispir.

HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>&firstName=Sam&sortOrder=desc&sortFields=workEmailAddressPrimary
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.contact-v1+xml
Accept: application/vnd.whispir.contact-v1+json

Contacts can be searched for in a given workspace by passing in valid search criteria. The search criteria usually can be any of the contact elements (field names) and will be sent in as part of the URI as query parameters.

This searching mechanism can be useful to see if any contacts exist in the system with a specific email address, phone number, or job role and so on. Simply to state, the API can help you search based on any attribute associated with the contact.

The key parameters that are required on the URL to facilitate this search are as follows:

URI Request Elements as Query Params
fieldname: String
Specifies the field name of the contact object. The field name could be any thing as long as it is a valid contact object.

Ex:
http://api..whispir.com/contacts?apikey=&firstName=Sam
sortOrder: String
The order in which you require the results to be returned. Either `asc` or `desc`.
sortFields: String
The fields that you require the ordering to be performed on. Multiple fields can be provided, separated by a comma.

Ex:
http://api..whispir.com/contacts?apikey=&firstName=Sam&sortFields=lastName,jobTitle

The search can also be done inside a specific workspace if needed, by adding the workspace information in the URI.

Note: There is no global search feature available where one can search on all the workspaces present in the system (under allowed user permission). So, When no workspace is provided, the search is performed on the default workspace of the user.

Searching for contacts with Custom Fields

Searching for Contacts using Custom Fields

Within Whispir, contacts can have Custom Fields present to store data that is not supported on the default contact profile. Users can search for contacts using this data using the API.

HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>&custom_staffID=123456
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.contact-v1+xml
Accept: application/vnd.whispir.contact-v1+json

As Whispir supports extension of the default Contact Profile through the use of Custom Fields. There may be cases where users want to search for Contacts that contain these specific fields. As such, the Whispir API supports searching for contacts using these custom fields.

Any custom field can be searched by adding the custom_ prepended to the name.

For example, if the field name is StaffId, then the URL would search for:

/contacts?custom_StaffId=12345

Updating Contacts

Updating Contacts

The following endpoints allow users to update contacts using the Whispir API.

HTTP 1.1 PUT https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.contact-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:contact xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <firstName>John</firstName>
    <lastName>Wick</lastName>
    <timeZone>+8</timezone>
    <jobTitle></jobTitle>

    ... remaining of the contact object
</ns2:contact>
Content-Type: application/vnd.whispir.contact-v1+json

{
    "firstName": "John",
    "lastName": "Wick",
    "timeZone": "+8",
    "jobTitle": "Whispir API Specialist",

    ... remaining of the contact object
}

The response to the PUT request upon success is a 204 No Content with no content being provided.

Updating a contact can be performed using a PUT request to the /contacts/{id} endpoint. So, to perform this, one must be knowing the exact “link” associated with the contact.

The application must provide all the fields during the update request, even if they are not being updated.

Any missing fields will be automatically removed from the existing record.

The Content-Type can be -

Note: You cannot selectively update the contact fields needed as this is a PUT request.

So the standard process for updating a contact record is -

  1. GET /contact/{id of contact}
  2. Update the contact field in the object to the required value
  3. PUT /contact/{id of contact} the new object

The response to the PUT request upon success is usually a 204 with no content being provided.

Deleting a contact

Deleting a contact

The following statement allows users to delete contacts using the Whispir API. Please note, this contact will only be deleted from the current workspace.

HTTP 1.1 DELETE https://api.<region>.whispir.com/contacts/124F6B2D46A5A268?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

Deleting a contact can be performed using a DELETE request to the /contacts/{id} endpoint. So, to perform this, one must be knowing the exact “link” associated with the contact.

After performing this request, the response does not contain any information other than the headers as it is not necessary.

The user has requested to delete a contact, and when the response of 204 No Content is returned, the contact is successfully deleted.

You can also delete a contact from all mapped workspace in a single api call. Please refer to the Advanced Options > Deleting a contact from all workspaces topic below.

Advanced Options

Whispir API provides some advanced options to perform search and data related queries on the contact information. These options can be performed by adding relevant query parameters to the URL.

Deleting a contact from all workspaces

Deleting a contact from all workspaces

The following statement allows users to delete a given contact from all mapped/copied workspaces using the API. Please note, this process is asynchronous and cannot be terminated once triggered.

HTTP 1.1 DELETE https://api.<region>.whispir.com/workspaces/A51D76194DDC09CC/contacts/124F6B2D46A5A268?apikey=<your_api_key>&action=deleteAll 
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

Whispir API allows to delete a contact from one workspace only by default at a time. However, due to certain business scenarios, there could be a need to delete all the references of a given contact from all workspaces in the company. Usually such references are made when there is a contact mapping rule (either automated, or via contact api) is in place.

To accomodate such a case, and also avoid calling DELETE /contacts/{id} repeatedly on all workspaces, Whispir API allows a “Delete All” functionality for contacts.

The API call involves passing a action=deleteAll parameter in the url query params. Once this action is triggered, all the contact references in all the workspaces for a given contact{id} are deleted, asynchronously. There is no way to stop the process once it is triggered. So, use it wisely and only when you are sure of a need to delete the contact in all workspaces. You have been warned.

The following are the types of contact that can be deleted:

Searching with multiple criteria

Searching with multiple search criteria

The following query parameters allow users to search with more than one piece of search criteria on the contact profile.

HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>&firstName=Sam&lastname=gamjee
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

The API allows to search for a contact based on any attribute/ data element associated with the contact. This is not limited to just one attribute, but multiple attributes can be searched at the same time.

URI Request Elements as Query Params
fieldname: String
Specifies the field name of the contact object. The field name could be any thing as long as it is a valid contact object.

Ex:
http://api..whispir.com/contacts?apikey=&firstName=Sam&lastName=gamjee
sortOrder: String
The order in which you require the results to be returned. Either `asc` or `desc`.
sortFields: String
The fields that you require the ordering to be performed on. Multiple fields can be provided, separated by a comma.

Ex:
http://api..whispir.com/contacts?apikey=&firstName=Sam&sortFields=lastName,jobTitle

Choosing the data elements

Choosing specific data elements to return

The following query parameters allow users to return data fields from the contact profile that are specifically what they are looking to retrieve.

HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>&fields=workEmailAddress1,workMobilePhone1&firstname=Sam
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.contact-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 1 of 1</status>
    <ns2:contacts>
        <ns2:contact>
            <id>DC09CC30243A51D5</id>
            <workEmailAddress1>sam@gamjee.com</workEmailAddress1>
            <workMobilePhone1>61423456789</workMobilePhone1>
            <messagingoptions/>
            <ns2:link uri="https://api.<region>.whispir.com/contacts/DC09CC30243A51D5?apikey=<your_key_api>" rel="self" method="GET"/>
        </ns2:contact>
    <ns2:contacts>
</ns2:return>
HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>&fields=workEmailAddress1,workMobilePhone1&firstname=Sam
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.contact-v1+json

{
  "contacts": [{
      "id": "DC09CC30243A51D5",
        "workEmailAddress1":"sam@gamjee.com",
        "workMobilePhone1":"61423456789"
        "messagingoptions": [],
        "link": [{
          "uri": "https://api.<region>.whispir.com/contacts/DC09CC30243A51D5?apikey=<your_key_api>",
          "rel": "self",
          "method": "GET"
        }]
    }

When requesting the contact information, a simple GET request on the /contact API gives you the basic details of the contact.

To get all the details or fields other than the ones given by default, you have to follow the link and do another GET request. This can be easily skipped, by asking the API to give you specific fields and data right away in the first GET \contact call itself.

This can be done by passing the required fields in the URL via the fields parameter. You can also use this in conjunction with the search criteria. An Example use could be to get the mobile number and the email of all contacts with firstname as 'Sam’.

Contact Devices

Unlike SMS, or EMail, where the recipient is an adhoc phone number, or email, Push in Whispir has to be sent to registered contacts. So, sending Push by putting in the push-token in “to” field is not allowed. The reason for this primarily is the way Push works. A push/device token alone is not suffecient for the push to succeed, it needs the API Keys (in GCM), and Certificates (in APNS) of your App too. Providing that information in every API call is costly and troublesome, so Whispir has consciouly built the product to reduce the friction from such calls and into a simple pre-registered Apps and contact-devices method.

So, to send a push notification to a user device, one has to register the push token as a device under a contact. The device is a combination of device token, app platform information (APN, GCM, …), and other meta data that helps Whispir to manage and do push properly.

API Endpoint

  • generic
https://api.<region>.whispir.com/contacts/{:contact-id}/devices?apikey=<your_api_key>
Content-Type: application/vnd.whispir.contactdevice-v1+xml
https://api.<region>.whispir.com/contacts/{:contact-id}/devices?apikey=<your_api_key>
Content-Type: application/vnd.whispir.contactdevice-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:workspace-id}/contacts/{:contact-id}/devices?apikey=<your_api_key>
Content-Type: application/vnd.whispir.contactdevice-v1+xml
https://api.<region>.whispir.com/workspaces/{:workspace-id}/contacts/{:contact-id}/devices?apikey=<your_api_key>
Content-Type: application/vnd.whispir.contactdevice-v1+json
> Resource type

- application/vnd.whispir.contactdevice-v1+xml
- application/vnd.whispir.contactdevice-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

A Device is a sub-resource to contact, and a Contact can have minimum of 0 to a maximum of 3 devices by default. However, the 3 device limit can be raised to a 10 depending on your app profile needs. Such limit is set during the App Registration

To understand the relationship easily, refer to the apps section.

Creating new Devices

Creating new Devices

New Devices can only be created under a given contact easily by following the request structure

POST https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices?apikey=[your_api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.contactdevice-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:device xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <deviceName>Device 1</deviceName>
    <appId>B1A24A8BF2DBB10E</appId>
    <platform>APNS</platform>
    <deviceOS>IOS 7</deviceOS>
    <deviceModel>Iphone 7 Plus</deviceModel>
    <status>active</status>
    <pushToken>15a01046 16f6f4f9 2f2055b5 f12d2c93 a70de908 487762f9 7b6c7115 e30083b1</pushToken>
</device>
Content-Type: application/vnd.whispir.contactdevice-v1+json

{
    "deviceName": "BCDF6B61-CA55-F287FF272101-4496-9DA9",
    "appId": "B1A24A8BF2DBB10E",
    "platform": "APNS",
    "deviceOS": "IOS 9",
    "deviceModel": "Iphone X",
    "status": "active",
    "pushToken": "15a01046 16f6f4f9 2f2055b5 f12d2c93 a70de908 487762f9 7b6c7115 e30083b1"
}

The successful response will be a 201 with the details of the device created and its associated unique deviceID.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:device xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <id>1B0C3FC62D59BF90</id>
    <deviceName>Device 1</deviceName>
    <appId>B1A24A8BF2DBB10E</appId>
    <registrationDate>2017-11-17</registrationDate>
    <lastModifiedDate>2017-11-17</lastModifiedDate>
    <platform>APNS</platform>
    <deviceOS>IOS</deviceOS>
    <deviceModel>Iphone 7 Plus</deviceModel>
    <status>active</status>
    <pushToken>15a01046 16f6f4f9 2f2055b5 f12d2c93 a70de908 487762f9 7b6c7115 e30083b1</pushToken>
    <ns3:link uri="https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]" rel="self" method="GET"/>
    <ns3:link uri="https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]" rel="updateDevice" method="PUT" type="application/vnd.whispir.contactdevice-v1+json,application/vnd.whispir.contactdevice-v1+xml"/>
    <ns3:link uri="https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]" rel="deleteDevice" method="DELETE"/>
</device>
{
    "id": "1B0C3FC62D59BF90",
    "deviceName": "BCDF6B61-CA55-F287FF272101-4496-9DA9",
    "appId": "B1A24A8BF2DBB10E",
    "registrationDate":"2017-11-17",
    "lastModifiedDate":"2017-11-17",
    "platform": "APNS",
    "deviceOS": "IOS 9",
    "deviceModel": "Iphone X",
    "status": "active",
    "pushToken": "15a01046 16f6f4f9 2f2055b5 f12d2c93 a70de908 487762f9 7b6c7115 e30083b1",
  "link": [
    {
      "uri": "https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]",
      "rel": "self",
      "method": "GET"
    },
    {
      "uri": "https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]",
      "rel": "updateDevice",
      "method": "PUT",
      "type": "application/vnd.whispir.contactdevice-v1+json,application/vnd.whispir.contactdevice-v1+xml"
    },
    {
      "uri": "https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]",
      "rel": "deleteDevice",
      "method": "DELETE"
    }
  ]
}

To create a new device, you can use the /contacts/{:cid}/devices endpoint. The method is POST. Ensure that the following mandatory fields are provided for.

The following fields are required:

High-Level Request Elements
deviceName: String
Specifies the name of the device for visual reference in UI
appId: String
Specifies the ID of the app the device is installed with. This ID refers to the Apps Endpoint > App ID
appVersion: String
The version of your App installed on the user device. This is purely meta information that helps to understand the push success/failure based on app version if any.
platform: String
Specifies the app’s platform. The value can be one of -
  • APNS - for Production APNS apps
  • APNS_SANDBOX - for Sandbox APNS apps
  • GCM - for FCM/GCM Apps
deviceOS: String
Specifies the device OS. The value can be one of -
  • IOS
  • Android
deviceModel: String
Specifies the model of the user device
status: String
Specifies the status of the device. Push will be only sent to the active devices under a given contact. It can be one of
  • ACTIVE (A)
  • DISABLED (D)
  • DELETED (E)
Note: The default value is “Active”.
pushToken: String
Specifies the pushToken .a.k.a. deviceToken given to your app by APNS/GCM to receive the push notification.

Notes:

Retrieving Devices

Retrieving the list of Devices under a Contact

Devices can easily be retrieved from the Whispir API using the following endpoints:

HTTP 1.1 GET https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.contact-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
        <ns2:contact>
            <id>AF48A9EC3F02E43C</id>
            <firstName>Fred</firstName>
            <lastName>Smith</lastName>
            <status>A</status>
            <messagingoptions/>
            <devices/>
            <ns2:link method="GET" 
                      rel="self" 
                      uri="http://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}?apikey=<your_api_key>"/>
        </ns2:contact>
</ns2:return>
Accept: application/vnd.whispir.contact-v1+json

{
    {
      "id": "AF48A9EC3F02E43C",
      "firstName": "Fred",
      "lastName": "Smith",
      "status": "A",
      "messagingoptions": [],
      "devices":[], //list of devices as array of objects if any
      "link": {
        "method": "GET",
        "rel": "self",
        "uri": "http://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}?apikey=<your_api_key>"
      }
    }
}

Devices are sub-resource to Contacts. So, Devices belonging to a specific contact can be retrieved quite easily with a GET request to the /workspaces/{:wid}/contacts/{:cid}. A simple workspaces/{:wid}/contacts/{:cid} will result in all devices being retrieved for that contact with all of their information under the devices key. No filters are applied.

Note: Deleted devices cannot be retrieved. Only the “Active” and “Disabled” status devices can be seen

Updating Devices

Updating Contact Devices

The following endpoints allow users to update contact’s devices using the Whispir API.

HTTP 1.1 PUT https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/{:did}?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.contactdevice-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<<ns2:device xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <deviceName>Device 1</deviceName>
    <appId>B1A24A8BF2DBB10E</appId>
    <platform>APNS</platform>
    <deviceOS>IOS 9</deviceOS>
    <deviceModel>Iphone 7 Plus</deviceModel>
    <status>active</status>
    <pushToken>15a01046 16f6f4f9 2f2055b5 f12d2c93 a70de908 487762f9 7b6c7115 e30083b1</pushToken>
</device>
Content-Type: application/vnd.whispir.contactdevice-v1+json

{
    "deviceName": "BCDF6B61-CA55-F287FF272101-4496-9DA9",
    "appId": "B1A24A8BF2DBB10E",
    "platform": "APNS",
    "deviceOS": "IOS 9",
    "deviceModel": "Iphone 8",
    "status": "active",
    "pushToken": "15a01046 16f6f4f9 2f2055b5 f12d2c93 a70de908 487762f9 7b6c7115 e30083b1"
}

The response to the PUT request upon success is a 204 No Content with no content being provided.

Updating a device can be performed using a PUT request to the /contacts/{:cid}/devices/{:did} endpoint. So, to perform this, one must be knowing the exact “link” associated with the contactdevice.

The application must provide all the fields during the update request, even if they are not being updated.

The Content-Type can be -

Note: You cannot selectively update the device fields needed as this is a PUT request.

So the standard process for updating a contact device record is -

  1. GET /contact/{id of contact}/devices/{id of device}
  2. Update the device field in the object to the required value
  3. PUT /contact/{id of contact}/devices/{id of device} the new object

Reasons to Update

  1. Device token (Push tokens) might change when the user re-installs or upgrades the OS on their phone
  2. Device information might have changed as a result of user upgrading their OS
  3. Change of device status to “Disabled”, if the push fails consistently. Whispir does not update the device to “Disabled” upon first failure, it only does that on second failure given the device was not updated after first failure. So, you will only be charged for the Push, as long as the status is “Active”
  4. Update does not automatically reset the “Disabled” status. You as the App owner has to specifically turn on the status back to “ACTIVE”, so that new push notifications can be triggered again.
  5. Disabled devices will not receive any push notifications.

The response to the PUT request upon success is usually a 204 with no content being provided.

Deleting a device

Deleting a contact device

The following statement allows users to delete contact’s device using the Whispir API. Please note, this device cannot be recovered back once deleted.

HTTP 1.1 DELETE https://api.<region>.whispir.com/contacts/124F6B2D46A5A268/device/{:did}?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

Deleting a contact device can be performed using a DELETE request to the /contacts/{:cid}/devices/{:did} endpoint. So, to perform this, one must be knowing the exact “link” associated with the contact device.

After performing this request, the response does not contain any information other than the headers as it is not necessary.

The user has requested to delete a contactdevice, and when the response of 204 No Content is returned, the contactdevice is successfully deleted.

FAQ

The following are some of the FAQ on contact devices

  1. I do not want to reveal my app user’s name under the contact due to security reasons. How can i still create a contact and do Push?
    Ans: Whispir asks for firstName, lastName, timeZone, and Country of the contact. You can choose to set any masked value for the firstName and lastName data points. The masked value is only understood by your program and cor-relates that to your actual user in your DB. Whispir has no interest in that information. So, your personal identifiable data is safe withing your servers still.

  2. How many devices can i register for a single App?
    Ans: This is dependent on the options.deviceLimit value set for the App when you registered it. Default is 3, and max allowed by Whispir is 10. This means your app user has upto 10 devices and has the app installed on all the 10 devices. Something not possible in real world, but still allowed.

  3. My app user’s push token is changed. What should i do?
    Ans: Update the contact devices that are tied to that token with the latest value, by using Updating Devices . Whispir would not know that the token has changed, so its your responsibility to periodically update the token to keep them correct and so Whispir can ensure a successful delivery of your Push

  4. What happens if i register two devices with same tokens, and appId information under a single contact?
    Ans: If both the devices are “ACTIVE”, then Whispir will send 2 push notifcations to the App.

  5. Can i specifically mention, which device under my contact should receive the push?
    Ans: No. Whispir sends the push to all devices that matches the appID under the given MRI.

  6. What If I registered two devices from two different platforms (APNS/GCM) under the same contact, and want to send to both of them at the same time?
    Ans: As the Apps registered for each platform will be different, you should trigger the message twice, once for each app. A single trigger does not allow sending messages to both platforms in one go.

  7. Can I tie/related the same device to multiple contacts?
    Ans: No. You have to register them separately under each contact, and also update them properly if the push token changes.

  8. If I use contact mapping, will my devices be also mapped automatically between workspaces?
    Ans: Yes, and this feature allows you to register your contacts in one workspace, and with mapping be able to trigger Push in other mapped workspaces also by using the base workspace contact mri value.

Distribution Lists

API Endpoint

  • generic
https://api.<region>.whispir.com/distributionlists/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.distributionlist-v1+xml
https://api.<region>.whispir.com/distributionlists/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.distributionlist-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/distributionlists/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.distributionlist-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/distributionlists/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.distributionlist-v1+json
> Resource type

- application/vnd.whispir.distributionlist-v1+xml
- application/vnd.whispir.distributionlist-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

Whispir’s API allows users to categorise their contacts into different groups to simplify the distribution of messages. This allows for

These logical groups can help to target specific communications to specific people. A contact can be part of any number of groups.

Whispir supports 3 types of distribution lists.

Creating Distribution lists

Creating Distribution Lists

Distribution Lists can contain lists of Contacts, Users or other Distribution Lists

POST https://api.<region>.whispir.com/distributionlists?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.distributionlist-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:distributionlists xmlns:ns2="http://schemas.api.whispir.com">
    <name>My Distribution List</name>
    <description></description>
    <access>Open</access>
    <visibility>Public</visibility>
    <contactIds></contactIds>
    <userIds></userIds>
    <distListIds></distListIds>
</ns1:distributionlists>
Content-Type: application/vnd.whispir.distributionlist-v1+json

{
    "name" : "My Distribution List",
    "description" : "",
    "access" : "Open",
    "visibility" : "Public",
    "contactIds" : "",
    "userIds" : "",
    "distListIds" : ""
}

Users should expect a 201 Created response after executing this request.

Creating Dynamic Distribution Lists

Dynamic Distribution Lists contains rules with filters to determine the members dynamically

POST https://api.<region>.whispir.com/distributionlists?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.distributionlist-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:distributionlist xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
   <name>My Dynamic DistributionList</name>
   <description>My Distribution list</description>
   <access>Open</access>
   <type>dynamic</type>
   <entityType>Contact</entityType>
   <visibility>Public</visibility>
   <rules>
       <ruleContent>sales</ruleContent>
       <ruleFilter>division</ruleFilter>
       <ruleFilterActualName>Division</ruleFilterActualName>
   </rules>
   <rules>
       <ruleContent>apac</ruleContent>
       <ruleFilter>businessUnit</ruleFilter>
       <ruleFilterActualName>Business Unit</ruleFilterActualName>
   </rules>
</ns1:distributionlist>
Content-Type: application/vnd.whispir.distributionlist-v1+json

  {
    "name" : "My Dynamic DistributionList",
    "description" : "My Distribution list",
    "access" : "Open",
    "visibility" : "Public",
    "type" : "dynamic",
    "entityType" : "Contact",
    "rules" : [{
            "ruleFilter" : "division",
            "ruleFilterActualName" : "Division",
            "ruleContent" : "sales"
        },{
            "ruleFilter" : "businessUnit",
            "ruleFilterActualName" : "Business Unit",
            "ruleContent" : "apac"
        }]
}

Users should expect a 201 Created response after executing this request. If the rules are incorrectly passed, then a 422 Unprocessible Entity is thrown.

Distribution lists can be created within the Default Workspace, or within a Specific Workspace. Distribution lists can contain Contacts, Users, or nested Distribution Lists to create any structure that is required within your environment.

The MRI value is important here. It is the required unique identifier for any communications that are to be sent out to this distribution list.

To create a new distribution list, you can use the /distributionlists endpoint.

Only 4 fields are required:

  1. name - the name of the distribution list to be created
  2. access - Open Or Restricted
  3. visibility - Private Or Public
  4. type - Static or Dynamic

In the case of Dynamic Distribution list, the required fields will be more than usual. As following -

  1. name - the name of the distribution list to be created
  2. access - Open Or Restricted
  3. visibility - Private Or Public
  4. type - Dynamic
  5. entityType - contact (limited to contacts only at the moment)
  6. rules - The rules is an object that specifies the rules that should be applied on the entityType values to pick the appropriate contact at the moment of usage (not creation). The rules contain an array of rule definitions with a minimum of one rule to be defined. If not done so, a 422 unprocessable entity is returned by the API duuring the distribution list creation/edit.

Note: The contactIds, userIds, and distListIds values are ignored when the type is dynamic, as the rules govern the members of the Distribution list

High-Level Request Elements
name String
Specifies the name of the distribution list. This has to be unique, and should not contain any special characters (except space) in it.
description String
Specifies a description for other users to see what this Distribution List should be used for.
access String
Allows the user to specify the access type for this DL.
  1. Open - Anyone can subscribe to this distribution list via the Whispir Portal
  2. ByApproval - Anyone can subscribe using the Whispir Portal, however they are not officially on the list until their access is approved.
  3. Restricted - The distribution list is not visible in the Whispir Portal
visibility String
Allows the user to specify the visibility for this DL.
  1. Public - Any user/contact in any workspace can map themselves to this Distribution List within the Whispir Portal.
  2. Private - Only users/contacts in the current workspace can map themselves to this Distribution List
type String
Allows the user to specify the type for this DL. Default is `static`
  1. Static - The contacts on the list don’t change unless you manually add or remove them (unlike a dynamic distribution list).
  2. Dynamic - The contacts on the list change based on the rulesFilter applied at the time of usage. There is good likelyhood of contacts changing for each run depending on the rules
entityTpe String
Only mandatory when the type is dynamic. The value is currently strictly limited to “contact”.
rules Object
The rules contains array (child) of rule definitions. Each rule is a object with 3 keys in them.
  1. ruleFilter - contains any of the contact profile elements that are available for searching e.g. Division, Department, Role.
  2. ruleFilterActualName - contains the matching string to be compared for the distribution list.
  3. ruleContent - contains the matching string to be compared with the contact element for being a part of the Distribution list
contactIds String
Comma separated list of userIds who can have access, visibility on this Distribution list. This information can be provided at the time of the DL creation or also later updated via a PUT request.
userIds String
Comma separated list of userIds who can have access, visibility on this Distribution list. This information can be provided at the time of the DL creation or also later updated via a PUT request.
distListIds String
Comma separated list of Distribution List IDs which can be nested distribution list to this DL.
List of common ruleFilter and ruleFilterActualName values
Common Values If your company has custom contact properties, that you want to include in the DL ruleFilter, then please reach out to Whispir Support or your Account Manager for the details.
  • ruleFilter : ruleFilterActualName
  1. businessUnit : Business Unit
  2. companyName : Organization Name
  3. createdtime__timestamp : Created Time
  4. department : Department
  5. division : Division
  6. firstName : First Name
  7. group_messagingoption_active__boolean : Is Active
  8. group_messagingoption_fieldmapping : Mapped Field
  9. group_messagingoption_type__dropdown : Type
  10. jobTitle : Job Title
  11. lastName : Last Name
  12. lastmodifiedtime__timestamp : Last Updated Time
  13. personalAddress1 : Personal Address1
  14. personalAddress2 : Personal Address2
  15. personalCountry : Personal Country
  16. personalEmailAddress1 : Personal Email Address
  17. personalEmailAddress2 : Personal Email Address Secondary
  18. personalMobilePhone1 : Personal Mobile Phone Primary
  19. personalMobilePhone2 : Personal Mobile Phone Secondary
  20. personalPhone1 : Personal Phone Primary
  21. personalPhone2 : Personal Phone Secondary
  22. personalPhoneAreaCode1 : Personal Phone Areacode Primary
  23. personalPhoneAreaCode2 : Personal Phone Areacode Secondary
  24. personalPostCode : Personal Postcode
  25. personalState : Personal State
  26. personalSuburb : Personal Suburb
  27. role1 : Role
  28. role2 : Additional Role
  29. teamName1 : Team Name
  30. teamName2 : Additional Team Name
  31. timezone : Timezone
  32. workAddress1 : Work Address1
  33. workAddress2 : Work Address2
  34. workCountry : Work Country
  35. workEmailAddress1 : Work Email Address Primary
  36. workEmailAddress2 : Work Email Address Secondary
  37. workMobilePhone1 : Work Mobile Phone Primary
  38. workMobilePhone2 : Work Mobile Phone Secondary
  39. workOtherPhone : Phone Other
  40. workPhone1 : Work Phone Primary
  41. workPhone2 : Work Phone Secondary
  42. workPhoneAreaCode1 : Work Phone Areacode Primary
  43. workPhoneAreaCode2 : Work Phone Areacode Secondary
  44. workPostCode : Work Postcode
  45. workPostalAddress1 : Work Postal Address1
  46. workPostalAddress2 : Work Postal Address2
  47. workPostalCountry : Work Postal Country
  48. workPostalPostCode : Work Postal PostCode
  49. workPostalState : Work Postal State
  50. workPostalSuburb : Work Postal Suburb
  51. workSetellitePhone : Satellite Phone
  52. workState : Work State
  53. workSuburb : Work Suburb

Retrieving Distribution Lists

Retrieving Distribution Lists

The following snippets show how you can use the Whispir API to retrieve Distribution List information.

HTTP 1.1 GET /distributionlists?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.distributionlist-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 2 of 2</status>
    <ns2:distributionLists>
        <ns2:distributionList>
            <id>CF5AF1AE49ED07A6</id>
            <name>DL 1</name>
            <mri>dl1.company_name@list.company.whispir.sg</mri>
            <description>Distribution list for company 1</description>
            <memberCount>4</memberCount>
            <access>ByApproval</access>
            <visibility>Private</visibility>
            <ns2:link uri="https://api.<region>.whispir.com/distributionlists/CF5AF1AE49ED07A6?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:distributionList>
        <ns2:distributionList>
            <id>9FF7C2B470CCEC1E</id>
            <name>Docs Distribution List</name>
            <mri>Docs_Distribution_List.company@list.company.whispir.sg</mri>
            <description>A Distribution List created while writing the docs</description>
            <memberCount>2</memberCount>
            <access>Open</access>
            <visibility>Public</visibility>
            <ns2:link uri="https://api.<region>.whispir.com/distributionlists/9FF7C2B470CCEC1E?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:distributionList>
    </ns2:distributionLists>
</ns2:return>
Content-Type: application/vnd.whispir.distributionlist-v1+json

{
  "distributionLists" : [ {
    "id" : "CF5AF1AE49ED07A6",
    "name" : "DL 1",
    "mri" : "dl1.company_name@list.company.whispir.sg",
    "description" : "test distribution list for company",
    "memberCount" : "4",
    "access" : "ByApproval",
    "visibility" : "Private",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/distributionlists/CF5AF1AE49ED07A6?apikey=your_api_key",
      "rel" : "self",
      "method" : "GET"
    } ]
  }, {
    "id" : "9FF7C2B470CCEC1E",
    "name" : "Docs Distribution List",
    "mri" : "Docs_Distribution_List.company@list.company.whispir.sg",
    "description" : "A Distribution List created while writing the docs",
    "memberCount" : "2",
    "access" : "Open",
    "visibility" : "Public",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/distributionlists/9FF7C2B470CCEC1E?apikey=your_api_key",
      "rel" : "self",
      "method" : "GET"
    } ]
  }],
  "status" : "1 to 2 of 2    ",
  "link" : [ ]
}

Similar to the creation of distribution list, retrieval of such list too is bound to the workspace it belongs to. So, a distribution list belonging to a workspace cannot be accessed from another workspace.

The code samples on the right describe the methods to retrieve Distribution Lists using the Whispir API.

Retrieving a specific Distribution List by ID

HTTP 1.1 GET /distributionlists/E07BA0DA35B0B1EF?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

Searching for Distribution Lists

Search for a Distribution List by name

Users can easily append the &name=My DL Name query parameter to search the Whispir API for a specific Distribution List.

HTTP 1.1 GET /distributionlists?apikey=<your_api_key>&name=My%20Distribution%20List
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

Search for a Distribution List by description

Users can easily append the &description=My DL Description query parameter to search the Whispir API for a specific Distribution List.

HTTP 1.1 GET /distributionlists?apikey=<your_api_key>&description=company_name
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

The distribution list is usually retrieved by its id, but one can also search or refer to the distribution list by its name. This feature has to do with the unique name requirement for the distribution list.

Apart from the name, the description field can also be used to search for a distribution list. While name can be directly used to send in messages, the description is solely for the purpose of search. Once search yields the required result, the mri has to be picked from the selected DL and then used to send the messages.

Both these operations can be performed by passing in the relevant search parameters in the URL - as query params

Modifying Distribution Lists

Getting the DL

Request

GET https://api.<region>.whispir.com/distributionlists/CF5AF1AE49ED07A6?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

Response

Accept: application/vnd.whispir.distributionlist-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:distributionlists xmlns:ns2="http://schemas.api.whispir.com">
    <id>CF5AF1AE49ED07A6</id>
    <name>Rockstar Distribution List</name>
    <description>All the rocks were once stars - astrophysicist inside me</description>
    <access>Open</access>
    <visibility>Public</visibility>
    <contactIds>7CC205AE17FFDC8A,92XC05AE154FDC8A</contactIds>
    <userIds></userIds>
    <distListIds></distListIds>
...
</ns1:distributionlists>
Accept: application/vnd.whispir.distributionlist-v1+json
{
    "id": "CF5AF1AE49ED07A6",
    "name" : "Rockstar Distribution List",
    "description" : "All the rocks were once stars - astrophysicist inside me",
    "access" : "Open",
    "visibility" : "Public",
    "contactIds" : "7CC205AE17FFDC8A,92XC05AE154FDC8A",
    "userIds" : "",
    "distListIds" : "",
...
}

Updating the DL

Lets do the following in a single request

  1. Remove a contactId
  2. Add two new UserId values

Request

PUT https://api.<region>.whispir.com/distributionlists/CF5AF1AE49ED07A6?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.distributionlist-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:distributionlists xmlns:ns2="http://schemas.api.whispir.com">
    <id>CF5AF1AE49ED07A6</id>
    <name>Rockstar Distribution List</name>
    <description>All the rocks were once stars - astrophysicist inside me</description>
    <access>Open</access>
    <visibility>Public</visibility>
    <contactIds>7CC205AE17FFDC8A,92XC05AE154FDC8A</contactIds>
    <userIds></userIds>
    <distListIds></distListIds>
...
</ns1:distributionlists>
Content-Type: application/vnd.whispir.distributionlist-v1+json

{
    "id": "CF5AF1AE49ED07A6",
    "name" : "Rockstar Distribution List",
    "description" : "All the rocks were once stars - astrophysicist inside me",
    "access" : "Open",
    "visibility" : "Public",
    "contactIds" : "7CC205AE17FFDC8A",
    "userIds" : "F0547F6F2E4839F8,900972D1C916FE84",
    "distListIds" : "",
...
}

Response

204 No Content

A distribution list allows you to associate the following -

Any or all three of these can be updated via the PUT method along with the DL properties (name, description, location etc).

The steps usually are -

  1. Create a Distribution List (DL)
  2. While creating the DL itself, you can put in the ContactIds, UserIds, distListIds (nested) so that the DL is created with those values readily placed in.

  3. After the DL is created, if you want to add/update the values, then

  4. Do a GET request to retrieve the specific DL.

    a. GET https://api..whispir.com/workspaces/{id}/distributionlists/{id}?apikey=xxxx

    b. This will return you the DL object

  5. Modify the DL properties (name, description, contactIds, UserIds, dlIds, location etc) as needed

  6. Do a PUT request to update the DL details

    a. PUT https://api..whispir.com/workspaces/{id}/distributionlists/{id}?apikey=xxxx

    b. Successful update gives you a 204 No Content

    c. The contactIds, userIds, distListIds can be passed all together in a single request.

Note:

  1. If an existing contactId is again added, it does neither throws an error, nor create two entries. The contactId is just neglected and only 1 record is maintained.

  2. If the PUT request was successful, the expected response code is a 204 No Content

  3. For Modifying the Location Information refer to Location Tags for Distribution Lists

Sending Messages

Sending Messages to Distribution Lists

The API call is a POST request to the /messages endpoint.

POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>Docs_Distribution_List.company@list.company.whispir.sg</to>
    <subject>Simple SMS to List of contacts in the distribution list</subject>
    <body>This is the content of my sample sms message.</body>
</ns2:message>
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "Docs_Distribution_List.company@list.company.whispir.sg",
    "subject" : "Simple SMS to List of contacts in the distribution list",
    "body" : "This is the content of my sample sms message."
}

Sending the message via the distribution list is very straight forward. The important key needed here is MRI of the distribution list.

This will result in the response of 202 Accepted and the message will be sent to all distribution list participants.

Deleting Distribution Lists

Deleting Distribution Lists

The following API requests allow users to remove Distribution Lists from the Whispir API.

DELETE https://api.<region>.whispir.com/distributionlists/E07BA0DA35B0B1EF?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
DELETE https://api.<region>.whispir.com/distributionlists/E07BA0DA35B0B1EF?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

After performing the request the expected successful response is 204 No Content.

Deleting the distribution is done via a DELETE /distributionlist/{id} endpoint.

You can only delete the distribution list that you have created or a valid userId associated with the specific distribution list.

Location Tags for Distribution Lists

Distribution Lists allow to add Locations as their property. This can be useful to geo-tag a group of users or assets in a single location. The location data can be set of multiple values with each entry specifying the lat, lon values and the type of data. There is no TTL attached to these values, so using the ‘type’ of location can help with proper identification and data stale ness.

Type can be:

  1. 'CurrentLocation’ - used to specify that the data is latest and is nearest best last known location of the DL asset
  2. ’-any-key-identifier’ - can be any custom identifier key name that you can use to identify/associate the location value with. Like 'AlternativeLocation’ or 'LocationB’ or 'LocationX’ etc.

Creating Distribution Lists with Location values

Distribution Lists can contain lists of Contacts, Users or other Distribution Lists

POST https://api.<region>.whispir.com/distributionlists?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.distributionlist-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:distributionlists xmlns:ns2="http://schemas.api.whispir.com">
    <name>My Distribution List</name>
    <description></description>
    <access>Open</access>
    <visibility>Public</visibility>
    <contactIds></contactIds>
    <userIds></userIds>
    <distListIds></distListIds>
    <locations>
    <location>
        <latitude>47.6204232</latitude>
        <longitude>-122.3493552</longitude>
        <type>CurrentLocation</type>
    </location>
    </locations>
</ns1:distributionlists>
Content-Type: application/vnd.whispir.distributionlist-v1+json

{
    "name" : "My Distribution List",
    "description" : "",
    "access" : "Open",
    "visibility" : "Public",
    "contactIds" : "",
    "userIds" : "",
    "distListIds" : "",
    "locations": [
        {
          "longitude": -122.3493552,
          "latitude": 47.6204232,
          "type": "CurrentLocation"
        }
    ]
}

Users should expect a 201 Created response after executing this request. Or 204 No Content in case of a distribution lost update using PUT

Callbacks

Whispir utilises API Callbacks to send simple notifications to different registered services in the event that some change has occurred on the Whispir Platform.

Callbacks are used widely in web applications to transfer information that may become avialable at some point in the future. These are sometimes referred to as ‘webhooks’.

The benefits of using api callbacks are:

The word 'Callback’ is termed to help users understand that Whispir will call you back when data is made available.

So, it is you who creates an endpoint (a page in your application) that Whispir shall callback upon an event happening. That endpoint can simply be your existing application (as mentioned earlier) or another application that needs/processes the response information.

Callback Overview

Callback Overview

Whispir can notify your application when your SMS, Email or Voice messages receive a reply.

An example callback that your application or service would receive is specified below.

HTTP 1.1 POST http://yourserver/callback.php
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:deliveryResponse xmlns:ns2="http://schemas.api.whispir.com">
  <messageid>ABC4857BCCF484575FCA</messageid>
  <messagelocation>https://api.<region>.whispir.com/messages/ABC4857BCCF484575FCA</messagelocation>
  <from>
      <name>Fred Waters</name>
      <mri>Fred_Waters.528798.Sandbox@Contact.whispir.com</mri>
      <mobile>$mobile</mobile>
      <email>me@example.com</email>
      <voice>$mobile</voice>
  </from>
  <responseMessage>
      <channel>SMS</channel>
      <acknowledged>09/01/16 13:22</acknowledged>
      <content>Yes, I accept. Will I need to bring steel cap boots?</content>
  </responseMessage>
</ns2:deliveryResponse>
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":"$mobile",
    "email":"me@example.com",
    "voice":"$mobile"
  },
  "responseMessage":{
    "channel":"SMS",
    "acknowledged":"09/01/16 13:22",
    "content":"Yes, I accept. Will I need to bring steel cap boots?"
  }
}

Callbacks allow custom applications to register URLs with Whispir that are used for notifications when certain events occur e.g. a response to a message is received, or a message was undeliverable.



Whispir’s Callback Service will forward the content of each message response, along with some associated metadata to a URL that the user has pre-registered to receive this information.

Some other points to follow -

  1. Always use a domain name for the callback. Do NOT use an IP.
  2. Ensure that your callback server is reachable on the internet. It should not be localhost or an intranet only application that cannot be reached from the WWW.
  3. Limit the port to 80 or 443. Do no use any other ports.
  4. Depending on the type chosen 'json’ or 'xml’ for the Content-Type, whispir would make a similar GET (and subsequently POST) calls. So, please ensure that your your web server is configured to handle such MIME type.
  5. Most importantly, if your application infrastructure is behind a firewall, then make sure that the firewall allows an incoming POST request.

Creating new Callbacks

Creating new Callbacks

The following API calls allow users to create new Callbacks using the Whispir API.

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:companyapicallback xmlns:ns2="http://schemas.api.whispir.com"
                    xmlns:ns3="http://schemas.api.whispir.com/dap">
    <name>Callback Name</name>
    <url>http://myserver.com/mycallback.php</url>
    <auth>
      <key>MY_AUTH_KEY</key>
      <type>querystring</type>
    </auth>
    <contentType>json</contentType>
    <removeHTML>enabled</removeHTML>
    <retriesEnabled>true</retriesEnabled>
    <email>me@example.com</email>
    <callbacks>
      <reply>enabled</reply>
      <undeliverable>enabled</undeliverable>
    </callbacks>
</ns2:companyapicallback>
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"
  }
}

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 an HTTP 201 - Created.

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 Authorization 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 as follows:
  • json
  • xml
removeHTML: String
Specifies whether HTML should be stripped from responses.

The choices are as follows:
  • 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 where failure notifications should be sent.
callbacks: Object
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

Note:

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

Callback Creation Errors

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

400 Malformed Error

This is the common error that you may face when creating a callback. If you get this issue, then check for the following:

  1. Read the error detail in the response body. It will give you the hint on what the issue is - immediately.
  2. Is the callback URL reachable from outside of your intranet?
    Try again one more time from outside of your network.
  3. Is the response for a GET request to the URL a 200?
    Try it in your browser and see what is the status you get in the Network tab of Developer Tools (F12). Or you may use cURL.
    • If the GET request does not receive a 200 response, Whispir will consider the Callback creation request a failure and throws a 400 Malformed Request.
    • The “request” is malformed - in the sense that the URL given is not working and so a bad configuration/malformed detail is given to Whispir.
  4. A callback with the same name already exists in the Whispir under your account.

Callback Authorization

Callback Authorization

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 an HTTP Header. Whispir will add the X-Whispir-Callback-Key Header to the request.

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

HTTP 1.1 POST https://yourserver/callback.php
X-Whispir-Callback-Key: MY_AUTH_TOKEN
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:deliveryResponse xmlns:ns2="http://schemas.api.whispir.com">
    <messageid>ABC4857BCCF484575FCA</messageid>
    <messagelocation>https://api.<region>.whispir.com/messages/ABC4857BCCF484575FCA</messagelocation>
    <from>
      <name>Fred Waters</name>
      <mri>Fred_Waters.528798.Sandbox@Contact.whispir.com</mri>
      <mobile>$mobile</mobile>
      <email>me@example.com</email>
      <voice>$mobile</voice>
    </from>
    <responseMessage>
      <channel>SMS</channel>
      <acknowledged>09/01/16 13:22</acknowledged>
      <content>Yes, I accept. Will I need to bring steel cap boots?</content>
    </responseMessage>
</ns2:deliveryResponse>
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" : "$mobile",
    "email" : "me@example.com",
    "voice" : "$mobile"
  },
  "responseMessage" : {
    "channel" : "SMS",
    "acknowledged" : "09/01/13 13:22",
    "content" : "Yes, I accept. Will I need to bring steel cap boots?"
  }
}

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.

HTTP 1.1 POST https://yourserver/callback.php?auth=MY_AUTH_TOKEN
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:deliveryResponse xmlns:ns2="http://schemas.api.whispir.com">
    <messageid>ABC4857BCCF484575FCA</messageid>
    <messagelocation>https://api.<region>.whispir.com/messages/ABC4857BCCF484575FCA</messagelocation>
    <from>
      <name>Fred Waters</name>
      <mri>Fred_Waters.528798.Sandbox@Contact.whispir.com</mri>
      <mobile>$mobile</mobile>
      <email>me@example.com</email>
      <voice>$mobile</voice>
    </from>
    <responseMessage>
      <channel>SMS</channel>
      <acknowledged>09/01/16 13:22</acknowledged>
      <content>Yes, I accept. Will I need to bring steel cap boots?</content>
    </responseMessage>
</ns2:deliveryResponse>
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" : "$mobile",
    "email" : "me@example.com",
    "voice" : "$mobile"
  },
  "responseMessage" : {
    "channel" : "SMS",
    "acknowledged" : "09/01/13 13:22",
    "content" : "Yes, I accept. Will I need to bring steel cap boots?"
  }
}

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:

The unique token should be an alphanumeric string generated and assigned specifically for Whispir Callbacks.

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

There are two options for the location of this Authorization Token:

1. HTTP Header

Using an HTTP Header for authorisation is the preferred approach. This method will use 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 Authorization will be passed to the callback server on the query string using an 'Auth’ parameter as follows:

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

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 occurring:

Users 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:

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

Retrieving Callbacks

Retrieving Callbacks

The following API Methods allow you to access callbacks via the API

HTTP 1.1 GET https://api.<region>.whispir.com/callbacks?apikey=[your_api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.api-callback-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 3 of 3</status>
    <ns2:callbacks>
        <ns2:callback>
            <id>BCD374DABC73649B</id>
            <name>Sample Callback 1</name>
            <url>http://myserver.com/callback1.php</url>
            <ns2:link uri="https://api.<region>.whispir.com/callbacks/BCD374DABC73649B?apikey=[API_KEY]" rel="self" method="GET"/>
        </ns2:callback>
        <ns2:callback>
            <id>AD34DBCEFD74EABC</id>
            <name>Sample Callback 2</name>
            <url>http://myserver.com/callback2.php</url>
            <ns2:link uri="https://api.<region>.whispir.com/callbacks/AD34DBCEFD74EABC?apikey=[API_KEY]" rel="self" method="GET"/>
        </ns2:callback>
        <ns2:callback>
            <id>73BDCEFA43DF35DB</id>
            <name>Sample Callback 3</name>
            <url>http://myserver.com/callback3.php</url>
            <ns2:link uri="https://api.<region>.whispir.com/callbacks/73BDCEFA43DF35DB?apikey=[API_KEY]" rel="self" method="GET"/>
        </ns2:callback>
    </ns2:callbacks>
</ns2:return>

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

{
  "status" : "1 to 3 of 3",
  "callbacks" : [ {
    "id" : "BCD374DABC73649B",
    "name" : "Sample Callback 1",
    "url" : "http://myserver.com/callback1.php",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/callbacks/BCD374DABC73649B?apikey=[API_KEY]",
      "rel" : "self",
      "method" : "GET"
    } ]
  },{
    "id" : "AD34DBCEFD74EABC",
    "name" : "Sample Callback 2",
    "url" : "http://myserver.com/callback2.php",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/callbacks/AD34DBCEFD74EABC?apikey=[API_KEY]",
      "rel" : "self",
      "method" : "GET"
    } ]
  },{
    "id" : "73BDCEFA43DF35DB",
    "name" : "Sample Callback 3",
    "url" : "http://myserver.com/callback3.php",
    "link" : [ {
      "uri" : "https://api.<region>.whispir.com/callbacks/73BDCEFA43DF35DB?apikey=[API_KEY]",
      "rel" : "self",
      "method" : "GET"
    } ]
  }, ],
  "link" : [ ]
}

To retrieve a list of callbacks from the Whispir API you can execute an HTTP GET using the /callbacks endpoint.

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

An array of Callbacks will be returned to you in the HTTP response body.

Each of these Callbacks will provide the following information:

Response Elements
id: String
The unique ID of the callback within Whispir.
name: String
The name given to the Callback at creation time. Also the ID that is used in the `/messages` endpoint.
url: String
The application URL that was given to the Callback at creation time. Also the endpoint that will be used when supplying callback information.
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

Using Callbacks

Using Callbacks

Callbacks can be added to messages by adding the callbackId parameter and the name of the callback as follows:

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.message-v1+json

{
   "to" : "$mobile",
   "subject" : "Test SMS Message",
   "body" : "This is the body of my test SMS message",
   "callbackId" : "Sample Callback 1"
}
Content-Type: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test SMS Message</subject>
    <body>This is the body of my test SMS message</body>
    <callbackId>Sample Callback 1</callbackId>
</ns2:message>

Callbacks can be added to messages by simply specifying the callback name within the request to the /messages endpoint.

Any responses to the above sent message will be forwarded back to the URL within the Callback named Sample Callback 1.

Handling Callback Failures

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.<region>.whispir.com/messages/ABC4857BCCF484575FCA
Name: Fred Waters
Mobile: $mobile
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 will be 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.

In the event the provided callback URL could not be reached or the connection to the service times out, Whispir will automatically generate a notification to the nominated email address with the details of the failed attempt.

Whispir will automatically send an email in the following circumstances:

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 will mark the callback server as down and log the attempted callback as Failed.

This callback will be attempted to be retried after ~5 minutes. If the server is available, the callbacks will automatically be processed through the server, the user doesn’t need to take any further action.

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

Retrieving attempted calls to a callback endpoint

The following API Methods allow you to access callback attempts via the API

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+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
  <status>1 to 1 of 1</status>
  <ns2:call>
    <id>B3EDFE83DF389DFE</id>
    <messageId>ABC4857BCCF484575FCA</messageId>
    <messageLocation>https://api.<region>.whispir.com/messages/ABC4857BCCF484575FCA</messageLocation>
    <status>FAILED</status>
    <from>
      <voice></voice>
      <mri>Fred_Waters.528798.Sandbox@Contact.whispir.com</mri>
      <name>Fred Waters</name>
      <mobile>$mobile</mobile>
      <email></email>
    </from>
    <responseMessage>
      <acknowledged>09/01/13 13:22</acknowledged>
      <channel>SMS</channel>
      <content>Yes, I accept. Will I need to bring steel cap boots?</content>
    </responseMessage>
    <callback>
      <name>My Callback Server</name>
      <attemptedDate>09/01/13 13:22</attemptedDate>
      <id>B384FD38DCBADE38</id>
      <url>https://www.myapplication.com/myapp</url>
      <statusMessage>Internal Server Error</statusMessage>
      <statusCode>500</statusCode>
    </callback>
    <link>
      <uri>/callbacks/B384FD38DCBADE38/calls/B3EDFE83DF389DFE</uri>
      <rel>updateCall</rel>
      <method>PUT</method>
    </link>
  </ns2:call>
  <ns2:link>
    <uri>/callbacks/B384FD38DCBADE38/calls?offset=20&amp;limit=20</uri>
    <rel>next</rel>
    <method>GET</method>
  </ns2:link>
</ns2:return>

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": "$mobile",
        "email": "",
        "voice": ""
      },
      "responseMessage": {
        "channel": "SMS",
        "acknowledged": "09/01/13 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/13 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"
  }]
}

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

An array of calls will be returned to you in the HTTP response body.

Each of these calls will provide 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 as follows:
  • name (string): The name of the sender of this message.
  • mri (string): The unique identifier for this contact within Whispir.
  • mobile (string): The mobile number associated to this sender.
  • voice (string): The phone number associated to the voice channel for this sender.
  • email (string): The email address associated to the email channel for this sender.
responseMessage: Object
The details about this particular message that has 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 as follows:
  • id (string): The ID of the callback that was attempted to be invoked.
  • name (string): The name of the callback server that was attempted to be invoked.
  • url (string): The url of the callback server that was attempted 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

Retrieve based on Status

Failed Calls

HTTP 1.1 GET https://api.<region>.whispir.com/callbacks/BCD374DABC73649B/calls?apikey=[your_api_key]&status=FAILED
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

Success Calls

HTTP 1.1 GET https://api.<region>.whispir.com/callbacks/BCD374DABC73649B/calls?apikey=[your_api_key]&status=SUCCESS
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

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

To specifically retrieve the FAILED/SUCCESS calls, one 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 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, that these calls will then need to be updated to reflect the current status.

Take the following example:

  1. 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 24h, 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’.

This process can be facilitated with the use of a PUT request to the /calls endpoint in Whispir.

Updating the status of the calls within the /calls endpoint

The following API Methods allow you to update callback attempts via the API

HTTP 1.1 PUT https://api.<region>.whispir.com/callbacks/BCD374DABC73649B/calls?apikey=[YOUR_API_KEY]&id=YOUR_CALL_ID
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.api-call-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:call xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
  <status>SUCCESS</status>
</ns2:call>

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

{
  "status": "SUCCESS"
}

The expected response code for this process is 204 - No Content.

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

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

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

Users 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

Callback Parameters

Callback Parameters within a Callback Response

a single callback parameter

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" : "$mobile",
   "subject" : "Test SMS",
   "body" : "This is the SMS",
   "callbackId" : "Sample Callback 1",
   "callbackParameters" : {
      "CustomID" : "890h0ef0fe09efw90e0jsdj0"
   }
}

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test SMS</subject>
    <body>This is the SMS</body>
    <callbackId>Sample Callback 1</callbackId>
    <callbackParameters>
      <entry>
        <key>CustomId</key>
        <value>890h0ef0fe09efw90e0jsdj0</value>
      </entry>
    </callbackParameters>
</ns2:message>

multiple callback parameters

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" : "$mobile",
   "subject" : "Test SMS",
   "body" : "This is the SMS",
   "callbackId" : "This is my callback",
   "callbackParameters" : {
      "CustomID" : "890h0ef0fe09efw90e0jsdj0",
      "CustomID2" : "9ef0fe09efw90e0jsdjsd43fw"
   }
}

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Test SMS</subject>
    <body>This is the SMS</body>
    <callbackId>Sample Callback 1</callbackId>
    <callbackParameters>
      <entry>
        <key>CustomId</key>
        <value>890h0ef0fe09efw90e0jsdj0</value>
      </entry>
      <entry>
        <key>CustomId2</key>
        <value>9ef0fe09efw90e0jsdjsd43fw</value>
      </entry>
    </callbackParameters>
</ns2:message>

The callback API allows you to pass in any values (parameters), which you want to be returned as is - included in the callback response.

To explain this in a simple scenario driven terms;

then

then

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

Whispir shall take note of these callback parameters, and when the response is returned via the callback URI, these parameters are included into 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 as: - in JSON as

{ Key : Value }

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

If there are more than one set of values, the data shall be set as:

{ Key : Value }, { Key : Value }

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

Receiving them in Response

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/13 13:22",
           "content":"Yes, I accept. Will I need to bring steel cap boots?"
    },
    "customParameters" : {
        "CustomerId" : "890h0ef0fe09efw90e0jsdj0",
        "TransactionId" : "9ef0fe09efw90e0jsdjsd43fw",
        ...
    }
}
Content-Type: application/xml

<ns2:deliveryResponse xmlns:ns2="http://schemas.api.whispir.com">
  <messageid>ABC4857BCCF484575FCA</messageid>
  <messagelocation>https://api.<region>.whispir.com/messages/ABC4857BCCF484575FCA</messagelocation>
  <from>
      <name>Fred Waters</name>
      <mri>Fred_Waters.528798.Sandbox@Contact.whispir.com</mri>
      <mobile>$mobile</mobile>
      <email>me@example.com</email>
      <voice>$mobile</voice>
  </from>
  <responseMessage>
      <channel>SMS</channel>
      <acknowledged>09/01/13 13:22</acknowledged>
      <content>Yes, I accept. Will I need to bring steel cap boots?</content>
  </responseMessage>
  <customParameters>
    <entry>
      <key>CustomerId</key>
      <value>890h0ef0fe09efw90e0jsdj0</value>
    </entry>
    <entry>
      <key>TransactionId</key>
      <value>9ef0fe09efw90e0jsdjsd43fw</value>
    </entry>
    ...
  </customParameters>
</ns2:deliveryResponse>

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 shall be part of customParameters object. The response does not contain the callbackParameters object. The naming convention could be a bit confusing at times, but the naming convention is kept from logical premise.

Note:

Custom Parameters

Custom Parameters are different from callbackParameters. To make it clear again -

This is important, so you may read that again now, or have a coffee and read it in 10 mins. I needed a chocolate to get that going. ;)

Custom Parameters are included in the response object of a callback POST that Whispir makes to your server. These parameters contain important information about

In Detail -

Whispir allows bulk messaging or dynamic messaging via the /resources and /messages endpoint. When you use that, you would need to know the processed values that are used by Whispir to replace the @@placeholders@@ used in that specific message template against each row of your csv, json, xml data.

To facilitate that Whispir gives those values in the callback response under customParameters. The list of custom Parameters provided by Whispir are -

"customParameters": {
  "sender_full_name": "John Wick",
  "sender_first_name": "John",
  "sender_last_name": "Wick",
  "sender_sms": "614235552323",
  "sender_email": "JohnWick@example.com",
  "recipient_full_name": "John Wick",
  "recipient_first_name": "John",
  "recipient_last_name": "Wick",
  "recipient_sms": "6593556682",
  "recipient_email": "jWick@whispir.com",
  "recipient_voice": "6593556682",
  "date": "2016-03-04",
  "time": "10:36",
  "yyyy": "2016",
  "month": "March",
  "day": "Friday",
  "yy": "16",
  "mm": "03",
  "dd": "04",
  "hrs": "10",
  "min": "36",
  "sec": "01",
  "matchedCategory": "Reserved",
  "responseRule": "Reserved Words",
  "first_name": "John",
  "last_name": "Wick"
}

<customParameters>
    <entry>
      <key>sender_full_name</key>
      <value>John Wick</value>
    </entry>
    <entry>
      <key>sender_first_name</key>
      <value>John</value>
    </entry>
    <entry>
      <key>sender_last_name</key>
      <value>Wick</value>
    </entry>
    <entry>
      <key>sender_sms</key>
      <value>614235552323</value>
    </entry>
    <entry>
      <key>sender_email</key>
      <value>JohnWick@example.com</value>
    </entry>
    <entry>
      <key>recipient_full_name</key>
      <value>John Wick</value>
    </entry>
    <entry>
      <key>recipient_first_name</key>
      <value>John</value>
    </entry>
    <entry>
      <key>recipient_last_name</key>
      <value>Wick</value>
    </entry>
    <entry>
      <key>recipient_sms</key>
      <value>6593556682</value>
    </entry>
    <entry>
      <key>recipient_email</key>
      <value>jWick@whispir.com</value>
    </entry>
    <entry>
      <key>recipient_voice</key>
      <value>6593556682</value>
    </entry>
    <entry>
      <key>date</key>
      <value>2016-03-04</value>
    </entry>
    <entry>
      <key>time</key>
      <value>10:36</value>
    </entry>
    <entry>
      <key>yyyy</key>
      <value>2016</value>
    </entry>
    <entry>
      <key>month</key>
      <value>March</value>
    </entry>
    <entry>
      <key>day</key>
      <value>Friday</value>
    </entry>
    <entry>
      <key>yy</key>
      <value>16</value>
    </entry>
    <entry>
      <key>mm</key>
      <value>03</value>
    </entry>
    <entry>
      <key>dd</key>
      <value>04</value>
    </entry>
    <entry>
      <key>hrs</key>
      <value>10</value>
    </entry>
    <entry>
      <key>min</key>
      <value>36</value>
    </entry>
    <entry>
      <key>sec</key>
      <value>01</value>
    </entry>
    <entry>
      <key>matchedCategory</key>
      <value>Reserved</value>
    </entry>
    <entry>
      <key>responseRule</key>
      <value>Reserved Words</value>
    </entry>
    <entry>
      <key>first_name</key>
      <value>John</value>
    </entry>
    <entry>
      <key>last_name</key>
      <value>Wick</value>
    </entry>
</customParameters>
High-Level Custom Parameters
sender_full_name: String
Specifies the full name of the sender. This is the name of the user account that was used to make the API call.
sender_first_name: String
Specifies the first name of the sender account.
sender_last_name: String
Specifies the last name of the sender account.
sender_sms: String
Specifies the phone number of the sender account.
sender_email: String
Specifies the email address of the sender. This is email address of the user account that was used to make the API call.
recipient_full_name: String
Specifies the full name of the recipient. If only the recipient is already a contact/user in the Whispir Platform under your account.
recipient_first_name: String
Specifies the first name of the recipient account. If only the recipient is already a contact/user in the Whispir Platform under your account.
recipient_last_name: String
Specifies the last name of the recipient account. If only the recipient is already a contact/user in the Whispir Platform under your account.
recipient_sms: String
Specifies the phone number of the recipient. If only the channel is SMS or the recipient is already a contact/user in the Whispir Platform under your account.
recipient_email: String
Specifies the email address of the recipient. If only the channel is EMAIL or the recipient is already a contact/user in the Whispir Platform under your account
recipient_voice: String
Specifies the phone number of the recipient. If only the channel is SMS/Voice or the recipient is already a contact/user in the Whispir Platform under your account
date: String
Specifies the date value in YYYY-MM-DD format.

Ex. 2016-03-04.

This is the date when the message was sent. This helps to know the sent date when the message is a SCHEDULED message
time: String
Specifies the time value in HH:MI format.

Ex. 10:36.

This is the time when the message was sent. This helps to know the sent time when the message is a SCHEDULED message
Individual broken-down values for Date and Time: String
Apart from the date and time values above, the API also provides broken down values for use.

  • yyyy - year (in 4 digit format) Eg. 2016
  • month - month (in full month name format) Eg. March
  • day - day (in full week day format) Eg. Tuesday

  • yy - year (in 2 digit format) Eg. 16
  • mm - month Eg. 03
  • dd - date Eg. 08
  • hrs - hours Eg. 16
  • min - minutes Eg. 39
  • sec - seconds Eg. 50

Example Flow

Imagine a workflow where the same user gets more than 1 message in a quick time frame, how does whispir know “to which message did this user respond to ?”.

Explanation -

{
  "to": "$mobile",
  "subject": "Whispir",
  "body": "Hello there. Reply Y",
  "callbackId": "callbackA"
}

{
  "to": "$mobile",
  "subject": "Whispir",
  "body": "Goodbye. Reply Y",
  "callbackId": "callbackB"
}

Scenario 1:

Assuming in a span of 10 seconds, these 2 SMSes were sent

If user $mobile replies “Y”, which callbackId would be called ?

Scenario 2:

SMS sent:

{
  "to": "$mobile",
  "subject": "Whispir",
  "body": "Hello there. Reply Y",
  "callbackId": "callbackA"
}

Another SMS sent half hour later (#scenario 2):

{
  "to": "$mobile",
  "subject": "Whispir",
  "body": "Goodbye. Reply Y",
  "callbackId": "callbackB"
}

If user $mobile replies “Y”, which callbackId would be called?

Scenario 3:

SMS sent (#scenario 3):

{
  "to": "$mobile",
  "subject": "Whispir",
  "body": "Hello there. Reply Y",
  "callbackId": "callbackA"
}

User $mobile replies “Y” half hour later, would the callbackId still be relevant?

How about 1 hour, 2 hours later?

Apps

Apps serve as the Mobile App definition endpoints, where you one can register their Mobile App at Whispir, and be able to do the push notifications with the help of /messages, /contacts and devices endpoints.

The endpoint serves the need for

API Endpoint

Apps exist at Company level, and are then made available to workspaces. So, there is no workspace-id to be provided in the URL.

https://api.<region>.whispir.com/apps?apikey=<your_api_key>
Content-Type: application/vnd.whispir.app-v1+xml
https://api.<region>.whispir.com/apps?apikey=<your_api_key>
Content-Type: application/vnd.whispir.app-v1+json
> Resource type

- application/vnd.whispir.app-v1+xml
- application/vnd.whispir.app-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

To understand the relationship between your app and Whispir endpoints, refer to this image.



Registering an App

App registration is a one time process, and once created, the app information can be used to register the pushTokens as devices (under contacts), and use the contact mri value to send the push messages to the app.

POST https://api.<region>.whispir.com/apps?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.app-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:app xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <name>My Push App</name>
    <description>Description of the App</description>
    <bundleId>com.your.bundleId</bundleId>
    <options>
        <apiKey>A valid UUID value</apiKey>
        <clientSecret>A valid UUID value without the `-` dashes</clientSecret>
        <deviceLimit>3</deviceLimit>
        <workspaces>46FEEB0398DDCE9A</workspaces>
        <contactDescriptionField>role</contactDescriptionField>
    </options>
    <apns>
        <certificate></certificate>
        <privateKey></privateKey>
    </apns>
    <apnsSandbox>
        <certificate></certificate>
        <privateKey></privateKey>
    </apnsSandbox>
    <defaultWorkspaceEnabled>true</defaultWorkspaceEnabled>
    <gcm>
        <gcmProjectNumber>0</gcmProjectNumber>
        <gcmSenderNumber>0</gcmSenderNumber>
        <gcmApiKey>GCM provided API Key</gcmApiKey>
    </gcm>
    <defaultWorkspaceEnabled>true</defaultWorkspaceEnabled>
    <managedBySystem>false</managedBySystem>
    <registrationTypes>SELF</registrationTypes>
</ns2:app>
Content-Type: application/vnd.whispir.app-v1+json

{
 "name": "string",
 "description": "string",
 "bundleId": "string"
 "options": {
    "apikey": "string",
    "clientSecret": "string",
    "deviceLimit": 0,
    "workspaces": "string",
    "contactDescriptionField": "string"
 },
 "apns": {
    "certificate": "string",
    "privateKey": "string"
 },
 "apnsSandbox": {
    "certificate": "string",
    "privateKey": "string"
 },
 "gcm": {
    "gcmProjectId": "string",
    "gcmSenderNumber": "string",
    "gcmApiKey": "string"
 },
 "defaultWorkspaceEnabled": true,
 "managedBySystem" : true,
 "registrationTypes": [
    "SELF"
 ]
}

The successful response will be a 201 with the details of the app created and its associated unique appID. Also, for security reasons, Whispir will NOT show the APNS certificate information at any time post app creation. The API response will only show the certificateDate so that one can use that to update the certificate upon expiry.

Almost all the fields are mandatory. So, please ensure the information is provided properly.

High-Level Request Elements
name: String
Specifies the name of the application
Required. Alphanumeric. Max length: 32
Sample: My Awesome Application
description: String
The description of the application for display within Whispir and whispir.io
Not Required. Alphanumeric. No max length. Default: “”
Sample: App for sending messages to My Awesome App
bundleId: String
The bundle Id of your application
Required. Alphanumeric. No max length. Default: “”
Sample: com.pushie.whispir
options.apiKey: string
A unique username tied to this app for usage monitoring purposes
Not Required. Alphanumeric. Generated if not provided
Sample: dfsdfsfds09fds-asdf9dsf-asdf9dfsa
options.clientSecret: string
The password tied to the apiKey and used by this app for usage monitoring purposes
Not Required. Alphanumeric. Max length 64 chars. Can use `.` as special character
Sample: dfsdfsfds09fds.lkrt
options.deviceLimit: Numeric
The number of devices that are allowed to be registered under a single contact per app
Not Required. Numeric. Default: 3
Sample: 3
options.workspaces: String
The comma separated list of Workspace IDs that will make this application usable/visible for messages sendout in those workspaces.
Not Required. Alphanumeric. No max length. Default: “”
Sample:
options.contactDescriptionField: String
The field on the contact profile that should be used to distinguish between contacts with the same name within the user list (mobile applications only).
E.g. if you call the /app/users endpoint and receive 3 people named 'John Smith’, how does a user differentiate between them? The contactDescriptionField provides a secondary mechanism to display a 'Role’, 'JobTitle’ or 'BusinessUnit’ to help distinguish between similar contacts.
Not Required. Alphanumeric. No max length. Default: “”.
Note: should reference a Whispir Contact Profile Field.
Sample: jobTitle
apns.certificate: String
The APNS Push Notifications certificate that has downloaded from the iOS developer console
Single line. Alphanumeric. No max length. Default: “”
Sample: —–BEGIN CERTIFICATE—–\nMIIGSjCCBTKgAwIBAgIICdjQ9d41eiYwDQYJKoZIhvcNAQELBQAwgZYxCzAJ…..\n—–END CERTIFICATE—–
IMP: You must ensure that the value is provided in a single line only with the use of `\n` to specify the line breaks just after the BEGIN CERTIFICATE—- and before the —–END CERTIFICATE. If you have .p12, then use any of the valid converter tools to extract the certificate, and private key correctly. An Incorrect value will lead to failure of app creation.
apns.privateKey: String
The APNS Push Notifications private key from the certificate chain that was downloaded from the iOS developer console
Single line. Alphanumeric. No max length. Default: “”
Sample: —–BEGIN PRIVATE KEY—–\nMIIGSjCCBTKgAwIBAgIICdjQ9d41eiYwDQYJKoZIhvcNAQELBQAwgZYxCzAJ…..\n—–END PRIVATE KEY—–
IMP: You must ensure that the value is provided in a single line only with the use of `\n` to specify the line breaks just after the BEGIN PRIVATE KEY—- and before the —–END PRIVATE KEY. An Incorrect value will lead to failure of app creation.
apnsSandbox.certificate: String
The APNS Push Notifications Sandbox certificate that has downloaded from the iOS developer console
Single line. Alphanumeric. No max length. Default: “”
Sample: —–BEGIN CERTIFICATE—–\nMIIGSjCCBTKgAwIBAgIICdjQ9d41eiYwDQYJKoZIhvcNAQELBQAwgZYxCzAJ…..\n—–END CERTIFICATE—–
IMP: You must ensure that the value is provided in a single line only with the use of `\n` to specify the line breaks just after the BEGIN CERTIFICATE—- and before the —–END CERTIFICATE. If you have .p12, then use any of the valid converter tools to extract the certificate, and private key correctly. An Incorrect value will lead to failure of app creation.
apnsSandbox.privateKey: String
The APNS Push Notifications Sandbox private key from the certificate chain that was downloaded from the iOS developer console
Single line. Alphanumeric. No max length. Default: “”
Sample: —–BEGIN PRIVATE KEY—–\nMIIGSjCCBTKgAwIBAgIICdjQ9d41eiYwDQYJKoZIhvcNAQELBQAwgZYxCzAJ…..\n—–END PRIVATE KEY—–
IMP: You must ensure that the value is provided in a single line only with the use of `\n` to specify the line breaks just after the BEGIN PRIVATE KEY—- and before the —–END PRIVATE KEY. An Incorrect value will lead to failure of app creation.
gcm.gcmProjectId: String
The Project ID from the Google Cloud Messaging Console
Alphanumeric. No max length. Default: “”
Sample: My-Sample-Project
gcm.gcmSenderNumber: String
The Sender ID from the Google Cloud Messaging Console
Numeric. No max length. Default: “”
Sample: 1000202045211
gcm.gcmApiKey: String
The GCM API Key from the Google Cloud Messaging Console
AlphaNumeric. No max length. Default: “”
Sample: fcde7ecfdefc6defcfde7faacbd637ca
defaultWorkspaceEnabled: String
Whether or not 'My Company’ should be supported within this application.
Not Required. Boolean. Default: false
Sample: true
managedBySystem: String
Whether or not this application has been automatically created by Whispir (vs created by a user).
Not editable by a user. Generated field.
Sample: N/A
registrationTypes: String
The array of registration types that are supported by this particular application
  • SELF
  • INVITE
SELF: Used for Apps, where Whispir is given the push Token readily by you. This is the common scenario for almost all the apps.
INVITE: Used for Apps, where Whispir’s Mobile SDK is used inside your App, and it captures the push Token upon app Installation, and passes to Whispir for registration of the device.

Updating an App

Updating an exisiting app is done via the PUT request on the /apps/{:aid} endpoint.

Please remember that you do not need to pass on the APNS certificates every time, only do so, if there is a need to update the certificate values.

Updating Apps

The following endpoints allow users to update contact’s devices using the Whispir API.

HTTP 1.1 PUT https://api.<region>.whispir.com/apps/{:aid}?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.app-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:app xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <id>521BBA863C2C230BD0E1BBA86</id>
    <name>My Push App</name>
    <description>Description of the App</description>
    <options>
        <apiKey>A valid UUID value</apiKey>
        <clientSecret>A valid UUID value without the `-` dashes</clientSecret>
        <deviceLimit>3</deviceLimit>
        <workspaces>46FEEB0398DDCE9A</workspaces>
        <contactDescriptionField>jobTitle</contactDescriptionField>
    </options>
    <apns>
        <certificateDate>2017-03-21T00:59:08.930Z</certificateDate>
    </apns>
    <apnsSandbox>
        <certificateDate>2017-03-21T00:59:08.930Z</certificateDate>
    </apnsSandbox>
    <defaultWorkspaceEnabled>true</defaultWorkspaceEnabled>
    <gcm>
        <gcmProjectNumber>0</gcmProjectNumber>
        <gcmSenderNumber>0</gcmSenderNumber>
        <gcmApiKey>GCM provided API Key</gcmApiKey>
    </gcm>
    <defaultWorkspaceEnabled>true</defaultWorkspaceEnabled>
    <managedBySystem>false</managedBySystem>
    <registrationTypes>SELF</registrationTypes>
</ns2:app>
Content-Type: application/vnd.whispir.app-v1+json

{
    "id": "521BBA863C2C230BD0E1BBA86",
    "name": "My Push App",
    "description": "Description of the App",
    "options": {
        "apiKey": "A valid UUID value",
        "deviceLimit": "3",
        "workspaces": "EBDCE9A46FE0398D",
    "contactDescriptionField" : "jobTitle"
    },
    "gcm": {
        "gcmProjectNumber": 0
    },
    "apns": {
        "certificateDate": "2017-03-21T00:59:08.930Z"
    },
    "apnsSandbox": {
        "certificateDate": "2017-03-21T00:59:08.930Z"
    },
    "registrationTypes": [
        "SELF"
    ],
    "managedBySystem": false,
    "defaultWorkspaceEnabled": true,
}

The response to the PUT request upon success is a 204 No Content with no content being provided.

Deleting an App

Deleting an App

The following statement allows users to delete an App using the Whispir API. Please note, this app cannot be recovered back once deleted, and you must also ensure that the devices that are referreing to this App are also promptly either deleted or updated to refer to a new App.

HTTP 1.1 DELETE https://api.<region>.whispir.com/apps/{:aid}?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

Deleting an App can be performed using a DELETE request to the /apps/{:aid} endpoint. So, to perform this, one must be knowing the exact “link” associated with the app.

After performing this request, the response does not contain any information other than the headers as it is not necessary.

The response of 204 No Content is returned, indicating that the app is successfully deleted.

Important Note

The endpoint is purely tied to creation of Apps for push notifications. This endpoint has nothing to do with the Apps that you create in the Whispir.io to get your API Keys.

Scenarios

API Endpoint

  • generic
https://api.<region>.whispir.com/scenarios/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.scenario-v1+xml
https://api.<region>.whispir.com/scenarios/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.scenario-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/scenarios/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.scenario-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/scenarios/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.scenario-v1+json
> Resource type

- application/vnd.whispir.scenario-v1+xml
- application/vnd.whispir.scenario-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

Scenarios allows users to simplify the message delivery processes through automated one click communications. The process involves creating a fixed message Or a message template combined with a contact or a distribution list. When the scenario is executed, the message is sent to the contacts.

Such use cases are widely useful in emergency notification scenarios where time is of essence. Not just messages (text), one can trigger Email, Voice and Social Media posts too suitable for different target audience as part of the scenario process.

Eg: “A fire outbreak evacuation notification with escape path” to all members of the office staff can be done much faster if a ready available message text and the handy distribution list of staff is created as a “Scenario”. A one click approach here shall trigger the evacuation order to all the staff immediately. No time is lost in composing, selecting the contacts etc.

The contacts can be picked as a static distribution list or a rule based dynamic distribution list, or just direct available numbers. This improves the effectiveness of the scenario’s target group reach.

Not just an emergency, but any scenario where a fixed content/Rich Message has to be sent to a pool of contacts, Whispir’s “Scenario” comes very handy.

Creating a new Scenario

Creating Scenario

The following API calls allow users to create Scenarios using the Whispir API.

HTTP 1.1 POST https://api.<region>.whispir.com/scenarios?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.scenario-v1+xml 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:scenario xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <title>Fire Evacuation Block A</title>
    <description>Fire evacuation notification for A block residents</description>
    <message>
        <to>$mobile</to>
        <subject>Fire Evacuation</subject>
        <body>A fire has been detected at level 55. Please evacuate the building immediately. Please do not use the lifts.</body>
    </message>
</ns2:scenario>
Content-Type: application/vnd.whispir.scenario-v1+json

{
    "title" : "Fire Evacuation Block A",
    "description" : "Fire evacuation notification for A block residents",
    "message" : {
        "to" : "$mobile",
        "subject" : "Fire Evacuation",
        "body" : "A fire has been detected at level 55. Please evacuate the building immediately. Please do not use the lifts."
    }
}

This will give a successful response [201] along with the details of newly created scenario.

A scenario is a combination of a message and contacts. So, its structure contains section for both message as well as contact information. API currently only supports creation of scenario with SMS as communication mode.

To create a scenario, you can use the /scenarios endpoint.

The following fields are required:

  1. name - name of the scenario
  2. description - details of the scenario
  3. message { to, subject, body }
High-Level Request Elements
name: String
Specifies the name of the scenario
description: String
Specifies the description of the scenario
allowedUsers: String
Specifies the usage permission -
  • EVERYONE
  • SELECTEDUSERS

When SELECTEDUSERS is provided, then `allowedUserIds` shall contain the userID of the allowed users.
allowedUserIds: String
Specifies the comma separated list of users who can run this scenario.
Only contains value when the allowedUsers is set to `SELECTEDUSERS`
message: Object
Specifies the messaging options
to: String
Specifies the phone number or mri or distribution list to which the message has to be sent
subject: String
Specifies the subject of the message
body: String
Specifies the body of the message
label: String
Specifies the label for the message (to view during reporting)
email: Object
Email message that can be sent as part of this scenario
  • body: The main content of the email
  • footer: footer of the email
  • type: text/plain or text/html
voice: Object
Similar to a text message, a voice call can also be triggered. This provides the necessary information for the channel.
  • header: header for message. This will be played before the subject
  • body: The main content of the message
  • footer: footer for the message. Played after the body. Usually contains a thank you note.
  • type: ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:
web: Object
Refer to web messaging. The web message structure remains exactly the same
social: Object
Refer to web messaging The social message structure remains exactly the same

Retrieving Scenarios

Retrieving Scenario

The following API calls allow users to retrieve scenarios using the Whispir API.

HTTP 1.1 GET https://api.<region>.whispir.com/scenarios?apikey=[your_api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.scenario-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 2 of 2</status>
    <ns2:scenarios>
        <ns2:scenario>
            <title>Emergency Comms - Fire</title>
            <description>Scenario to use during fire evacuation</description>
            <createdTime>2015-07-20T17:18:58+08:00</createdTime>
            <ns2:link uri="https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:scenario>
        <ns2:scenario>
            <title>Scenario X</title>
            <description>This is a scenario where a scenario is created</description>
            <createdTime>2015-07-20T17:19:41+08:00</createdTime>
            <ns2:link uri="https://api.<region>.whispir.com/scenarios/6EE7F6F2E48B73B4?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:scenario>
    </ns2:scenarios>
</ns2:return>
Accept: application/vnd.whispir.scenario-v1+json

{
  "scenarios": [
    {
      "title": "Emergency Comms - Fire",
      "description": "Scenario to use during fire evacuation",
      "createdTime": 1437383938000,
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "title": "Scenario X",
      "description": "This is a scenario where a scenario is created",
      "createdTime": 1437383981000,
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/scenarios/6EE7F6F2E48B73B4?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    }],
  "status": "1 to 2 of 2",
  "link": []
}

To retrieve a list of scenarios from the Whispir.io API you can execute an HTTP GET using the /scenarios endpoint.

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

An array of Scenarios will be returned to you in the HTTP response body.

Each of these scenarios will provide the following information:

Response Elements
name: String
Specifies the name of the scenario.
description: String
Specifies the broad description of the scenario.
createdTime: Number
Specifies the scenario created time value in Epoch
link: Array
Provides a list of URLs that can be used to manipulate or access the scenario.
  • uri - the link to access the scenario
  • rel - the descriptor for what the link will do
  • method - the HTTP method to use with this particular link

While that specifies the master list, doing a GET on a single scenario provides the following information -

Retrieving details of a single Scenario

Retrieving a single scenario details needs the ID of the scenario

HTTP 1.1 GET https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.scenario-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:scenario xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <title>Emergency Comms - Fire</title>
    <description>Scenario to use during fire evacuation</description>
    <createdTime>2015-07-20T17:18:58+08:00</createdTime>
    <allowedUsers>EVERYONE</allowedUsers>
    <message>
        <to>$mobile</to>
        <subject>Scenario Emergency Comms - Fire</subject>
        <body>sms test</body>
        <label></label>
        <voice/>
        <from>joe.bloggs.company@Contact.Melbourne.whispir.au</from>
        <social>
            <social id="socialType">
                <body>text/plain</body>
            </social>
        </social>
        <createdTime>2015-07-22T20:48:31+08:00</createdTime>
    </message>
    <ns3:link uri="https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]" rel="self" method="GET"/>
    <ns3:link uri="https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]" rel="updateScenario" method="PUT" type="application/vnd.whispir.scenario-v1+json,application/vnd.whispir.scenario-v1+xml"/>
    <ns3:link uri="https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]" rel="deleteScenario" method="DELETE" type="application/vnd.whispir.scenario-v1+json,application/vnd.whispir.scenario-v1+xml"/>
</ns2:scenario>
Accept: application/vnd.whispir.scenario-v1+json

{
  "title": "Emergency Comms - Fire",
  "description": "Scenario to use during fire evacuation",
  "createdTime": 1437383938000,
  "allowedUsers": "EVERYONE",
  "message": {
    "to": "$mobile",
    "subject": "Scenario Emergency Comms - Fire",
    "body": "sms test",
    "label": "",
    "voice": {},
    "from": "joe.bloggs.company@Contact.Melbourne.whispir.au",
    "social": {
      "social": [
        {
          "id": "socialType",
          "body": "text/plain"
        }
      ]
    },
    "createdTime": 1437569311000,
  },
  "link": [
    {
      "uri": "https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]",
      "rel": "self",
      "method": "GET"
    },
    {
      "uri": "https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]",
      "rel": "updateScenario",
      "method": "PUT",
      "type": "application/vnd.whispir.scenario-v1+json,application/vnd.whispir.scenario-v1+xml"
    },
    {
      "uri": "https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]",
      "rel": "deleteScenario",
      "method": "DELETE",
      "type": "application/vnd.whispir.scenario-v1+json,application/vnd.whispir.scenario-v1+xml"
    }
  ]
}
Response Elements
name: String
Specifies the name of the scenario
description: String
Specifies the description of the scenario
createdTime: Number
Specifies the scenario created time value in Epoch
allowedUsers: String
Specifies the usage permission -
  • EVERYONE
  • SELECTEDUSERS

When SELECTEDUSERS is provided, then `allowedUserIds` shall contain the userID of the allowed users.
allowedUserIds: String
Specifies the comma separated list of users who can run this scenario.
Only contains value when the allowedUsers is set to `SELECTEDUSERS`
message: Object
Specifies the messaging options
to: String
Specifies the phone number or mri or distribution list to which the message has to be sent
subject: String
Specifies the subject of the message
body: String
Specifies the body of the message
label: String
Specifies the label for the message (to view during reporting)
email: Object
Email message that can be sent as part of this scenario
  • body: The main content of the email
  • footer: footer of the email
  • type: text/plain or text/html
voice: Object
Similar to a text message, a voice call can also be triggered. This provides the necessary information for the channel.
  • header: header for message. This will be played before the subject
  • body: The main content of the message
  • footer: footer for the message. Played after the body. Usually contains a thank you note.
  • type: ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:
web: Object
Refer to web messaging. The web message structure remains exactly the same
social: Object
Refer to web messaging The social message structure remains exactly the same
from: String
The user/contact from whom this communication will be sent out when the scenario is run.
Eg: joe.bloggs.company@Contact.Melbourne.whispir.au
link: Array
Provides a list of URLs that can be used to manipulate or access the scenario.
  • uri - the link to access the scenario
  • rel - the descriptor for what the link will do
  • method - the HTTP method to use with this particular link

Running a Scenario

Running a Scenario

A simple POST call to the scenarios endpoint with the scenario ID triggers the scenario execution

HTTP 1.1 POST https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

> > The expected response to this call is an HTTP 204 - No Content.

Running a Scenario , in other words, invoking a scenario triggers the communication to the intended recipients. The message (static or dynamic) will be sent on all the provided channels.

Running a scenario is very simple to do. The specific scenario has to called via a /POST request.

Step wise example -

  1. Get all the scenarios
  2. Pick the required scenario’s link attribute
  3. Make a /POST call

From the retrieving scenarios call above, we can get all the scenarios in the workspace. Choosing the Emergency Comms - Fire named Scenario, the link provided is https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]

Now invoking this scenario is just making a /POST call. There is no need for a Content-type header as the payload is empty.

Updating Scenario

To update existing scenario, you can use a PUT request the /scenarios endpoint.

Updating a Scenario

The following API calls allow users to update Scenarios using the Whispir API.

HTTP 1.1 PUT https://api.<region>.whispir.com/scenarios/F0547F6F2E4839F8?apikey=[your_api_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.scenario-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:scenario xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <title>Emergency Comms - Fire</title>
    <description>Scenario to use during fire evacuation</description>
    <allowedUsers>EVERYONE</allowedUsers>
    <message>
        <to>$mobile</to>
        <subject>Scenario Emergency Comms - Fire</subject>
        <body>Evacuate the building Immediately. Do not use the lifts.</body>
        <label></label>
        <voice/>
        <from>joe.bloggs.company@Contact.Melbourne.whispir.au</from>
        <social>
            <social id="socialType">
                <body>text/plain</body>
            </social>
        </social>
    </message>
</ns2:scenario>
Accept: application/vnd.whispir.scenario-v1+json

{
  "title": "Emergency Comms - Fire",
  "description": "Scenario to use during fire evacuation",
  "allowedUsers": "EVERYONE",
  "message": {
    "to": "$mobile",
    "subject": "Scenario Emergency Comms - Fire",
    "body": "Evacuate the building Immediately. Do not use the lifts.",
    "label": "",
    "voice": {},
    "from": "joe.bloggs.company@Contact.Melbourne.whispir.au",
    "social": {
      "social": [
        {
          "id": "socialType",
          "body": "text/plain"
        }
      ]
    }
  }
}

The following fields are required:

  1. name - name of the scenario
  2. description - details of the scenario
  3. message { to, subject, body }
High-Level Request Elements
name: String
Specifies the name of the scenario
description: String
Specifies the description of the scenario
createdTime: Number
Specifies the scenario created time value in Epoch
allowedUsers: String
Specifies the usage permission -
  • EVERYONE
  • SELECTEDUSERS

When SELECTEDUSERS is provided, then `allowedUserIds` shall contain the userID of the allowed users.
allowedUserIds: String
Specifies the comma separated list of users who can run this scenario.
Only contains value when the allowedUsers is set to `SELECTEDUSERS`
message: Object
Specifies the messaging options
to: String
Specifies the phone number or mri or distribution list to which the message has to be sent
subject: String
Specifies the subject of the message
body: String
Specifies the body of the message
label: String
Specifies the label for the message (to view during reporting)
email: Object
Email message that can be sent as part of this scenario
  • body: The main content of the email
  • footer: footer of the email
  • type: text/plain or text/html
voice: Object
Similar to a text message, a voice call can also be triggered. This provides the necessary information for the channel.
  • header: header for message. This will be played before the subject
  • body: The main content of the message
  • footer: footer for the message. Played after the body. Usually contains a thank you note.
  • type: ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:
web: Object
Refer to web messaging. The web message structure remains exactly the same
social: Object
Refer to web messaging The social message structure remains exactly the same
from: String
The user/contact from whom this communication will be sent out when the scenario is run.
Eg: joe.bloggs.company@Contact.Melbourne.whispir.au

Deleting Scenario

Deleting a Scenario

The following API calls allow users to delete Scenarios using the Whispir API.

HTTP 1.1 DELETE https://api.<region>.whispir.com/scenarios/6EE7F6F2E48B73B4?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

> > The expected response to this call is an HTTP 204 - No Content.

Deleting a Scenario can be done via a DELETE call to the /scenarios endpoint. The request has to be targeted at a particular Scenario with the Scenario ID in the URI.

Activities

API Endpoint

  • generic
https://api.<region>.whispir.com/activities/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.activity-v1+xml
https://api.<region>.whispir.com/activities/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.activity-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/activities/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.activity-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/activities/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.activity-v1+json
> Resource type

- application/vnd.whispir.activity-v1+xml
- application/vnd.whispir.activity-v1+json


> Methods supported

- GET
- POST

Activities are all the individual changes, tasks, calls, messages.. just about everything performed in a given company workspaces. Each Activity log entry contains information about the workspace, the module(message, email, IVR..), the user who performed it, time stamps, description of the activity, and its status (success, fail) etc.

All of these helps in fulfilling the auditing, standards compliance and also change tracking. For example -

As activities information is sensitive, stricter permission rules apply to the data served by these endpoints. - Any API user will be able to perform a GET on /activities - If the user is a Company Admin or Company Leader, they will receive a 200 OK with the valid response - If the user is a Company Member or Company Guest, they will receive a 403 Forbidden advising they don’t have permission to access this resource - Company Admin or Company Leader can also create content within the Activity Stream. They can do this through a POST of data to either the /activities endpoint, or to the specific Activity ID. - They must specify a valid ‘Action’, 'Description’ and 'Status’ within their request - Posting to the /activities endpoint will create a new activity - Posting to the /activities/ {ID} endpoint will append the content to the detail of the specified activity

Creating an activity log

HTTP 1.1 POST https://api.<region>.whispir.com/activities?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.activity-v1+xml


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:activity xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <module>Message</module>
    <action>Send</action>
    <status>Successful</status>
    <description>Message sent via the Whispir's Java library</description>
</ns3:activity>
Content-Type: application/vnd.whispir.activity-v1+json

{
  "module": "Message",
  "action" : "Send",
  "status" : "Successful",
  "description" : "Message sent via the Whispir's Java library"
}
> Response will be `201 Created`

To create a new workspace, you can use the /activities endpoint.

Only 3 fields are required:

  1. module - The name of the module in which the activity is performed (see the high-level request elements table below for list of modules).
  2. action - The action performed.
  3. status - The status of the action.

Note: There is no limit to the amount of activities that can be created.

High-Level Request Elements
action : String
Specifies the action performed during this activity. The following are the list of actions that can be performed -
  • Create
  • Update
  • Move
  • Copy
  • Draft
  • Send
  • Modified
  • Delete
  • Contact Import File
  • Login
  • Approve
  • Reject
  • Dispatch
  • Register
  • Accept
  • Closed
  • Map
  • Un-map
module: String
Specifies the module to which this activity belongs to. The following are the list of actions that can be performed -
  • System
  • Message
  • Scheduled Message
  • User
  • Contact
  • DistributionList
  • Template
  • Workspace
  • Event
  • WebService
  • Settings
  • Conversation
  • Gateway
  • Workspace Mapping
  • Folders
  • Team
  • RSS
  • API Mapping
  • Asset
  • Instruction
workspace: String
The workspace in which this activity is performed. This will usually be the API user’s default workspace
user: String
The username of the person who performed this activity. This will usually be the API user invoking the creation.
status: String
Specifies the status of the activity. The status can be one of -
  • Successful
  • Failed
  • Rejected
description: String
The description of the activity. This is a free text that details about the activity.

Note: If this is not provided during the creation of the activity, this field will not exist for the specific activity. As updating an activity is not allowed, care has to be taken to ensure that absence of this field is justified as per your audit - compliance needs.
time: String
The date and time of the activity in the format: dd/mm/yy hh:mm. This will be defaulted to the time at which this activity is created.

Retrieving Activities

To retrieve a list of activities from the Whispir.io API you can execute an HTTP GET using the /activities endpoint.

HTTP 1.1 GET https://api.<region>.whispir.com/activities?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Accept: application/vnd.whispir.activity-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <ns2:activities>
        <ns2:activity>
            <user>james.cameron</user>
            <time>17/08/15 13:29</time>
            <action>Send</action>
            <description>Message sent via the Whispir's Java library</description>
            <status>Successful</status>
            <module>Message</module>
            <workspaceName>Whispir</workspaceName>
            <ns2:link uri="https://api.<region>.whispir.com/activities/9B26BCE6A7C1997D3E3C04D4C0B62165?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:activity>
        <ns2:activity>
            <user>james.cameron</user>
            <time>17/08/15 12:56</time>
            <action>Create</action>
            <status>Successful</status>
            <module>Workspace</module>
            <workspaceName>Whispir</workspaceName>
            <ns2:link uri="https://api.<region>.whispir.com/activities/CF8F388F18FDDA7CA40F42E888EC8E67?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:activity>
        <ns2:activity>
            <user>james.cameron</user>
            <time>17/08/15 12:26</time>
            <action>Draft</action>
            <description>Template for default notification messages</description>
            <status>Successful</status>
            <module>Template</module>
            <workspaceName>Whispir</workspaceName>
            <ns2:link uri="https://api.<region>.whispir.com/activities/19F603F21E8A7D536D577A6B4DBCFE3F?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:activity>
    <ns2:activity>
            <user>markm</user>
            <time>22/12/14 11:37</time>
            <action>Logout</action>
            <description>Logged out</description>
            <status>Successful</status>
            <module>System</module>
            <workspaceName>ABC Operations</workspaceName>
            <ns2:link uri="http://app19.dev1.whispir.net:8080/api/activities/0DEB48AB3D3B6069D7DA1A808F5A5DE4?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:activity>
        <ns2:activity>
            <user>markm</user>
            <time>22/12/14 11:20</time>
            <action>Login</action>
            <description> Logged in, IP:127.0.0.1, Country: </description>
            <status>Successful</status>
            <module>System</module>
            <workspaceName>ABC Operations</workspaceName>
            <ns2:link uri="http://app19.dev1.whispir.net:8080/api/activities/0CEC8009230B3B92F5B548A22B55C407?apikey=[your_api_key]" rel="self" method="GET"/>
        </ns2:activity>
    </ns2:activities>
</ns2:return>
Accept: application/vnd.whispir.activity-v1+json

{
  "activities": [
    {
      "user": "james.cameron",
      "time": "17/08/15 13:29",
      "action": "Send",
      "description": "Message sent via the Whispir's Java library",
      "status": "Successful",
      "module": "Message",
      "workspaceName": "Whispir",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/activities/9B26BCE6A7C1997D3E3C04D4C0B62165?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "user": "james.cameron",
      "time": "17/08/15 12:56",
      "action": "Create",
      "status": "Successful",
      "module": "Workspace",
      "workspaceName": "Whispir",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/activities/CF8F388F18FDDA7CA40F42E888EC8E67?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "user": "james.cameron",
      "time": "17/08/15 12:26",
      "action": "Draft",
      "description": "Template for default notification messages",
      "status": "Successful",
      "module": "Template",
      "workspaceName": "Whispir",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/activities/19F603F21E8A7D536D577A6B4DBCFE3F?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
  {
      "user": "markm",
      "time": "22/12/14 11:37",
      "action": "Logout",
      "description": "Loged out",
      "status": "Successful",
      "module": "System",
      "workspaceName": "ABC Operations",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/activities/0DEB48AB3D3B6069D7DA1A808F5A5DE4?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
  {
      "user": "markm",
      "time": "22/12/14 11:20",
      "action": "Login",
      "description": "Logged in, IP:8.8.8.8, Country: USA",
      "status": "Successful",
      "module": "System",
      "workspaceName": "ABC Operations",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/activities/0CEC8009230B3B92F5B548A22B55C407?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "link": []
}

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

An array of activities will be returned to you in the HTTP response body.

Each of these activities will provide the following information:

High-Level Response Elements
action : String
Specifies the action performed during this activity.
module: String
Specifies the module to which this activity belongs to.
workspace: String
The workspace in which this activity is performed.
user: String
The username of the person who performed this activity.
status: String
Specifies the status of the activity. The status can be one of -
  • Successful
  • Failed
  • Rejected
description: String
The description of the activity.
time: String
The date and time of the activity in the format: dd/mm/yy hh:mm.
link: Array
Provides a list of URLs that can be used to manipulate or access the activity.
  • uri - the link to access the activity
  • rel - the descriptor for what the link will do
  • method - the HTTP method to use with this particular link

Note: The API currently results in a 404 Not Found when there are no activities present in the log for a given search criteria. This should not be not confused with a failed response. But rather as No Data Found.

Restricting to only a single workspace

HTTP 1.1 GET https://api.<region>.whispir.com/activities?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
HTTP 1.1 GET https://api.<region>.whispir.com/workspace/B7BFEF555F0F7F81/activities?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

By default, GET /activities returns all the activities at company level. This covers all the workspaces. So, if the items has to limited to a specific workspace, one has to use the workspace as the endpoint and activities followed by it.

Request Information
Request Description
/activities Only returns activity that took place in My Company
/workspaces/:id/activities Only returns activity that took place in the specified workspace

Search or Filter on Activity Logs

Activity logs can become quickly huge owing to the amount of actions performed. In such cases, to have a proper filtering of data during a GET /activities, Whispir API provides very neat filtering options on the data.

HTTP 1.1 GET https://api.<region>.whispir.com/activities?apikey=[your_api_key]&field=value
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

All filter options are to be passed in as URL query parameters.

Search Criteria
action : /activities?action=Map
module: /activities?module=Message
user: /activities?user=james
workspace: /activities?workspace=Whispir.

One can also refer to restricting to only a workspace section above
status: /activities?status=Successful
description: /activities?description=Imported
Start time: The date and time to start searching from in the format: dd/mm/yyyy hh:mm. This will search on the `time` field

/activities?startTime=01/01/2015%2000:00
End time: The date and time to start searching from in the format: dd/mm/yyyy hh:mm

/activities?endTime=01/01/2015%2000:00

Note: The API currently results in a 404 Not Found when there are no activities present in the log for a given search criteria. This should not be not confused with a failed response. But rather as No Data Found.

Updating, Deleting an activity

Activities can only be created and retrieved. They cannot be updated or deleted.

Custom Lists

API Endpoint

  • generic
https://api.<region>.whispir.com/customlists/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.customlist-v1+xml
https://api.<region>.whispir.com/customlists/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.customlist-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/customlists/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.customlist-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/customlists/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.customlist-v1+json
> Resource type

- application/vnd.whispir.customlist-v1+xml
- application/vnd.whispir.customlist-v1+json


> Methods supported

- GET

Custom Lists are user specific translations or preferred options in the various list controls used in the platform tool. These provide the freedom for the user to customize the list options in various modules like Messages, Events. These custom list either can complement or completely overwrite the existing list items.

A quick example -

In the Events, You have a “Priority” field that the user has to fill to specify the priority of the attention. The default ones are -

If this is not the standard for the company, the values can be changed to suit your needs. This is where custom lists come in to help. Just Create a custom list and via company settings set the custom list to override the existing list. When this is done, the user using the interface shall only see the new custom list values in place of the standard list.These custom lists can be associated to message attributes, event fields, contact fields.

Translations within Voice Module -

The custom lists can also be used to do translations during the Voice Module usage. During the call, options can be read out in various languages depending on the user preference of language. In this case, the standard list is replaced with a custom list that is merely a translation in the target language word to word. Instead of the English, the specific language words are read out, making it easier to communicate with end customers from multiple language groups.

Permission Rules applicable on the Custom Lists -

CONTENT (type) -

The customlists will contain all lists in the company across the following places - RSS Custom Lists - Incident Custom Lists (Events/Assets) - Message Attribute Custom Lists - Contact Custom Lists - Message Custom Lists

Retrieving custom lists

HTTP 1.1 GET https://api.<region>.whispir.com/customlists?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Accept: application/vnd.whispir.customlist-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 5 of 5</status>
    <ns2:customlabels>
        <ns2:customlabel>
            <id>4E2101D0E5D16229</id>
            <name>Category</name>
            <type>INCIDENT</type>
            <createdDate>02/08/11 14:20</createdDate>
            <sortType>As Displayed</sortType>
            <linked>disabled</linked>
            <ns2:link uri="https://api.<region>.whispir.com/customlists/40E5D16229E2101D?apikey=7qyxe7z37tsdy9spv6sw6uec" rel="self" method="GET"/>
        </ns2:customlabel>
        <ns2:customlabel>
            <id>0CA7B9E2B21A3B1A</id>
            <name>Day of Month</name>
            <type>MESSAGE</type>
            <createdDate>13/10/14 16:30</createdDate>
            <sortType>As Displayed</sortType>
            <linked>disabled</linked>
            <ns2:link uri="https://api.<region>.whispir.com/customlists/0CA7B9E2B21A3B1A?apikey=7qyxe7z37tsdy9spv6sw6uec" rel="self" method="GET"/>
        </ns2:customlabel>
        <ns2:customlabel>
            <id>87F23964C25ECF22</id>
            <name>Day of Week</name>
            <type>MESSAGE</type>
            <createdDate>07/01/14 09:51</createdDate>
            <sortType>As Displayed</sortType>
            <linked>disabled</linked>
            <ns2:link uri="https://api.<region>.whispir.com/customlists/87F23964C25ECF22?apikey=7qyxe7z37tsdy9spv6sw6uec" rel="self" method="GET"/>
        </ns2:customlabel>
        <ns2:customlabel>
            <id>F0771B97F1EF770B</id>
            <name>External Vendor</name>
            <type>INCIDENT</type>
            <createdDate>02/08/11 14:20</createdDate>
            <sortType>As Displayed</sortType>
            <linked>disabled</linked>
            <ns2:link uri="https://api.<region>.whispir.com/customlists/F0771B97F1EF770B?apikey=7qyxe7z37tsdy9spv6sw6uec" rel="self" method="GET"/>
        </ns2:customlabel>
        <ns2:customlabel>
            <id>768E4ACA5DA7500C</id>
            <name>Finish Time</name>
            <type>MESSAGE</type>
            <createdDate>01/08/11 12:38</createdDate>
            <sortType>As Displayed</sortType>
            <linked>disabled</linked>
            <ns2:link uri="https://api.<region>.whispir.com/customlists/768E4ACA5DA7500C?apikey=7qyxe7z37tsdy9spv6sw6uec" rel="self" method="GET"/>
        </ns2:customlabel>
    </ns2:customlabels>
</ns2:return>
Accept: application/vnd.whispir.customlist-v1+json

{
  "status": "1 to 5 of 5",
  "customlabels": [
    {
      "id": "4E2101D0E5D16229",
      "name": "Category",
      "type": "INCIDENT",
      "createdDate": "02/08/11 14:20",
      "sortType": "As Displayed",
      "linked": "disabled",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/customlists/40E5D16229E2101D?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "0CA7B9E2B21A3B1A",
      "name": "Day of Month",
      "type": "MESSAGE",
      "createdDate": "13/10/14 16:30",
      "sortType": "As Displayed",
      "linked": "disabled",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/customlists/0CA7B9E2B21A3B1A?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "87F23964C25ECF22",
      "name": "Day of Week",
      "type": "MESSAGE",
      "createdDate": "07/01/14 09:51",
      "sortType": "As Displayed",
      "linked": "disabled",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/customlists/87F23964C25ECF22?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "F0771B97F1EF770B",
      "name": "External Vendor",
      "type": "INCIDENT",
      "createdDate": "02/08/11 14:20",
      "sortType": "As Displayed",
      "linked": "disabled",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/customlists/F0771B97F1EF770B?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "768E4ACA5DA7500C",
      "name": "Finish Time",
      "type": "MESSAGE",
      "createdDate": "01/08/11 12:38",
      "sortType": "As Displayed",
      "linked": "disabled",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/customlists/768E4ACA5DA7500C?apikey=[your_api_key]",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "link": []
}

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

An array of Custom Lists will be returned to you in the HTTP response body.

High-Level Response Elements
id: Number
Specifies the unique id of the List.
name: String
Specifies the name of the List.
type: String
Specifies the type. The type can be one of -
  • INCIDENT
  • MESSAGE
  • CONTACT
  • RSS
sorttype: String
Specifies the sorting order. The order can be one of -
  • As Displayed
  • Ascending
  • Descending
linked: String
Specifies the linked status. Linked list item values are dependent on other lists. The linked can be one of -
  • disabled
  • list id to which this is linked with
link: Array
Provides a list of URLs that can be used to manipulate or access the list.
  • uri - the link to access the list
  • rel - the descriptor for what the link will do
  • method - the HTTP method to use with this particular link

Details of a Specific Custom List

HTTP 1.1 GET https://api.<region>.whispir.com/customlists/4E2101D0E5D16229?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Accept: application/vnd.whispir.customlist-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:customlabel xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <id>4E2101D0E5D16229</id>
    <name>Category</name>
    <type>INCIDENT</type>
    <createdDate>02/08/11 14:20</createdDate>
    <sortType>As Displayed</sortType>
    <linked>disabled</linked>
    <customlabellists>
        <customlabellist>
            <name>Internal Systems</name>
            <value>Internal Systems</value>
        </customlabellist>
        <customlabellist>
            <name>External Systems</name>
            <value>External Systems</value>
        </customlabellist>
        <customlabellist>
            <name>Infrastructure</name>
            <value>Infrastructure</value>
        </customlabellist>
    </customlabellists>
    <ns3:link uri="https://api.<region>.whispir.com/customlists/40E5D16229E2101D?apikey=7qyxe7z37tsdy9spv6sw6uec" rel="self" method="GET"/>
</ns2:customlabel>
Accept: application/vnd.whispir.customlist-v1+json

{
  "id": "4E2101D0E5D16229",
  "name": "Category",
  "type": "INCIDENT",
  "createdDate": "02/08/11 14:20",
  "sortType": "As Displayed",
  "linked": "disabled",
  "customlabellists": [
    {
      "name": "Internal Systems",
      "value": "Internal Systems"
    },
    {
      "name": "External Systems",
      "value": "External Systems"
    },
    {
      "name": "Infrastructure",
      "value": "Infrastructure"
    }
  ],
  "link": [
    {
      "uri": "https://api.<region>.whispir.com/customlists/40E5D16229E2101D?apikey=7qyxe7z37tsdy9spv6sw6uec",
      "rel": "self",
      "method": "GET"
    }
  ]
}

To retrieve the details of a specific list, the end point must be passed with the custom list ID. The link can be usually found in the link attribute of each customlist item.

High-Level Response Elements
id: Number
Specifies the unique id of the List.
name: String
Specifies the name of the List.
type: String
Specifies the type. The type can be one of -
  • INCIDENT
  • MESSAGE
  • CONTACT
  • RSS
createdDate: String
Specifies the date of the List creation.
sorttype: String
Specifies the sorting order. The order can be one of -
  • As Displayed
  • Ascending
  • Descending
linked: String
Specifies the linked status. Linked list item values are dependent on other lists. The linked can be one of -
  • disabled
  • list id to which this is linked with
customlabellists: Object
Contains the individual list items that make up this list.

The `name` is the text that is shown to the user, where as the `value` is the internally passed in value.
link: Array
Provides a list of URLs that can be used to manipulate or access the list.
  • uri - the link to access the list
  • rel - the descriptor for what the link will do
  • method - the HTTP method to use with this particular link

Search or Filter on Custom Lists

API allows you to be able to query the GET /customlists endpoint using the following filters.

HTTP 1.1 GET https://api.<region>.whispir.com/customlists?apikey=[your_api_key]&field=value
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

All filter options are to be passed in as URL query parameters.

Search Criteria
name: /customlists?name=Category
type: /customlists?type=Message

Note: The API currently results in a 404 Not Found when there are no activities present in the log for a given search criteria. This should not be not confused with a failed response. But rather as No Data Found.

Creating, Updating, and Deleting a custom list

API currently only supports retrieving the custom lists. It does not support the creation, update, and delete of the custom list.

Users

API Endpoint

  • generic
https://api.<region>.whispir.com/users/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.user-v1+xml
https://api.<region>.whispir.com/users/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.user-v1+json
> Resource type

- application/vnd.whispir.user-v1+xml
- application/vnd.whispir.user-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

Access to use the Whispir API, Platform and its features is strictly limited to user permission set. One needs to have proper permissions to access all the features provided by the platform, and when using the API, have appropriate permissions to modify the user attributes of themselves or others in their company workspaces.

Invalid Permission Error

If the API user account does not have the permissions needed to operate on an user account, the API will give a 403 Forbidden response. So make sure the account has all the necessary permissions. Use Whispir Platform Environment URL given in the whispir.io apps screen to login and manage the permissions

The Whispir API provides the /users endpoint to serve the purpose of managing the users of the platform. One can - Retrieve users of a workspace - Add new users - Modify user status (except their own) - Modify user’s information - Delete user

An User ability to access the features is limited to the STATUS he/she is assigned to. They can have only one status at any given point of time and the change of status is controlled by the “user state machine”. The state machine follows the following tabulated rules -

User Status
PENDING (P) User has been just created and this is the default status one will be given.
Status can be modified to -
  • INACTIVE
  • DELETED
INACTIVE (I) User has been set to Inactive Status. During this state they CANNOT access the platform until they are set to Active again.
Status can be modified to -
  • ACTIVE
  • DELETED

Note: If you are the user who is changing your status, beware that setting yourself to InActive results you in being locked out of your own account. Always use another account in your company to change your account status. Have a beer to get this slide down your throat. I did too.
SUSPENDED (B) User has been Suspended. In this State they can access the platform, but cannot use the features on the platform
Status can be modified to -
  • ACTIVE
  • DELETED
DELETED (D) User has been Deleted. This is Soft delete, so their record exists, but they are marked as deleted.
Status cannot be modified once set to Deleted.
ACTIVE (A) User is Active. They can use all the features (they are assigned/allowed to) on the platform.
Status can be modified to -
  • SUSPENDED
  • DELETED

So for example -

If an user has been newly created, the default status is PENDING (P). Now, to Activate the user, the User must be set to INACTIVE first via a PUT request and then finally set to ACTIVE (A) via another PUT. They cannot be directly set to (A) from (P).

Creating new User

Creating new User

Users can easily be created by using the following request structure

POST https://api.<region>.whispir.com/users?apikey=[your api key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.user-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:user xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <firstName>John</firstName>
    <lastName>Wick</lastName>
    <userName>John.Wick</userName>
    <password>AmF10gt_x</password>
    <timezone>Australia/Melbourne</timezone>
    <workEmailAddress1>jsmith@testcompany.com</workEmailAddress1>
    <workMobilePhone1>61423456789</workMobilePhone1>
    <workCountry>Australia</workCountry>
</ns2:user>
Content-Type: application/vnd.whispir.user-v1+json

{
    "firstName": "John",
    "lastName": "Wick",
    "userName": "John.Wick",
    "password": "AmF10gt_x",
    "timezone": "Australia/Melbourne",
    "workEmailAddress1": "jwick@testcompany.com",
    "workMobilePhone1": "61423456789",
    "workCountry": "Australia"
}

The successful response will be a 201 with the details of the user created and their associated unique mri.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:user xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <userName>John.Wick</userName>
    <password></password>
    <status>PENDING</status>
    <firstName>John</firstName>
    <lastName>Wick</lastName>
    <personalEmailAddress2></personalEmailAddress2>
    <personalCountry>Australia</personalCountry>
    <workEmailAddress1>jwick@testcompany.com</workEmailAddress1>
    <workMobilePhone1>61423456789</workMobilePhone1>
    <workCountry>Australia</workCountry>
    <workPostalCountry>Australia</workPostalCountry>
    <timezone>Australia/Melbourne</timezone>
    <ns2:link uri="https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=[your api key]" rel="self" method="GET"/>
    <ns2:link uri="https://api.<region>.whispir.com/users?apikey=[your api key]" rel="updateUser" method="PUT" type="application/vnd.whispir.user-v1+xml,application/vnd.whispir.user-v1+json"/>
    <ns2:link uri="https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=[your api key]" rel="deleteUser" method="DELETE"/>
</ns3:user>

{
  "userName": "John.Wick",
  "password": "",
  "status": "PENDING",
  "firstName": "John",
  "lastName": "Wick",
  "personalEmailAddress2": "",
  "personalCountry": "Australia",
  "workEmailAddress1": "jwick@testcompany.com",
  "workMobilePhone1": "61423456789",
  "workCountry": "Australia",
  "workPostalCountry": "Australia",
  "timezone": "Australia/Melbourne",
  "link": [
    {
      "uri": "https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=[your api key]",
      "rel": "self",
      "method": "GET"
    },
    {
      "uri": "https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=[your api key]",
      "rel": "updateUser",
      "method": "PUT",
      "type": "application/vnd.whispir.user-v1+xml,application/vnd.whispir.user-v1+json"
    },
    {
      "uri": "https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=[your api key]",
      "rel": "deleteUser",
      "method": "DELETE"
    }
  ]
}

To create a new user, you can use the /users endpoint. The method is POST. Ensure that the necessary permissions are provided to the API account to create or modify user accounts.

When creating an account, the following fields are mandatory:

High-Level Request Elements
userName: String
Specifies the username for the account
password: String
Specifies the password for the account
Note: The following are the rules for the password:
  • Alpha Numeric [a-zA-Z0-9_]
  • Must have at least one uppercase and one lowercase character
  • Minimum Length is 8 Characters
  • Any special characters other than `_` (underscore) cannot be used in the passwords
firstName: String
Specifies the firstName of the user
middleName: String
Specifies the middleName of the user
lastName: String
Specifies the lastName of the user
title: String
The title of the name
nickname: String
Preferred name to be shown in the platfom interface
status: String
Specifies the validity status of the user. The status can be one of -
  • Active (A)
  • InActive (I)
  • Pending (P)
  • Suspended (B)
  • Deleted (D)
Note: The default status is PENDING. One cannot set the status while creation of account. Read `User State Machine` again mentioned above.
companyName: String
Specifies the company name
jobTitle: String
Specifies the job title at the company
division: String
Specifies the Division in the company to which this user is associated with
department: String
Specifies the Department in the company to which this user is associated with
Teams and Roles: String
Specifies the primary and Secondary values for each respective variable
  • teamName1, teamName2
  • role1, role2
Work Place Address: String
Specifies the primary and Secondary values for each respective type. Of all these the workEmailAddress1 is the mandatory field.
  • workEmailAddress1, workEmailAddress2
  • workAddress1, workAddress2
  • workSuburb, workState
  • workPostCode, workCountry
  • workPostalAddress1, workPostalAddress2
  • workPostalSuburb, workPostalState
  • workPostalPostCode, workPostalCountry
Work Place Phones: Number
Specifies the primary and Secondary values for each respective type. Of all these the workMobilePhone1 is the mandatory field.
  • workMobilePhone1, workMobilePhone2
  • workPhoneAreaCode1, workPhone1
  • workPhoneAreaCode2, workPhone2
  • workFaxAreaCode1, workFax1
  • workSetellitePhone, WorkOtherPhone
timezone: String
Specifies the timezone in which the user lives in. Values in relation to GMT.

Supported values are:
  • Offset from GMT in the format `+/-NN` e.g. `+10`
  • Worldwide Timezone Format in the format `Country/City` e.g. `Australia/Melbourne`
For a list of available worldwide timezones, click here.
Personal Address: String
Specifies the primary and Secondary values for each respective type
  • personalEmailAddress1, personalEmailAddress2
  • personalAddress1, personalAddress2
  • personalSuburb, personalState
  • personalCountry, personalPostCode
Personal Phones: Number
Specifies the primary and Secondary values for each respective type
  • personalPhoneAreaCode1, personalPhone1
  • personalPhoneAreaCode2, personalPhone2
  • personalFaxAreaCode1, personalFax1
  • otherPhoneAreaCode1, otherPhone1
  • otherMobile
Alias Fields: String
The other (alias) name and title fields
  • otherFirstName, otherLastName, otherTitle

Retrieving Users

Retrieving a list of Users

Users can easily be retrieved from the Whispir API using the following endpoints:

HTTP 1.1 GET https://api.<region>.whispir.com/users?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.user-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 1 of 1</status>
    <ns2:Users>
        <ns2:user>
            <id>AF48A9EC3F02E43C</id>
            <firstName>Fred</firstName>
            <lastName>Smith</lastName>
            <companyName>Whispir Pte Ltd</companyName>
            <workEmailAddress1>fsmith@testcompany.com</workEmailAddress1>
            <workMobilePhone1>61423456789</workMobilePhone1> 
            <ns2:link method="GET" 
                      rel="self" 
                      uri="http://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=<your_api_key>"/>
        </ns2:user>

        ...

    </ns2:Users>
</ns2:return>
Accept: application/vnd.whispir.user-v1+json

{
  "status": "1 to 1 of 1",
  "Users": [
    {
      "id": "AF48A9EC3F02E43C",
      "firstName": "Fred",
      "lastName": "Smith",
      "companyName": "Whispir Pte Ltd",
      "workEmailAddress1": "fsmith@testcompany.com",
      "workMobilePhone1": "61423456789",
      "link": {
        "method": "GET",
        "rel": "self",
        "uri": "http://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=<your_api_key>"
      }
    },

    ...

  ]
}

Users can be retrieved quite easily with a GET request to the /users. A simple /users will result in all users being retrieved with all of their basic identity information. The result will only be limited to users with ACTIVE status. User’s with other status will not be listed in the results.

Once the request is placed, the response will be a list of url’s to each of the users that the API user has access to/or has requested for via the search criteria.

Note: The sample request here shows users from the company the existing API user is associated with. You cannot retrieve users list from outside of your company and users with status != ACTIVE.

Get a specific user

Retrieving a specific user

Users can retrieve a specific user by supplying the user ID in the URL.

HTTP 1.1 GET https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.user-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:user xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
   <id>AF48A9EC3F02E43C</id>
   <firstName>Fred</firstName>
   <lastName>Smith</lastName>
   <status>ACTIVE</status>
   ... remaining of the user object
   <ns2:link method="GET" 
             rel="self" 
             uri="http://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=<your_api_key>"/>
</ns2:user>
Accept: application/vnd.whispir.user-v1+json

{
   "id": "AF48A9EC3F02E43C",
   "firstName": "Fred",
   "lastName": "Smith",
   "status": "ACTIVE",
   ... remaining of the user object
   "link": {
     "method": "GET",
     "rel": "self",
     "uri": "http://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=<your_api_key>"
   }
}

To get details of a specific user, the URI must be passed with the ID of the user. So, the URI shall be: https://api.<region>.whispir.com/users/AF48A9EC3F02E43C Where AF48A9EC3F02E43C is the user id.

Retrieving workspace users

Retrieving list of users having access on a workspace

HTTP 1.1 GET https://api.<region>.whispir.com/workspaces/C727BCE3A813E2B1/users/?apiKey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.user-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 20 of 28</status>
    <ns2:link uri="https://api.<region>.whispir.com/workspaces/C727BCE3A813E2B1/users/?apikey=<your_api_key>&offset=20&limit=20" rel="next" method="GET"/>
    <ns2:users>
        <ns2:user>
            <id>AF48A9EC3F02E43C</id>
            <firstName>Fred</firstName>
            <lastName>Smith</lastName>
            <companyName>Whispir Pte Ltd</companyName>
            <workEmailAddress1>fsmith@whispir.com</workEmailAddress1>
            <workMobilePhone1>6512348765</workMobilePhone1>
            <ns2:link uri="https://api.<region>.whispir.com/workspaces/C727BCE3A813E2B1/users/AF48A9EC3F02E43C?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:user>
        <ns2:user>
            <id>DFC878BCB2EF9258</id>
            <firstName>John</firstName>
            <lastName>Wick</lastName>
            <companyName>SHIELD</companyName>
            <workEmailAddress1>jwick@whispir.com</workEmailAddress1>
            <ns2:link uri="https://api.<region>.whispir.com/workspaces/C727BCE3A813E2B1/users/DFC878BCB2EF9258?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:user>

        ...

    </ns2:users>
</ns2:return>
Accept: application/vnd.whispir.user-v1+json

{
  "users": [
    {
      "id": "AF48A9EC3F02E43C",
      "firstName": "Fred",
      "lastName": "Smith",
      "companyName": "Whispir Pte Ltd",
      "workEmailAddress1": "fsmith@whispir.com",
      "workMobilePhone1": "6512348765",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/workspaces/C727BCE3A813E2B1/users/AF48A9EC3F02E43C?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "DFC878BCB2EF9258",
      "firstName": "John",
      "lastName": "Wick",
      "companyName": "",
      "workEmailAddress1": "jwick@whispir.com",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/workspaces/C727BCE3A813E2B1/users/DFC878BCB2EF9258?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    },

    ...

    "status": "1 to 20 of 28",
    "link": [
    {
      "uri": "https://api.<region>.whispir.com/workspaces/C727BCE3A813E2B1/users/?apikey=<your_api_key>&offset=10&limit=10",
      "rel": "next",
      "method": "GET"
    }
  ]
}

To retrieve the list of users, the request is made to via GET to /workspaces/{:id}/users endpoint.

By default there will be a limit of 20 users returned in a request.

The user will use the limit and offset query parameters to determine how many users they would like to receive. (default when not provided will be limit=20 & offset=0)

Searching for users

Searching for users

Users can easily use further query parameters to search for specific users within Whispir.

HTTP 1.1 GET https://api.<region>.whispir.com/users?apikey=<your_api_key>&firstName=Sam&sortOrder=desc&sortFields=workEmailAddressPrimary
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Accept: application/vnd.whispir.user-v1+xml
Accept: application/vnd.whispir.user-v1+json

Users can be searched for in a given company by passing in valid search criteria. The search criteria usually can be any of the following user elements (field names) and will be sent in as part of the URI as query parameters.

This searching mechanism can be useful to see if any users exist in the system with a specific email address, phone number, or job role and so on.

The key parameters that are required on the URL to facilitate this search are as follows:

URI Request Elements as Query Params
fieldname: String
Specifies on this field name of the user object.

Ex:
http://api..whispir.com/users?apikey=&firstName=Sam
sortOrder: String
The order in which you require the results to be returned. Either `asc` or `desc`.
sortFields: String
The fields that you require the ordering to be performed on. Multiple fields can be provided, separated by a comma.

Ex:
http://api..whispir.com/users?apikey=&firstName=Sam&sortFields=lastName,jobTitle

Note: While searching for users via status, use the short code ‘A’ for ACTIVE, similarly, 'I’ for INACTIVE, rather than the full words ACTIVE, INACTIVE, etc. so, it is &status=A not &status=ACTIVE.

Updating users

Updating users

The following endpoints allow users to update users using the Whispir API.

HTTP 1.1 PUT https://api.<region>.whispir.com/users/CB4558257DD86D09?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key
Content-Type: application/vnd.whispir.user-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:user xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <firstName>John</firstName>
    <lastName>Wick</lastName>
    <timeZone>+8</timezone>
    <jobTitle></jobTitle>

    ... remaining of the user object
</ns2:user>
Content-Type: application/vnd.whispir.user-v1+json

{
    "firstName": "John",
    "lastName": "Wick",
    "timeZone": "+8",
    "jobTitle": "Whispir API Specialist",

    ... remaining of the user object
}

The response to the PUT request upon success is a 204 No Content with no content being provided.

Updating a user can be performed using a PUT request to the /users/{id} endpoint. So, to perform this, one must be knowing the exact “link” associated with the user.

The application must provide all the fields during the update request, even if they are not being updated.

Any missing fields,except for the password field, will be automatically removed from the existing record.

The Content-Type can be -

Note: You cannot selectively update the user fields needed as this is a PUT request.

So the standard process for updating a user record is -

  1. GET /users/{id of user}
  2. Update the user field in the object to the required value
  3. PUT /users/{id of user} the new object

The response to the PUT request upon success is usually a 204 with no content being provided.

Deleting an user

An User can be deleted by calling the DELETE /users/{id} end point.

Deleting a user

The following statement allows users to delete users using the Whispir API.

HTTP 1.1 DELETE https://api.<region>.whispir.com/users/124F6B2D46A5A268?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

Deleting an user can be performed using a DELETE request to the /users/{id} endpoint. So, to perform this, one must be knowing the exact “link” associated with the user.

After performing this request, the response does not contain any information other than the headers as it is not necessary.

The delete a user if successful shall respond with a 204 No Content.

Deleting multiple users

All users in the company can be deleted with a single API call.

Deleting all users

The following statement allows a user to delete all users in their company using the Whispir API.

HTTP 1.1 DELETE https://api.<region>.whispir.com/users/?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

Deleting an user can be performed using a DELETE request to the /users/{id} endpoint. So, to perform this, one must be knowing the exact “link” associated with the user.

After performing this request, the response does not contain any information other than the headers as it is not necessary.

The delete a user if successful shall respond with a 204 No Content.

Activating an User after the creation

Activating an newly created user using the “user state machine” rules

The following steps have to followed in exact order.

Step 1

HTTP 1.1 POST https://api.<region>.whispir.com/users?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

{user object}

capture the Location header value

Step 2

HTTP 1.1 GET https://api.<region>.whispir.com/users/{:id}?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

This step retreives the newly created user object

Step 3

HTTP 1.1 PUT https://api.<region>.whispir.com/users/{:id}?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

{userobject}
status : 'INACTIVE'

Step 4

HTTP 1.1 PUT https://api.<region>.whispir.com/users/{:id}?apikey=<your_api_key>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

{userobject}
status : 'ACTIVE'

An user when created is assigned the PENDING status. SO, to set the user to ACTIVE, one has to follow the “user state machine” rules. Here’s how we do it -

  1. POST /users for user account creation. Capture the Location header value which is the unique link to the User record. This is used in Step 2
  2. GET /users/{id} for the user object
  3. PUT /users/{id} with STATUS set to 'INACTIVE’ - using the user object retreived in step 2
  4. PUT /users/{id} with STATUS set to 'ACTIVE’ - using the user object retreived in step 2

Note: The status text is case sensitive. Lowercase or mixed case text is invalid. Always use uppercase.

Ex: active != ACTIVE; inActive != INACTIVE

Assigning an user to workspace

This is currently not supported via the API right now. One can only do this via the Whispir Platform interface.

Events

API Endpoint

  • generic
https://api.<region>.whispir.com/events/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.event-v1+xml
https://api.<region>.whispir.com/events/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.event-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/events/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.event-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/events/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.event-v1+json
> Resource type

- application/vnd.whispir.event-v1+xml
- application/vnd.whispir.event-v1+json


> Methods supported

- GET
- POST
- PUT
- DELETE

Whispir’s Events API allows users to capture, create and manage Events (including Incidents, Issues, Places, and Assets). Link multi-channel communications to each event to track report and disseminate information textually and Geo-spatially.

The Whispir Events module allows customers to easily input, invoke and track communications about current events that are taking place within their organisation. The Events can be customized to accept events and associated information from external systems or to capture more complex information around an event.

Events can be created from within the Whispir Conversation Platform through the web interface, or via the REST or WSDL APIs. This information is then available for the author to distribute templated messages, or (if location enabled) for other users to view on Whispir’s map interface.

Events within the Whispir Conversation Platform are generally active for a short period of time, most commonly defined by a Start Date and an End Date. Once the end date of the event is reached the event is deemed closed.

Whispir Consultants work with each customer to design and build an events module that is specific to them, ensuring that the fields, applicable values, and captured information maps directly to the organisational process.

An example of an event could be an outage of an internal system or service, or an organisation wide event e.g. a media launch, a network outage or an incident (bush fires, a river flooding)

Creating an Event

As Whispir works with each organisation to build out the requirements of the events module, the required fields are minimal. The bulk of the event information is from fields that are generic, and only applicable to the customer that is using the module.

Events have sub sections under them called as ‘actions’ (maximum of 10). When an Event occurs/is triggered, the related actions are to be performed. Each action has an owner, a set time, and details associated with it. The owner or responsible person for the event could be a /contacts in the system. This ensures that proper communication is sent to the individual based on their preferred channel (message, email, voice) automatically without having to key in the phone, email, and other communication information again.

The Events module captures information specific to an event so the information can be used in as part of messaging for the duration of the event. The Events module can be customized to accept events and associated information from external systems or to capture more complex information around an event.

Events are created within a workspace. As they are custom built the information to be captured will depend on your organisations specific requirements. Generally at a minimum an event will have a label, start date, and a status.

Most importantly, to create an event, one must have the create access for Incident row in the Roles & Permission section of the account settings.

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://schemas.api.whispir.com/dap" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="link">
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base="xs:string">
          <xs:attribute type="xs:string" name="method"/>
          <xs:attribute type="xs:string" name="rel"/>
          <xs:attribute type="xs:anyURI" name="uri"/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>
  <xs:element name="eventLabel" type="xs:string"/>
  <xs:element name="status" type="xs:string"/>
  <xs:element name="eventFormList">
    <xs:complexType>
      <xs:sequence>
        <xs:element type="xs:string" name="formName"/>
        <xs:element name="eventFieldList" maxOccurs="unbounded" minOccurs="0">
          <xs:complexType>
            <xs:sequence>
              <xs:element type="xs:string" name="name"/>
              <xs:element type="xs:string" name="value" minOccurs="0"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Required Fields:

and one set of Actions for this event

All other fields on the event are defined through name/value pairs. E.g.

Optional Fields:

You can refer to the schema for a detail of the object structure.

Creating an event

Event can easily be created by using the following request structure

HTTP1.1 POST https://api.<region>.whispir.com/events?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.event-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:event
    xmlns:ns2="http://schemas.api.whispir.com/dap"
    xmlns:ns3="http://schemas.api.whispir.com">
    <eventLabel>2701095 - Outage of Local Systems in Sydney</eventLabel>
    <status>Open</status>
    <eventFormList>
        <formName>MetroEvent</formName>
        <eventFieldList>
            <name>summary</name>
            <value>Outage of systems in Sydney</value>
        </eventFieldList>
        <eventFieldList>
            <name>status</name>
            <value>Open</value>
        </eventFieldList>
        <eventFieldList>
            <name>description</name>
            <value>ATMs are non responsive, teams to be sent to investigate.</value>
        </eventFieldList>
        <eventFieldList>
            <name>type</name>
            <value>Notification</value>
        </eventFieldList>
        <eventFieldList>
            <name>category</name>
            <value>Internal</value>
        </eventFieldList>
        <eventFieldList>
            <name>startDate</name>
            <value>26/05/2015 17:51:00</value>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner1</name>
            <value>John Wick</value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate1/name>
            <value>11/09/2015 17:51:00</value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails1</name>
            <value>investigation to take place asap.</value>
        </eventFieldList>
        <eventFieldList>
            <name>severity</name>
            <value>Severity 3 - Minor Outage (Some Service Degradation)</value>
        </eventFieldList>
    </eventFormList>
</ns3:event>
Content-Type: application/vnd.whispir.event-v1+json

{
    "eventLabel" : "2701095 - Outage of Local Systems in Sydney",
    "status" : "Open",
    "eventFormList" : [ {
        "formName" : "MetroEvent",
        "eventFieldList" : [ 
            {
              "name" : "summary",
              "value" : "Outage of systems in Sydney"
            }, {
              "name" : "status",
              "value" : "Open"
            }, {
              "name" : "description",
              "value" : "ATMs are non responsive, teams to be sent to investigate."
            }, {
              "name" : "category",
              "value" : "Internal"
            }, {
              "name" : "startDate",
              "value" : "11/09/2015 17:41:00"
            }, {
              "name" : "actionOwner1",
              "value" : "John Wick"
            }, {
              "name" : "actionDate1",
              "value" : "11/09/2015 17:41:00"
            }, {
              "name" : "actionDetails1",
              "value" : "investigation to take place asap."
            }, {
              "name" : "severity",
              "value" : "Severity 3 - Minor Outage (Some Service Degradation)"
            } 
        ]
    } ]
}

The request if successful shall return a 201 Created along with the complete event object.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:event xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <id>421FEEBA93GF53A2</id>
    <eventLabel>2701095 - Outage of Local Systems in Sydney</eventLabel>
    <status>Open</status>
    <eventFormList>
        <eventFieldList>
            <name>summary</name>
            <value>Outage of systems in Sydney</value>
        </eventFieldList>
        <eventFieldList>
            <name>location</name>
            <value>0.0,0.0</value>
        </eventFieldList>
        <eventFieldList>
            <name>endDate</name>
        </eventFieldList>
        <eventFieldList>
            <name>type</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails2</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails3</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails1</name>
            <value>investigation to take place asap.</value>
        </eventFieldList>
        <eventFieldList>
            <name>priority</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>description</name>
            <value>ATMs are non responsive, teams to be sent to investigate.</value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails8</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails9</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails6</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails7</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails4</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner10</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails5</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>platform</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>services</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>status</name>
            <value>Open</value>
        </eventFieldList>
        <eventFieldList>
            <name>openedBy</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>category</name>
            <value>Internal</value>
        </eventFieldList>
        <eventFieldList>
            <name>externalVendor</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>externalCaseNumber</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner6</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>startDate</name>
            <value>11/09/2015 00:00:00</value>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner5</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner8</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner7</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner9</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate8</name>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate9</name>
        </eventFieldList>
        <eventFieldList>
            <name>actionDetails10</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate4</name>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner2</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate5</name>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner1</name>
            <value>John Wick</value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate6</name>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner4</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate7</name>
        </eventFieldList>
        <eventFieldList>
            <name>actionOwner3</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate1</name>
            <value>11/09/2015 00:00:00</value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate3</name>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate2</name>
        </eventFieldList>
        <eventFieldList>
            <name>locations</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>impactToOrg</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>actionDate10</name>
        </eventFieldList>
        <eventFieldList>
            <name>locationDisplay</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>subCategory</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>severity</name>
            <value>Severity 3 - Minor Outage (Some Service Degradation)</value>
        </eventFieldList>
        <eventFieldList>
            <name>duration</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>lineNumber</name>
            <value></value>
        </eventFieldList>
        <eventFieldList>
            <name>impactCondition</name>
            <value></value>
        </eventFieldList>
        <formName>MetroEvent</formName>
    </eventFormList>
    <ns3:link uri="https://api.<region>.whispir.com/workspaces/26C20B1A09XS3RA2/events/421FEEBA93GF53A2?apikey=<your_api_key>" rel="self" method="GET"/>
    <ns3:link uri="https://api.<region>.whispir.com/workspaces/26C20B1A09XS3RA2/events/421FEEBA93GF53A2?apikey=<your_api_key>" rel="self" method="PUT" type="application/vnd.whispir.event-v1+xml,application/vnd.whispir.event-v1+json"/>
    <ns3:link uri="https://api.<region>.whispir.com/workspaces/26C20B1A09XS3RA2/messages?label=2701095%20-%20Outage%20of%20Local%20Systems%20in%20Sydney" rel="retrieveEventMessages" method="GET"/>
</ns2:event>
{
  "id": "421FEEBA93GF53A2",
  "eventLabel": "2701095 - Outage of Local Systems in Sydney",
  "status": "Active",
  "eventFormList": [
    {
      "formName": "MetroEvent",
      "eventFieldList": [
        {
          "name": "summary",
          "value": "Outage of systems in Sydney"
        },
        {
          "name": "location",
          "value": "0.0,0.0"
        },
        {
          "name": "endDate"
        },
        {
          "name": "type",
          "value": ""
        },
        {
          "name": "actionDetails2",
          "value": ""
        },
        {
          "name": "actionDetails3",
          "value": ""
        },
        {
          "name": "actionDetails1",
          "value": "investigation to take place asap."
        },
        {
          "name": "priority",
          "value": ""
        },
        {
          "name": "description",
          "value": "ATMs are non responsive, teams to be sent to investigate."
        },
        {
          "name": "actionDetails8",
          "value": ""
        },
        {
          "name": "actionDetails9",
          "value": ""
        },
        {
          "name": "actionDetails6",
          "value": ""
        },
        {
          "name": "actionDetails7",
          "value": ""
        },
        {
          "name": "actionDetails4",
          "value": ""
        },
        {
          "name": "actionOwner10",
          "value": ""
        },
        {
          "name": "actionDetails5",
          "value": ""
        },
        {
          "name": "platform",
          "value": ""
        },
        {
          "name": "services",
          "value": ""
        },
        {
          "name": "status",
          "value": "Open"
        },
        {
          "name": "openedBy",
          "value": ""
        },
        {
          "name": "category",
          "value": "Internal"
        },
        {
          "name": "externalVendor",
          "value": ""
        },
        {
          "name": "externalCaseNumber",
          "value": ""
        },
        {
          "name": "actionOwner6",
          "value": ""
        },
        {
          "name": "startDate",
          "value": "11/09/2015 00:00:00"
        },
        {
          "name": "actionOwner5",
          "value": ""
        },
        {
          "name": "actionOwner8",
          "value": ""
        },
        {
          "name": "actionOwner7",
          "value": ""
        },
        {
          "name": "actionOwner9",
          "value": ""
        },
        {
          "name": "actionDate8"
        },
        {
          "name": "actionDate9"
        },
        {
          "name": "actionDetails10",
          "value": ""
        },
        {
          "name": "actionDate4"
        },
        {
          "name": "actionOwner2",
          "value": ""
        },
        {
          "name": "actionDate5"
        },
        {
          "name": "actionOwner1",
          "value": "John Wick"
        },
        {
          "name": "actionDate6"
        },
        {
          "name": "actionOwner4",
          "value": ""
        },
        {
          "name": "actionDate7"
        },
        {
          "name": "actionOwner3",
          "value": ""
        },
        {
          "name": "actionDate1",
          "value": "11/09/2015 00:00:00"
        },
        {
          "name": "actionDate3"
        },
        {
          "name": "actionDate2"
        },
        {
          "name": "locations",
          "value": ""
        },
        {
          "name": "impactToOrg",
          "value": ""
        },
        {
          "name": "actionDate10"
        },
        {
          "name": "locationDisplay",
          "value": ""
        },
        {
          "name": "subCategory",
          "value": ""
        },
        {
          "name": "severity",
          "value": "Severity 3 - Minor Outage (Some Service Degradation)"
        },
        {
          "name": "duration",
          "value": ""
        },
        {
          "name": "lineNumber",
          "value": ""
        },
        {
          "name": "impactCondition",
          "value": ""
        }
      ]
    }
  ],
  "link": [
    {
      "uri": "https://api.<region>.whispir.com/workspaces/26C20B1A09XS3RA2/events/421FEEBA93GF53A2?apikey=<your_api_key>",
      "rel": "self",
      "method": "GET"
    },
    {
      "uri": "https://api.<region>.whispir.com/workspaces/26C20B1A09XS3RA2/events/421FEEBA93GF53A2?apikey=<your_api_key>",
      "rel": "self",
      "method": "PUT",
      "type": "application/vnd.whispir.event-v1+xml,application/vnd.whispir.event-v1+json"
    },
    {
      "uri": "https://api.<region>.whispir.com/workspaces/26C20B1A09XS3RA2/messages?label=2701095%20-%20Outage%20of%20Local%20Systems%20in%20Sydney",
      "rel": "retrieveEventMessages",
      "method": "GET"
    }
  ]
}
High-Level Request Elements
eventLabel: String
Specifies the name of the label used for the messages sent under this event
status: String
Specifies the status of the event. The status can be one of -
  • Active
  • Resolved
Note: The default status is Open.
summary: String
Specifies the summary of the event. A single liner that can be equivalent to the Subject of an email.
description: String
Specifies the detailed description of the event
location: String
Specifies the latitude, longitude values of the event location. This helps to show the event location on Whispir’s geo-map feature set and coordinated communication based on the geo location of the event.
startDate: String
Specifies the startdate of the event. This is a mandatory value.
The date should be in the format of DD/MM/YYYY HH:MI:SS in 24hrs format. e.g 11/09/2015 17:21:00 for 11th September 2015 5.21 PM.
endDate: String
Specifies the endDate of the event.
The date should be in the format of DD/MM/YYYY HH:MI:SS in 24hrs format. e.g. 11/09/2015 19:26:00 for 11th September 2015 7.26 PM.
severity: String
Specifies the severity of the event. While this can change from company to company, the standard value set to be chosen from is -
  • Severity 5 - Routine Maintenance Tasks
  • Severity 4 - Scheduled System Changes
  • Severity SL3 - Minor Outage (Some Service Degradation)
  • Severity SL2 - Moderate Outage (Service Degradation)
  • Severity SL1 - Major Outage (Significant Service Unavailablity)
Priority: String
Specifies the priority of the event. While this can change from company to company, the standard value set to be chosen from is -
  • Priority 5 - No Set Resolution Period
  • Priority 4 - <1 week Resolution
  • Priority 3 - <3 day Resolution
  • Priority 2 - <1 day Resolution
  • Priority 1 - <2hr Resolution
duration: String
The duration of the event in HH:MI:SS. e.g. 02:05:00
This can be substituted in the place of end date if required. Or a subset of the time between the start and end Dates.
– Event categorization attributes –
category: String
Specifies the category of event. The default values to choose from are -
  • Internal Systems
  • External Systems
  • Infrasturcture
subcategory: String
Specifies the subcategory in the category. The default values to choose from are -
  • Customer Impact
  • Cust & Staff Impact
  • Staff Impact
  • Impact Unknown
type: String
Specifies the type of event. The default values to choose from are -
  • Multiple Issues
  • NIL
  • Network
  • Applications
  • Mobile Apps
externalVendor: String
Specifies the name/contact who is the external vendor related to this event
lineNumber: String
Specifies the line Number (production lines)
externalCaseNumber: String
Specifies the number as tracked by an external party realted to this event
– Services effected by this event –
platform: String
Specifies the platform in the company to which this event is associated with
services: String
Specifies the service in the company to which this event is associated with
– Impact of this event –
impactCondition: String
Specifies the impact condition of this event to the company. These values can be configured via custom lists as these can be very specific to the company. The default list to choose from are -
  • All services not available
  • All services degraded
  • Some services not available
  • Some services degraded
  • No Impact
  • Unknown
impactToOrg: String
Specifies the impact of this event to the Organization. These values can be configured via custom lists as these can be very specific to the company. The default list to choose from are -
  • Global
  • National
  • Local
locations: String
Specifies the impact location of this event to the Organization’s operational geographies. These values can be configured via custom lists as these can be very specific to the company.
– Actions for this event –
multiple key value sets: String
Specifies the set of individual actions to be taken during this event.
Each action consists of -
  • actionDate - the start date of this action in dd/mm/yyyy HH:MI:SS 24hr format
  • actionOwner - the individual (contact) responsible for this action’s execution
  • actionDetails - the detail description of this action
An event can have a maximum of 10 action. So the action values are numbered. actionDate1, actionOwner1, actionDetails1
actionDate2, actionOwner2, actionDetails2

actionDate10, actionOwner10, actionDetails10
Alias Fields: String
The other (alias) name and title fields
  • otherFirstName, otherLastName, otherTitle

Sending Messages using event data

Sending Messages using event data

The messages are sent using the /message end point. The added data here is the eventId. The id of the event whose data has to be used.

HTTP1.1 POST https://api.<region>.whispir.com/messages?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Event Notification</subject>    
    <eventId>2EE7FEA3343662BE</eventId>  
    <body>An event has occurred: @@summary@@.  A resolution is required by @@actionDate1@@.</body>
</ns2:message> 

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

{
    "to" : "$mobile",
    "subject" : "Event Notification",
    "eventId" : "2EE7FEA3343662BE",
    "body" : "An event has occurred: @@summary@@.  A resolution is required by @@actionDate1@@."
}

This would resolve as -

Event Notification. 
An event has occurred: Outage of systems in Sydney.  A resolution is required by 11/09/2015 17:41:00.

The response to the request would be as follows -

HTTP 1.1 202 Accepted 
Location: http://api.<region>.whispir.com/messages/47707420BAE1288B?apikey=<your_api_key>  

Once can also use the templates to make the message more structured.

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>$mobile</to>
    <subject>Event Notification</subject>    
    <eventId>2EE7FEA3343662BE</eventId>  
    <messageTemplateId>BCFD647BCD83FED893</messageTemplateId>
</ns2:message> 

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

{
    "to" : "$mobile",
    "subject" : "Event Notification",
    "eventId" : "2EE7FEA3343662BE",
    "messageTemplateId" : "BCFD647BCD83FED893"
}

Once you have completed creating your event data into the Whispir Platform, the next logical step is to be able to deliver a notification about the event.

This action can be performed using the existing Messages endpoint, with the Event ID as an attribute of the message.

Including this Event ID will link the message to the event, and allow you to use any attribute of the Event within your message payload.

Retrieving messages sent in relation to the event

Sample URI for retrieveEventMessages

<ns2:link 
        uri="http://api.<region>.whispir.com/messages?label=657126%20Outage%20of%20systems%20in%20Sydney" 
        rel="retrieveEventMessages" 
        method="GET" /> 
{
   "uri": "http://api.<region>.whispir.com/messages?label=657126%20Outage%20of%20systems%20in%20Sydney",
   "rel": "retrieveEventMessages",
   "method": "GET"
}

You can easily retrieve all of the messages that are associated with an Event by using the unique label that is created for each event.

The label that should be used for searching is provided to users in both the /events and /events/ requests as a link element. The 'rel’ field for this element is: retrieveEventMessages

The API also supports to use this listing to query the different messages for status or any other purpose. And, any of the features available in Sending Messages, or Advanced Messages, are also available to be used within the Events Messages.

Sending in request to retrieve Event Messages

HTTP 1.1 GET https://api.<region>.whispir.com/messages?label=657126%20Outage%20of%20systems%20in%20Sydney?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

response

Accept: application/vnd.whispir.message-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 1 of 1</status>
    <ns2:messages>
        <ns2:message>
            <ns2:link method="GET" rel="self" uri="http://api.<region>.whispir.com/messages/47707420BAE1288B?apikey=<your_api_key>"/>
            <subject>Event Notification</subject>
            <repetitionCount>0</repetitionCount>
            <repeatDays>0</repeatDays>
            <repeatHrs>0</repeatHrs>
            <repeatMin>0</repeatMin>
            <from>John Wick</from>
            <direction>OUTGOING</direction>
            <responseCount>0</responseCount>
            <createdTime>1424062773000</createdTime>
        </ns2:message>
    </ns2:messages>
</ns2:return>
Accept: application/vnd.whispir.message-v1+json

HTTP 1.1 200 OK

{
   "messages" : [{
     "subject" : "Event Notification",
     "repetitionCount" : 0,
     "repeatDays" : 0,
     "repeatHrs" : 0,
     "repeatMin" : 0,
     "from" : "John Wick",
     "direction" : "OUTGOING",
     "responseCount" : "0",
     "createdTime" : 1424062773000,
     "link" : [ {
       "uri" : "http://api.<region>.whispir.com/messages/47707420BAE1288B?apikey=DFD0FD90u809SDF90832FDS ",
       "rel" : "self",
       "method" : "GET"
     } ]
   } ],
   "status" : "",
   "link" : [ ]
} 

Deleting an Event

It is not currently possible to remove events from the Whispir Platform. Instead, events should be updated to have a status of 'Closed’.

Resources

API Endpoint

Default Workspace Example

https://api.<region>.whispir.com/resources/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.resource-v1+xml
https://api.<region>.whispir.com/resources/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.resource-v1+json

Workspace Specific Example

https://api.<region>.whispir.com/workspaces/{:id}/resources/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.resource-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/resources/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.resource-v1+json

Methods supported

- GET
- POST
- PUT
- DELETE

Using Whispir’s API, one can submit data payloads to be stored by Whispir and used in various API calls. These files are uploaded through the /resources endpoint.

Using the Resources endpoint, application developers can submit, retrieve, update, and delete resources. These resources can be used as part of either Whispir Bulk (Dynamic) Messages, or to be used for importing Contacts.

Method Description
GET /resources
  • Provides a List of all the currently saved resources in the company (URIs), sorted by most recently updated
/resources/{:id}
  • Retrieves the representation of the requested resource. (this does not allow users to download the resource, only the representation)
/workspaces/(id)/resources
  • Provides a List of all the currently saved resources in the specified workspace(URIs), sorted by most recently updated
/workspaces/(id)/resources/(id)
  • Retrieves the representation of the requested resource. (this does not allow users to download the resource, only the representation)
POST /resources
  • Creates a new resource for use in the API
/resources/{:id}
  • METHOD not supported
/workspaces/(id)/resources
  • Creates a new resource for use in the API under the particular workspace
/workspaces/(id)/resources/{:id}
  • METHOD not supported
PUT /resources
  • METHOD not supported
/resources/{:id}
  • Update the specified resource with the one supplied in the request.
/workspaces/(id)/resources
  • METHOD not supported
/workspaces/(id)/resources/{:id}
  • Update the specified resource with the one supplied in the request under the particular workspace
DELETE /resources
  • METHOD not supported
/resources/{:id}
  • Delete the specified resource from the Whispir Platform.
/workspaces/(id)/resources
  • METHOD not supported
/workspaces/(id)/resources/{:id}
  • Delete the specified resource from the Whispir Platform under the particular workspace

Creating a resource

HTTP 1.1 POST https://api.<region>.whispir.com/resources?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.resource-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:resource xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <name>test.csv</name>
    <scope>private</scope>
    <mimeType>text/csv</mimeType>
   <derefUri>
     ...base64 representation...
     </derefUri>
</ns3:resource>

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

{
  "name" : "test.csv",
  "scope" : "private",
  "mimeType" : "text/csv",
  "derefUri" : "...base64 representation..."
}   

Response

HTTP 1.1 201 Created
...
Location: http://api.<region>.whispir.com/resources/4FBBC384BCE3DAABFE3
...

Creating a resource is very easy. To create a new resource we should use the /resources end point.

The following are the mandatory fields needed to create a resource -

High-Level Response Elements
name: String
Specifies the name of the file being uploaded. The extension of the file too is allowed to be present in the name. Eg: australia-contacts.csv

Note: It is advised that names should not contain spaces or special characters other than `-` and `.`. This helps for easier search and also for a valid URL link (especially) in case of public scoped files.
Eg: `australia-contacts.csv` is better name convention than `australia contacts.csv` as the latter converts into `australia%20contacts.csv`.
scope: String
Specifies the permission scope of the file being uploaded. The scope defines the access restriction of the resource. It can be only one of -
  • Public - Public files have an addressable URL and are available publicly
  • Private - Private files have no URL and are only available for bulk messaging purposes and for importing contacts.
mimeType: String
The mime type of the file that is being uploaded. The type is dependent on the scope of the resource.
  • Public - Public files can be of any mimetype. text/html; text/csv
  • Private - Private files are restricted to CSV, JSON, and XML.
derefUri: String
The base64 representation of the file being submitted.

Note: When creating a resource, the following conditions apply -

Example resources

The following are all equivalent representations of the same data structure, across the three supported formats.

CSV format

As the CSV file format does not support structured objects, they have been omitted from the dataset.

CSV

fullname,email,mobile,streetaddress,suburb,manifest.name,manifest.value.timestamp
Franco Himboli,fhimboli@gmail.com,0410509001,123 Auburn Rd,Hawthorn,Delivery Manifest,20-10-2014 10:24
Jordan Windsor,jwindsor@yahoo.com,0410509002,360 Walsh Rd,North Melbourne,Delivery Manifest,20-10-2014 10:24

JSON Format

JSON

[{
 "fullname": "Franco Himboli",
 "email": "ftrimboli@gmail.com",
 "mobile": "0410509001",
 "streetaddress": "123 Auburn Rd",
 "suburb": "Hawthorn",
 "Reference": "Xpress Mail",
 "MsgData" : {
  "POBDetail": {
    "DateAndTime" : "09-Sep-2015 12:15 PM",
    "Message" : "Please let us know if the time slot is acceptable. Respond with a 'No' to get alternative time slot"
  }
  }
},
{
 "fullname": "Jordan Windsor",
 "email": "jwindsor@yahoo.com",
 "mobile": "0410509002",
 "streetaddress": "360 Walsh Rd",
 "suburb": "North Melbourne",
 "Reference": "Xpress Mail",
 "MsgData" : {
  "POBDetail": {
    "DateAndTime" : "09-Sep-2015 12:30 PM",
    "Message" : "Please let us know if the time slot is acceptable. Respond with a 'No' to get alternative time slot"
  }
  }
}]

XML

<?xml version="1.0" encoding="UTF-8"?>
<recipients>
   <recipient>
      <name>Franco</name>
      <surname>Himboli</surname>
      <email>ftrimboli@gmail.com</email>
      <mobile>0410509001</mobile>
      <streetaddress>123 Auburn Rd</streetaddress>
      <suburb>Hawthorn</suburb>
    <Reference>Xpress Mail</Reference>
      <MsgData>
    <POBDetail>
      <DateAndTime>09-Sep-2015 12:15 PM</DateAndTime>
      <Message>Please let us know if the time slot is acceptable. Respond with a 'No' to get alternative time slot</Message>
    </POBDetail>
    </MsgData>
   </recipient>
   <recipient>
      <name>Jordan</name>
      <surname>Windsor</surname>
      <email>jwindsor@yahoo.com</email>
      <mobile>0410509002</mobile>
      <streetaddress>360 Walsh Rd</streetaddress>
      <suburb>North Melbourne</suburb>
      <Reference>Xpress Mail</Reference>
      <MsgData>
    <POBDetail>
      <DateAndTime>09-Sep-2015 12:30 PM</DateAndTime>
      <Message>Please let us know if the time slot is acceptable. Respond with a 'No' to get alternative time slot</Message>
    </POBDetail>
    </MsgData>
   </recipient>
</recipients>

Once you have your data in one of the above 3 formats, you need to convert it into Base64 format, but before we do that, let’s create our Message Template to determine what we actually want to send to these recipients.

Encode the JSON, CSV or XML into Base64

In order to prepare the file to be uploaded to Whispir, it needs to be endcoded from it’s textual representation into a Base64 encoded version. Base64 is a common method of encoding binary data in ASCII format. Whispir uses it as a common method of exchange of file data. It is also used when uploading attachments to messages in Whispir, or specifing custom WAV files for outbound voice calls. More information about Base64 can be found here .

Most programming languages will provide a facility to convert text into Base64. A simple internet search for ‘base 64 encode java’, or 'base 64 encode PHP’ will yeild results on how to accomplish this task.

JSON file encoded to Base64

The output after encoding the JSON Sample File into Base64 will look as follows:

W3sNCiAiZnVsbG5hbWUiOiAiRnJhbmNvIEhpbWJvbGkiLA0KICJlbWFpbCI6ICJmdHJpbWJvbGlAZ21haWwuY29tIiwNCiAibW9iaWxlIjogIjA0MTA1MDkwMDEiLA0KICJzdHJlZXRhZGRyZXNzIjogIjEyMyBBdWJ1cm4gUmQiLA0KICJzdWJ1cmIiOiAiSGF3dGhvcm4iLA0KICJSZWZlcmVuY2UiOiAiWHByZXNzIE1haWwiLA0KICJNc2dEYXRhIiA6IHsgDQoJIlBPQkRldGFpbCI6IHsNCgkJIkRhdGVBbmRUaW1lIiA6ICIwOS1TZXAtMjAxNSAxMjoxNSBQTSIsDQoJCSJNZXNzYWdlIiA6ICJQbGVhc2UgbGV0IHVzIGtub3cgaWYgdGhlIHRpbWUgc2xvdCBpcyBhY2NlcHRhYmxlLiBSZXNwb25kIHdpdGggYSAnTm8nIHRvIGdldCBhbHRlcm5hdGl2ZSB0aW1lIHNsb3QiDQoJfQ0KICB9DQp9LA0Kew0KICJmdWxsbmFtZSI6ICJKb3JkYW4gV2luZHNvciIsDQogImVtYWlsIjogImp3aW5kc29yQHlhaG9vLmNvbSIsDQogIm1vYmlsZSI6ICIwNDEwNTA5MDAyIiwNCiAic3RyZWV0YWRkcmVzcyI6ICIzNjAgV2Fsc2ggUmQiLA0KICJzdWJ1cmIiOiAiTm9ydGggTWVsYm91cm5lIiwNCiAiUmVmZXJlbmNlIjogIlhwcmVzcyBNYWlsIiwNCiAiTXNnRGF0YSIgOiB7IA0KCSJQT0JEZXRhaWwiOiB7DQoJCSJEYXRlQW5kVGltZSIgOiAiMDktU2VwLTIwMTUgMTI6MzAgUE0iLA0KCQkiTWVzc2FnZSIgOiAiUGxlYXNlIGxldCB1cyBrbm93IGlmIHRoZSB0aW1lIHNsb3QgaXMgYWNjZXB0YWJsZS4gUmVzcG9uZCB3aXRoIGEgJ05vJyB0byBnZXQgYWx0ZXJuYXRpdmUgdGltZSBzbG90Ig0KCX0NCiAgfQ0KfV0=

This is now ready to be uploaded to Whispir.

Upload the encoded file to Whispir using the API

HTTP 1.1 POST https://api.<region>.whispir.com/resources?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.resource-v1+xml


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:resource xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <name>test.json</name>
    <scope>private</scope>
    <mimeType>application/json</mimeType>
 <derefUri>W3sNCiAiZnVsbG5hbWUiOiAiRnJhbmNvIEhpbWJvbGkiLA0KICJlbWFpbCI6ICJmdHJpbWJvbGlAZ21haWwuY29tIiwNCiAibW9iaWxlIjogIjA0MTA1MDkwMDEiLA0KICJzdHJlZXRhZGRyZXNzIjogIjEyMyBBdWJ1cm4gUmQiLA0KICJzdWJ1cmIiOiAiSGF3dGhvcm4iLA0KICJSZWZlcmVuY2UiOiAiWHByZXNzIE1haWwiLA0KICJNc2dEYXRhIiA6IHsgDQoJIlBPQkRldGFpbCI6IHsNCgkJIkRhdGVBbmRUaW1lIiA6ICIwOS1TZXAtMjAxNSAxMjoxNSBQTSIsDQoJCSJNZXNzYWdlIiA6ICJQbGVhc2UgbGV0IHVzIGtub3cgaWYgdGhlIHRpbWUgc2xvdCBpcyBhY2NlcHRhYmxlLiBSZXNwb25kIHdpdGggYSAnTm8nIHRvIGdldCBhbHRlcm5hdGl2ZSB0aW1lIHNsb3QiDQoJfQ0KICB9DQp9LA0Kew0KICJmdWxsbmFtZSI6ICJKb3JkYW4gV2luZHNvciIsDQogImVtYWlsIjogImp3aW5kc29yQHlhaG9vLmNvbSIsDQogIm1vYmlsZSI6ICIwNDEwNTA5MDAyIiwNCiAic3RyZWV0YWRkcmVzcyI6ICIzNjAgV2Fsc2ggUmQiLA0KICJzdWJ1cmIiOiAiTm9ydGggTWVsYm91cm5lIiwNCiAiUmVmZXJlbmNlIjogIlhwcmVzcyBNYWlsIiwNCiAiTXNnRGF0YSIgOiB7IA0KCSJQT0JEZXRhaWwiOiB7DQoJCSJEYXRlQW5kVGltZSIgOiAiMDktU2VwLTIwMTUgMTI6MzAgUE0iLA0KCQkiTWVzc2FnZSIgOiAiUGxlYXNlIGxldCB1cyBrbm93IGlmIHRoZSB0aW1lIHNsb3QgaXMgYWNjZXB0YWJsZS4gUmVzcG9uZCB3aXRoIGEgJ05vJyB0byBnZXQgYWx0ZXJuYXRpdmUgdGltZSBzbG90Ig0KCX0NCiAgfQ0KfV0=</derefUri>
</ns3:resource>

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

{
  "name" : "test.json",
  "scope" : "private",
  "mimeType" : "application/json",
  "derefUri" : "W3sNCiAiZnVsbG5hbWUiOiAiRnJhbmNvIEhpbWJvbGkiLA0KICJlbWFpbCI6ICJmdHJpbWJvbGlAZ21haWwuY29tIiwNCiAibW9iaWxlIjogIjA0MTA1MDkwMDEiLA0KICJzdHJlZXRhZGRyZXNzIjogIjEyMyBBdWJ1cm4gUmQiLA0KICJzdWJ1cmIiOiAiSGF3dGhvcm4iLA0KICJSZWZlcmVuY2UiOiAiWHByZXNzIE1haWwiLA0KICJNc2dEYXRhIiA6IHsgDQoJIlBPQkRldGFpbCI6IHsNCgkJIkRhdGVBbmRUaW1lIiA6ICIwOS1TZXAtMjAxNSAxMjoxNSBQTSIsDQoJCSJNZXNzYWdlIiA6ICJQbGVhc2UgbGV0IHVzIGtub3cgaWYgdGhlIHRpbWUgc2xvdCBpcyBhY2NlcHRhYmxlLiBSZXNwb25kIHdpdGggYSAnTm8nIHRvIGdldCBhbHRlcm5hdGl2ZSB0aW1lIHNsb3QiDQoJfQ0KICB9DQp9LA0Kew0KICJmdWxsbmFtZSI6ICJKb3JkYW4gV2luZHNvciIsDQogImVtYWlsIjogImp3aW5kc29yQHlhaG9vLmNvbSIsDQogIm1vYmlsZSI6ICIwNDEwNTA5MDAyIiwNCiAic3RyZWV0YWRkcmVzcyI6ICIzNjAgV2Fsc2ggUmQiLA0KICJzdWJ1cmIiOiAiTm9ydGggTWVsYm91cm5lIiwNCiAiUmVmZXJlbmNlIjogIlhwcmVzcyBNYWlsIiwNCiAiTXNnRGF0YSIgOiB7IA0KCSJQT0JEZXRhaWwiOiB7DQoJCSJEYXRlQW5kVGltZSIgOiAiMDktU2VwLTIwMTUgMTI6MzAgUE0iLA0KCQkiTWVzc2FnZSIgOiAiUGxlYXNlIGxldCB1cyBrbm93IGlmIHRoZSB0aW1lIHNsb3QgaXMgYWNjZXB0YWJsZS4gUmVzcG9uZCB3aXRoIGEgJ05vJyB0byBnZXQgYWx0ZXJuYXRpdmUgdGltZSBzbG90Ig0KCX0NCiAgfQ0KfV0="
}   

Response

Once the resource is created, you can now use this in Whispir to send a message to each of the recipients using the data within the resource.

HTTP 1.1 201 Created
...
Location: http://api.<region>.whispir.com/resources/ABD435DBFCD663DEDEFF?apikey=<your_api_key>
...

Sending Messages using template and resources

Apart from use in the Dynamic Messages, resources can be equally used sending dynamic messages with or without a template.

Assuming there is a template that has already been created with stencil as -

TemplateID: BCD384BC3847CD3484CD

{
  "messageTemplateName" : "Delivery Plan",
  "subject" : "Delivery Plan:",
  "body" : "Hi @@name@@ @@surname@@, Your planned mail delivery is at @@MsgData.POBDetail.DateAndTime@@. @@MsgData.POBDetail.Message@@. Any questions, please call 1300 WHISPIR."
}

Now we have the templateId(for content) with the resourceID (for recipients). Using these two key pieces of information, developers can submit an API request to kick off the Dynamic Messaging process.

The smsMappingField should be mapped to the column or key that holds the number to which the SMS has to sent to; and the emailMappingField to the email to which the message has to be sent to. refer to Dynamic Messages for more details on the mapping.

Sending the Bulk Message

the resource type here is application/vnd.whispir.bulkmessage-v1+xml, application/vnd.whispir.bulkmessage-v1+json. Not the usual application/vnd.whispir.message-v1+xml, application/vnd.whispir.message-v1+json.

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.bulkmessage-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
   <resource>
      <resourceId>ABD435DBFCD663DEDEFF</resourceId>
    <smsMappingField>mobile</smsMappingField>
      <emailMappingField>email</emailMappingField>
   </resource>
   <messageTemplateId>BCD384BC3847CD3484CD</messageTemplateId>
</ns2:message>
Content-Type: application/vnd.whispir.bulkmessage-v1+json

{
  "resource" :{
    "resourceId" : "ABD435DBFCD663DEDEFF",
    "smsMappingField" : "mobile",
    "emailMappingField" : "email",
    "voiceMappingField" : ""
  },
  "messageTemplateId": "BCD384BC3847CD3484CD"
}

Final Message delivered to Customer (Individually)

The message when combined with the data will be -

Hi Franco Thimboli, Your planned mail delivery is at 09-Sep-2015 12:15 PM. Please let us know if the time slot is acceptable. Respond with a 'No' to get alternative time slot. Any questions, please call 1300 WHISPIR.

Hi Jordan Windsor, Your planned mail delivery is at 09-Sep-2015 12:30 PM. Please let us know if the time slot is acceptable. Respond with a 'No' to get alternative time slot. Any questions, please call 1300 WHISPIR.

Response

HTTP 1.1 202 Accepted
Location: http://api.<region>.whispir.com/messages/CDB938478CD6DBC3784C?apikey=[your_api_key]

Error in creating a resource

The API may report error in the resource processing. The reason would be part of the response to the POST call.The standard reasons are -

Standard Error Scenarios
Error Condition Details
Request a URI that doesn’t exist Response Code
  • 404 Not Found
Description
  • The requested URI does not exist
Actions for application client
  • Resource does not exist. Incorrect resource identifier, or resource has been removed.
Provide an attachment that is bigger than 10 MB Response Code
  • 422 Unprocessable Entity
Description
  • The POST request entity exceeds allowed size
Actions for application client
  • Ensure the size of the resource does not exceed 10MiB.
Provide a mime type that is not json, xml or csv Response Code
  • 422 Unprocessable Entity
Description
  • The request was unsuccessful because the requested content type is not supported by the API.
Actions for application client
  • Incorrect mime type. Only text/csv, application/xml, application/json are supported as bulk message resources.
Malformed XML or JSON passed Response Code
  • 422 Unprocessable Entity
Description
  • An error occurred when processing entity in the request.
Actions for application client
  • Likely to be a malformed CSV, XML, or JSON file. Verify the data structure.

Retrieving existing resources

Existing resources can be easily retrieved via the GET /resources API call. The response lists all of the existing public and private resources available in the system.

Retrieving resources

The resources contain the id, and url link of the resource (only public)

HTTP 1.1 GET https://api.<region>.whispir.com/resources/?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Accept: application/vnd.whispir.resource-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 7 of 7    </status>
    <ns2:resources>
        <ns2:resource>
            <name>singapore.csv</name>
            <scope>private</scope>
            <mimeType>application/json</mimeType>
            <ns2:link uri="https://api.<region>.whispir.com/resources/D9A8DC34EDRSD7E4?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:resource>
        <ns2:resource>
            <name>australia.json</name>
            <scope>private</scope>
            <mimeType>application/json</mimeType>
            <ns2:link uri="https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:resource>
        <ns2:resource>
            <name>usa.csv</name>
            <scope>private</scope>
            <mimeType>text/csv</mimeType>
            <ns2:link uri="https://api.<region>.whispir.com/resources/3E2F6E72642F949?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:resource>
        <ns2:resource>
            <name>users.json</name>
            <scope>public</scope>
            <mimeType>application.json</mimeType>
            <url>https://cdn-ap.whispir.com/public/resources/216asdfgjgedf1sdf56fd472360cd.json</url>
            <ns2:link uri="https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:resource>
        <ns2:resource>
            <name>whispir-example-bulk-message-1.csv</name>
            <scope>private</scope>
            <mimeType>text/csv</mimeType>
            <ns2:link uri="https://api.<region>.whispir.com/resources/32SDF43ED6829B2?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:resource>
        <ns2:resource>
            <name>whispir-example-bulk-message-2.csv</name>
            <scope>private</scope>
            <mimeType>text/csv</mimeType>
            <ns2:link uri="https://api.<region>.whispir.com/resources/C708D712EDRB0?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:resource>
        <ns2:resource>
            <name>whispir-example-bulk-message-3.csv</name>
            <scope>private</scope>
            <mimeType>text/csv</mimeType>
            <ns2:link uri="https://api.<region>.whispir.com/resources/2FEED897U46E2?apikey=<your_api_key>" rel="self" method="GET"/>
        </ns2:resource>
    </ns2:resources>
</ns2:return>
Accept: application/vnd.whispir.resource-v1+json

{
  "resources": [
    {
      "name": "singapore.csv",
      "scope": "private",
      "mimeType": "application/json",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/resources/D9A8DC34EDRSD7E4?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "name": "australia.json",
      "scope": "private",
      "mimeType": "application/json",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "name": "usa.csv",
      "scope": "private",
      "mimeType": "text/csv",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/resources/3E2F6E72642F949?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "name": "users.json",
      "scope": "public",
      "mimeType": "application/json",
      "url": "https://cdn-ap.whispir.com/public/resources/2163b29d4edf1bd77d71a36210d472360cd.json",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "name": "whispir-example-bulk-message-1.csv",
      "scope": "private",
      "mimeType": "text/csv",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/resources/32SDF43ED6829B2?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "name": "whispir-example-bulk-message-2.csv",
      "scope": "private",
      "mimeType": "text/csv",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/resources/C708D712EDRB0?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "name": "whispir-example-bulk-message-3.csv",
      "scope": "private",
      "mimeType": "text/csv",
      "link": [
        {
          "uri": "https://api.<region>.whispir.com/resources/2FEED897U46E2?apikey=<your_api_key>",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "status": "1 to 7 of 7    ",
  "link": []
}

Retrieving a single resource

A single resource (public|private) can be retrieved from the available resource by using the resource’s specific link uri.

Retrieving a single resource

use the resource’s link uri for private scope file

HTTP 1.1 GET https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Accept: application/vnd.whispir.resource-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:resource xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <name>australia.json</name>
    <scope>private</scope>
    <mimeType>application/json</mimeType>
    <ns2:link uri="https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>" rel="self" method="GET"/>
    <ns2:link uri="https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>" rel="updateResource" method="PUT" type="application/vnd.whispir.resource-v1+json,application/vnd.whispir.resource-v1+xml"/>
    <ns2:link uri="https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>" rel="deleteResource" method="DELETE"/>
</ns3:resource>

Accept: application/vnd.whispir.resource-v1+json

{
  "name": "australia.json",
  "scope": "private",
  "mimeType": "application/json",
  "link": [
    {
      "uri": "https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>",
      "rel": "self",
      "method": "GET"
    },
    {
      "uri": "https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>",
      "rel": "updateResource",
      "method": "PUT",
      "type": "application/vnd.whispir.resource-v1+json,application/vnd.whispir.resource-v1+xml"
    },
    {
      "uri": "https://api.<region>.whispir.com/resources/D3E2XCDF3WS4859?apikey=<your_api_key>",
      "rel": "deleteResource",
      "method": "DELETE"
    }
  ]
}
> > use the resource's link uri for public scope file

HTTP 1.1 GET https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Accept: application/vnd.whispir.resource-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:resource xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <name>users.json</name>
    <scope>public</scope>
    <mimeType>application/json</mimeType>
  <url>https://cdn-ap.whispir.com/public/resources/2163b29d4edf1bd77d71a36210d472360cd.json</url>
    <ns2:link uri="https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>" rel="self" method="GET"/>
    <ns2:link uri="https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>" rel="updateResource" method="PUT" type="application/vnd.whispir.resource-v1+json,application/vnd.whispir.resource-v1+xml"/>
    <ns2:link uri="https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>" rel="deleteResource" method="DELETE"/>
</ns3:resource>

Accept: application/vnd.whispir.resource-v1+json

{
  "name": "users.json",
  "scope": "public",
  "mimeType": "application/json",
  "url": "https://cdn-ap.whispir.com/public/resources/2163b29d4edf1bd77d71a36210d472360cd.json",
  "link": [
    {
      "uri": "https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>",
      "rel": "self",
      "method": "GET"
    },
    {
      "uri": "https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>",
      "rel": "updateResource",
      "method": "PUT",
      "type": "application/vnd.whispir.resource-v1+json,application/vnd.whispir.resource-v1+xml"
    },
    {
      "uri": "https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=<your_api_key>",
      "rel": "deleteResource",
      "method": "DELETE"
    }
  ]
}
High-Level Response Elements
name: String
Specifies the name of the resource. The name is given during creation.
scope: String
Specifies the permission scope of the file being uploaded.
mimeType: String
The mime type of the file that is being uploaded.
url: String
The downloaded link to the resource location. Browsing this link results in a download of the resource.

Note: Only available for Public scoped resources.
link: Array
Provides a list of URLs that can be used to manipulate or access the message template.
  • uri - the link to access the message template
  • rel - the descriptor for what the link will do
  • method - the HTTP method to use with this particular link

Filtering search results

Filtering By scope

Resources can be filtered by their scope. This can be achieved by sending in the required scope type in the URL as query parameter. The scope can be one of the allowed scope types.

Filtering resources by scope

Only get the public resources

HTTP 1.1 GET https://api.<region>.whispir.com/resources/?apikey=<your_api_key>&scope=public
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

Only get the private resources

HTTP 1.1 GET https://api.<region>.whispir.com/resources/?apikey=<your_api_key>&scope=private
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

Filtering By name

Filtering resources by scope

With extension of file type

HTTP 1.1 GET https://api.<region>.whispir.com/resources/?apikey=<your_api_key>&name=australia.csv
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

Response will be array of records that match exactly the whole name given in the query

Only part of name

HTTP 1.1 GET https://api.<region>.whispir.com/resources/?apikey=<your_api_key>&name=au
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key

Response will match all records that have au in their file name. So, multiple records are returned.

Resources can be filtered by their name. This can be achieved by sending in the name in the URL as query parameter.

Note: The name including the file extension makes it a unique search.

Eg: - &name=australia.csv

Updating a resource

HTTP 1.1 PUT https://api.<region>.whispir.com/resources/ABD435DBFCD663DEDEFF?apikey=[your_api_key]
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Content-Type: application/vnd.whispir.resource-v1+xml


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:resource xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <name>australia.json</name>
    <scope>private</scope>
    <mimeType>application/json</mimeType>
 <derefUri>W3sNCiAiZnVsbG5hbWUiOiAiRnJhbmNvIEhpbWJvbGkiLA0KICJlbWFpbCI6ICJmdHJpbWJvbGlAZ21haWwuY29tIiwNCiAibW9iaWxlIjogIjA0MTA1MDkwMDEiLA0KICJzdHJlZXRhZGRyZXNzIjogIjEyMyBBdWJ1cm4gUmQiLA0KICJzdWJ1cmIiOiAiSGF3dGhvcm4iLA0KICJSZWZlcmVuY2UiOiAiWHByZXNzIE1haWwiLA0KICJNc2dEYXRhIiA6IHsgDQoJIlBPQkRldGFpbCI6IHsNCgkJIkRhdGVBbmRUaW1lIiA6ICIwOS1TZXAtMjAxNSAxMjoxNSBQTSIsDQoJCSJNZXNzYWdlIiA6ICJQbGVhc2UgbGV0IHVzIGtub3cgaWYgdGhlIHRpbWUgc2xvdCBpcyBhY2NlcHRhYmxlLiBSZXNwb25kIHdpdGggYSAnTm8nIHRvIGdldCBhbHRlcm5hdGl2ZSB0aW1lIHNsb3QiDQoJfQ0KICB9DQp9LA0Kew0KICJmdWxsbmFtZSI6ICJKb3JkYW4gV2luZHNvciIsDQogImVtYWlsIjogImp3aW5kc29yQHlhaG9vLmNvbSIsDQogIm1vYmlsZSI6ICIwNDEwNTA5MDAyIiwNCiAic3RyZWV0YWRkcmVzcyI6ICIzNjAgV2Fsc2ggUmQiLA0KICJzdWJ1cmIiOiAiTm9ydGggTWVsYm91cm5lIiwNCiAiUmVmZXJlbmNlIjogIlhwcmVzcyBNYWlsIiwNCiAiTXNnRGF0YSIgOiB7IA0KCSJQT0JEZXRhaWwiOiB7DQoJCSJEYXRlQW5kVGltZSIgOiAiMDktU2VwLTIwMTUgMTI6MzAgUE0iLA0KCQkiTWVzc2FnZSIgOiAiUGxlYXNlIGxldCB1cyBrbm93IGlmIHRoZSB0aW1lIHNsb3QgaXMgYWNjZXB0YWJsZS4gUmVzcG9uZCB3aXRoIGEgJ05vJyB0byBnZXQgYWx0ZXJuYXRpdmUgdGltZSBzbG90Ig0KCX0NCiAgfQ0KfV0=</derefUri>
</ns3:resource>

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

{
  "name" : "australia.json",
  "scope" : "private",
  "mimeType" : "application/json",
  "derefUri" : "W3sNCiAiZnVsbG5hbWUiOiAiRnJhbmNvIEhpbWJvbGkiLA0KICJlbWFpbCI6ICJmdHJpbWJvbGlAZ21haWwuY29tIiwNCiAibW9iaWxlIjogIjA0MTA1MDkwMDEiLA0KICJzdHJlZXRhZGRyZXNzIjogIjEyMyBBdWJ1cm4gUmQiLA0KICJzdWJ1cmIiOiAiSGF3dGhvcm4iLA0KICJSZWZlcmVuY2UiOiAiWHByZXNzIE1haWwiLA0KICJNc2dEYXRhIiA6IHsgDQoJIlBPQkRldGFpbCI6IHsNCgkJIkRhdGVBbmRUaW1lIiA6ICIwOS1TZXAtMjAxNSAxMjoxNSBQTSIsDQoJCSJNZXNzYWdlIiA6ICJQbGVhc2UgbGV0IHVzIGtub3cgaWYgdGhlIHRpbWUgc2xvdCBpcyBhY2NlcHRhYmxlLiBSZXNwb25kIHdpdGggYSAnTm8nIHRvIGdldCBhbHRlcm5hdGl2ZSB0aW1lIHNsb3QiDQoJfQ0KICB9DQp9LA0Kew0KICJmdWxsbmFtZSI6ICJKb3JkYW4gV2luZHNvciIsDQogImVtYWlsIjogImp3aW5kc29yQHlhaG9vLmNvbSIsDQogIm1vYmlsZSI6ICIwNDEwNTA5MDAyIiwNCiAic3RyZWV0YWRkcmVzcyI6ICIzNjAgV2Fsc2ggUmQiLA0KICJzdWJ1cmIiOiAiTm9ydGggTWVsYm91cm5lIiwNCiAiUmVmZXJlbmNlIjogIlhwcmVzcyBNYWlsIiwNCiAiTXNnRGF0YSIgOiB7IA0KCSJQT0JEZXRhaWwiOiB7DQoJCSJEYXRlQW5kVGltZSIgOiAiMDktU2VwLTIwMTUgMTI6MzAgUE0iLA0KCQkiTWVzc2FnZSIgOiAiUGxlYXNlIGxldCB1cyBrbm93IGlmIHRoZSB0aW1lIHNsb3QgaXMgYWNjZXB0YWJsZS4gUmVzcG9uZCB3aXRoIGEgJ05vJyB0byBnZXQgYWx0ZXJuYXRpdmUgdGltZSBzbG90Ig0KCX0NCiAgfQ0KfV0="
}   

Response

Once the resource is updated, the older version is technically removed. The new resource data will be used in all the references of the resource (via the ID)

HTTP 1.1 204 No Content

Updating a resource involves the same process as in creating a resource. The process of using one of the format (CSV, JSON, XML) for private and any format for public -> converting to base64 encoded data is the same.

The change is doing a PUT to the existing resource URL that needs to be updated. Please be careful that doing an update overwrites the previous resource. There is no versioning available in Whispir for the resources.

Any or all of the 4 values can be changed. i.e, name, scope, mimeType, derefUri, but all 4 are mandatory values to be sent.

Deleting a resource

Deleting a resource

Exact URI of the resource has to be provided.

HTTP 1.1 DELETE https://api.<region>.whispir.com/resources/F1212CF334EDR68?apikey=[your_key]
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
x-api-key: your_api_key

Response

204 No Content

Resources can be deleted after use. These can be both public and private in scope.

Note: Deleting a public resource may result in 404 File Not Found error for any sites or material referencing to it. So, ensure that DELETE is only executed when the reference to all material is removed or the content has to be removed for other purposes immediately.

Imports

API Endpoint

  • generic
https://api.<region>.whispir.com/imports/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.importcontact-v1+xml
https://api.<region>.whispir.com/imports/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.importcontact-v1+json
  • limited to a workspace
https://api.<region>.whispir.com/workspaces/{:id}/imports/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.importcontact-v1+xml
https://api.<region>.whispir.com/workspaces/{:id}/imports/?apikey=<your_api_key>
Content-Type: application/vnd.whispir.importcontact-v1+json
> Methods supported

- POST

The imports endpoint allows users to import a CSV/JSON/XML file of contacts (via /resources) to be added to the contacts database.

This is slightly different from the contact API as it doesn’t support the deleting of contacts. It will only add and update.

Method Description
GET METHOD not supported
POST /imports
  • Invokes the import process into the My Company workspace with the specified resource
/imports/{:id}
  • METHOD not supported
/workspaces/(id)/imports
  • Invokes the import process into the specified workspace with the specified resource.
/workspaces/(id)/imports/{:id}
  • METHOD not supported
PUT METHOD not supported
DELETE METHOD not supported

Bulk contact import

The Whispir API will expose this functionality as a two stage process: 1. Submit contact data within a CSV, JSON, XML payload using the /resource endpoint – which will return a resource ID, 2. Create a new import resource by submitting a POST to the /imports endpoint referencing the resource ID created in step 1.

These two stages are further explained below.

Create a resource specifying the contact information

Sample Data File

The following data file could be produced or created from data in your internal system that needs to be imported into Whispir.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:import xmlns:ns2="http://schemas.api.whispir.com" 
             xmlns:ns3="http://schemas.api.whispir.com/dap">
    <ns2:contacts>
        <ns2:contact>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <workEmailAddress1>john.smith@testcompany.com</workEmailAddress1>
            <workMobilePhone1>61423456789</workMobilePhone1>
            <workCountry>Australia</workCountry>
            <timezone>+10</timezone>
        </ns2:contact>
        <ns2:contact>
            <firstName>Jane</firstName>
            <lastName>Smith</lastName>
            <workEmailAddress1>jane.smith@testcompany.com</workEmailAddress1>
            <workMobilePhone1>61498765432</workMobilePhone1>
            <workCountry>Australia</workCountry>
            <timezone>+10</timezone>
        </ns2:contact>
   </ns2:contacts>
</ns2:import>
{
  "contacts" : [{
    "firstName": "John",
    "lastName": "Smith",
    "workEmailAddress1": "john.smith@testcompany.com",
    "workMobilePhone1": "61423456789",
    "workCountry": "Australia",
    "timezone": "+10"
  },{
    "firstName": "Jane",
    "lastName": "Smith",
    "workEmailAddress1": "jane.smith@testcompany.com",
    "workMobilePhone1": "61498765432",
    "workCountry": "Australia",
    "timezone": "+10"
  }]
}

The data could alternatively be provided in a CSV format

firstName,lastName,workEmailAddress1,workMobilePhone1,workCountry,timezone
John,Smith,john.smith@testcompany.com,61423456789,Australia,+10
Jane,Smith,jane.smith@testcompany,com,61498765432,Australia,+10

You can then use the /resources endpoint to upload this information as a Resource in Whispir.

Applications can upload a valid CSV, XML or JSON resource containing the contact information that will be imported into the Whispir Platform. Whispir will return the resource ID which can be used to import or update contacts within a workspace through the imports endpoint as described below.

Request Structure

Firstly, the application needs to upload a resource using the Creating Resources.

The resource that needs to be provided for contact importing should be in one the following format:

Once this resource has been imported with the appropriate mime type, the application can reference this resource within the import request.

Import a resource using the imports endpoint

Import

Doing an import by mapping the respective data columns to contact fields

HTTP 1.1 POST https://api.<region>.whispir.com/imports?apikey=<your_api_key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
x-api-key: your_api_key
Accept: application/vnd.whispir.importcontact-v1+json

{
    "resourceId": "4FBBC384BCE3DAABFE3",
    "importType" : "contact",
    "importOptions": {
        "fieldMapping" : {
            "firstName": "firstName",
            "lastName": "lastName",
            "workMobilePhone1": "workEmailAddress1",
            "workCountry": "workCountry",
            "timezone": "timezone"
        },
        "importMode" : "replace"
    }

}

If the request was successful, the response contains the information for the calling application to retrieve information about the import process that has been started.

...
HTTP 1.1 202 Accepted
...

After receiving a valid resource ID, applications can make a request to the imports endpoint within a workspace and reference the appropriate resource ID. Whispir will then create an import process that will import the specified data into the workspace.

Once the application has an appropriate resource ID to use within the import endpoint, the following request can be used to begin the import process.

Note: Import processes take place asynchronously. Any contacts will be created once the import process starts, and users will be able to utilise imported contacts as soon as each is completed.

High Level Request Elements
Field Details
resourceId: Description
  • The resource identifier returned from the POST to /resources. Resource referred to must be a valid CSV, XML, or JSON file.
Required
  • Both Tag and Value
Sample Value
  • 4FBBC384BCE3DAABFE3
importType: Description
  • This defines the resource that will be created through this import process.
Required
  • Both Tag and Value
Available Values
  • Contact is the only supported importType at this stage.
importOptions Description
  • The list of options that are passed through to the import engine.
Required
  • Both Tag and Value
Available Values
  • fieldMapping
  • importMode
importMode Description
  • The type of contact import that is occurring.
Required
  • Both Tag and Value
One of three options available:
  • replace
  • duplicate
  • ignore
fieldMapping Description
  • Mapping the data column in your resource file to the contact field value.
Required
  • Both Tag and Value
The following are the mandatory fields to be present and also to be mapped from the resource file:
  • firstName
  • lastName
  • workMobilePhone1
  • workCountry
  • timezone
The fieldMapping section is used to map field/value pairs within a resource to the field/value pairs within a Whispir contact profile - fieldMapping elements must use fields that exist within the resource payload. Any incorrect resource field will return a blank value. - fieldMapping elements must be valid Whispir Contact fields, ie; “firstName”. The complete listing of Contact fields are defined within the [contacts](https://whispir.github.io/api/#creating-new-contacts) API documentation: - fieldMapping can include custom contact fields previously setup within your organisations Contact profile. - The minimum requirement must be fulfilled for a contact to be created, this includes firstName, lastName, and one of personalEmailAddress1, workEmailAddress1, workMobilePhone1, personalMobilePhone1, workCountry and timezone.
firstName Description
  • First Name of the Contact. Value of this field is used to map the field within the resource.
Required
  • Both Tag and Value
Sample value
  • name
lastName Description
  • Last Name of the Contact. Value of this field is used to map the field within the resource.
Required
  • Both Tag and Value
Sample value
  • surname
workMobilePhone1 Description
  • The mobile phone number of the Contact. Value of this field is used to map the field within the newly created resource.