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:
- Create, send and retrieve multi-channel messages over 8 different channels
- Invoke scenario based communications for quick, effective and targeted communications
- Publish messages to internal or external web pages, RSS feeds and social networks
- Asynchronously receive all responses to a given message and perform analysis on the data
Communications Template API
The Whispir.io Template API gives developers the ability to:
- Create rich, cross-channel message templates that can be managed by designers within the Whispir Rich Message Studio.
- Ensure a DRY (don’t repeat yourself) pattern within developer code by separating the communication content from code
- Reduce code change by managing content elsewhere
Event Management API
The Whispir.io API Event Management API provides developers with the tools needed to manage the communication around events that happen:
- When events occur in your organisation, manage them using Whispir.io
- Save different event details; Severity, Priority, Description and Tasks to ensure a path to a seamless resolution
- Automatically inform teams through Whispir’s integrated cross-channel messaging, ensuring that you know who has received the message, and more importantly; who hasn’t
Contact Management API
The Whispir.io API provides developers with the ability to manage the recipients of their messages:
- Store contact information in a cloud based highly available and accessible environment
- Use standards based methods to create, update, and delete contact information
- Build forms to allow contacts to self-register and manage their account, with auto-generated email notifications
- Create, update and delete distribution lists that can be accessed for messaging at a later date
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,
- Service “CLOUDFRONT” in the region “GLOBAL”
For all the regional endpoints, you should be using REGION + EC2
- AU, IT, EDUCATION, NZ = AP-SOUTHEAST-2
- AP, AP1 = AP-SOUTHEAST-1
- US = US-WEST-1
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.
- The API URL will be more specific to your region
- 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 -
| Region | API Base URL |
|---|---|
| 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 |
What is my region?
- Login to your Whispir.io Account, and click on any existing key. The information is available there as
Enviromentvalue. Eg: forap.whispir.com, your region isap. - 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 - 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:
- The apikey is to be passed both as a query param and also as a header value.
- 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. - The order in the headers does not matter.
x-api-keycan 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. - If the API Key value is incorrect, or not passed propery, then a
403 Forbiddenerror will be returned by Whispir. - 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:
- Register with Whispir to create your account - (Free 14 Day Trial)
- Activate your account, and reach out to Whispir for the API Credentials- (Whispir Support)
- Check your connectivity to the API
- 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.
- If you are an existing Whispir client, please contact Whispir Support for a new API key.
- 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:
- App API Key
- Authorization Header
- Recipient information
- Message Subject
- 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:
To test your connectivity, you will need to enter the following parameters:
- The URL that you would like to request
- Your App API Key
- Your Authorization Header
- (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
- Your Authorization header may not be quite right, verify your username and password browsing to Whispir.io and clicking ‘Log In’
- If you can successfully log in, then try and re-generate the Base64 encoded username and password using the form above.
- If you cannot log in, then it’s possible your account isn’t active. Contact your Whispir Administrator, or send a message to our support team at support@whispir.io.
Other HTTP errors or no connectivity at all
- If you’re still having issues, please contact us at support@whispir.io.
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):
- application/vnd.whispir.message-v1+json
- application/vnd.whispir.message-v1+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:
- XML -
application/vnd.whispir.message-v1+xml - JSON -
application/vnd.whispir.message-v1+json
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.
- If this Username and password is correct, the server will process the request and send back an appropriate response.
- If the Username and password is not correct, the server will send back an HTTP 401 (Authorization required).
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:
- XML
- JSON
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;
- The Company resource contains many Workspaces.
- The Workspace resource contains many Messages.
- Each Message resource contains a MessageStatus.
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
|
| 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
|
| 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:
limit: the number of rows to be returned (max: 20, default: 20)offset: the record number to start returning from (default: 0)
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:
- Workspaces
- Scenarios
- Messages
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
- criteriaFromDate (format: dd/mm/yyyy)
- criteriaFromTime (format: hh:mm)
- criteriaToDate (format: dd/mm/yyyy)
- criteriaToTime (format: hh:mm)
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:
- projectName - The name of the Workspace to be created.
- 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 -
|
| 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):
- Accept: application/vnd.whispir.workspace-v1+xml
- Accept: application/vnd.whispir.workspace-v1+json
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 -
|
| 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.
|
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:
- Create and Send a new message in a given workspace
- 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.
|
| 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.
|
| dlr: | Object Allows the user to specify the turn ON or turn OFF the DLRs (delivery receipts) via the `type` option e.g.
Usage:
|
| features: | Object Allows the user to modify the push notifications properties if these are configured in the company. pushOptions:
|
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:
- To - the mobile phone number of the recipient
- Subject - the first line or identifier of the SMS
- Body - the remainder of the SMS content
The ‘to’ field can be provided in the following formats:
| 'To’ field options | |
|---|---|
| Ad-hoc Recipients | String
|
| Defined Whispir Recipients | String
|
Notes:
- Each SMS message can contain up to 1600* characters
- The Subject field is Mandatory.
- The Body field is Mandatory.
- MRI (Message Resource Identifier) is the unique Whispir address for the Contact, User or Distribution List.
* 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
- If the response is
202 Accepted, then theLocationheader contains the reference to the message request. This value can be used to retrieve the message status, responses later on. - For any other response codes, please refer to the HTTP Response Codes section.
- If you have failed to capture the
Locationheader value, then refer to How to Retrieve previously sent messages? - This process is same for sms, email, voice, push notifications.
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.
- To - the recipient of the email message.
- Subject - the subject line of the email message.
- Body - the content of the email (either HTML or Plain Text content).
- 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=="
}]
}
}
}
- HTML, HEAD and BODY HTML elements are not supported. HTML content assumes that it is starting from within the BODY tag.
- HTML form and input elements are not supported in most email clients. These can be included in the HTML content but should be thoroughly tested prior to use.
- STYLE elements are supported. It is recommended that a single STYLE element at the top of the HTML that defines the styles for the entire email. However, inline styles are also supported.
- Javascript is not supported and should not be used in e-mail messages.
- Images must be referenced through absolute web urls, any other mechanism will not work on most email clients.
Note: Whispir does not host images for clients, you must use another hosting service and reference the URL in your Whispir request payload.
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:
- attachmentName - The name of the file being attached (mandatory)
- attachmentDesc - An optional description of the file being attached
- derefUri - The base64 representation of the file being uploaded
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:
- The Subject field is Mandatory.
- The Body field is Mandatory.
- The Type field is Mandatory and at a minimum must specify the following string:
<type>ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:</type> - The Type field is mandatory even when no conference call is being used
- Pauses can be added in conference call details using a +
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:
- Message Introduction - Either TTS or WAV file, mandatory for all messages
- Message Acceptance - Requests the recipient to press a button to accept the message
- Message Content - The concatenation of the Message Subject and Message Body (either TTS or WAV file)
- 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.
- All WAV files must be 8bit, 8000Hz, 1ch, 64kbps MAX.
- If the WAV is supplied outside of these criteria, the TTS will be used instead. It is vital that TTS is provided even when using WAV files.
- All of the WAV files combined, may not exceed 10MB in total file size.
Notes:
- attachmentName - The name of the file being attached (mandatory)
- attachmentDesc - For the WAV file to be played as the introduction, this must be voiceintro.wav
- attachmentDesc - For the WAV file to be played as the body, this must be voicebody.wav
- deferUri - The base64 representation of the WAV file being played
- in case of JSON, The attachment element is also an array, so be sure to add the square bracket in there!
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:
- Needs to be able to launch a web browser that is HTML5 compliant. Most mainstream smartphones and tablets include modern browsers.
- Requires Javascript to be enabled on the target devices.
- Have an active internet connection.
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.
- Build to a responsive design that works across your target devices. Ensure you test across these devices.
- Whispir strips body and doctype tags, and replaces them with tags suitable to render on mobile devices. The final DOCTYPE is delivered as a HTML 5 doctype.
- Use style tags at the bottom of the HTML content (rather than in the head tag or inline styles).
- Custom javascript should be included at the bottom of the content if possible (speeds up viewing).
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.
- External hosting also applies to scripts such as javascript libraries. Google CDN has excellent resources here: https://developers.google.com/speed/libraries/. Javascript can also be coded inline if required.
- As content is delivered over HTTPS, it is recommended that all external resources be accessible over HTTPS, as devices may refuse to load or display any mixed (HTTP and HTTPS) content.
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.
- Response Rules can be attached to a Whispir Message Template within the Whispir interface.
- A message with Response Rules displays a response button at the bottom on the page. So ensure your message has at least 60px at the bottom of the page content.
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:
- To - the Whispir Contact MRI value
- Subject - the first line or the badge header text in the Push Note
- Body - the remainder of the Push Content
- 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 ?
- Whispir looks for the contact based on the MRI value in the given workspace (only).
- It loads all the devices under that contact
- Filters them down to the device(s) that has the same appId as passed in the message payload Or set in the template
- Sends a push to all the device(s) matched in the previous step.
- There is NO option to specifically pick a single device. If you need to do that, just register only 1 device for that contact.
- If Whispir does not find any devices under the said contact, the message status will be “PENDING” and the info will be “No valid receipients found for this message”
Notes
- You must register your app with Whispir under the
\appsendpoint. Refer to Apps - You must register the device token generated by your app with Whispir as a contact’s device. Refer to Contact Devices
- You must be sending the push to a contact MRI only. So, refer to the Contacts for getting the MRI value.
- The maximum push content length is 256 bytes for both IOS and Android. This includes the payload structure as well.
- Whispir allows sending of custom message attributes with the payload, however these are not available by default, and needs to be configured by Whispir for you.
- Support for other mobile app platforms (Windows is provided upon request via separate enablement process.
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.
- Using this method, messages can be easily scheduled so that the message is delivered when the recipient requires it. Or based on their preference time of day.
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.
- Using this method, users can easily schedule a message to be delivered multiple times starting from a date and continuing until desired.
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:
- If the user timezone setting is UTC, then messages are scheduled to be sent as per UTC, even if the user has triggered the message sitting in Singapore (+8).
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.
- One has to use the contact mri/ user mri from the Whispir system to resolve these variables.
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.
- For example:
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.
- For example:
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:
- User-defined attributes available through the API are configured at the account level and require Whispir administrative assistance to enable.
- You can start using user-defined attributes through the api by contacting your Whispir Customer Success Representative or support@whispir.com
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.
- Upload the resource file via API (CSV, JSON or XML)
- 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. https://api. |
| 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.
|
| 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
jsmtih@test.com
Any valid Mobile number for SMS or Voice calls (countrycode prefixed)
61423589146,6596624876
Any valid Landline number for Voice calls only (countrycode prefixed)
6197468794
For pre-entered Whispir recipients:
Contacts can be used as a message recipient simply by specifying any valid Whispir Contact MRI
John_Smith.782749@Contact.whispir.com
Users can be used as a message recipient simply by specifying any valid Whispir User MRI
John_Smith@User.whispir.com
Distribution Lists can be used as a message recipient simply by specifying any valid Whispir Distribution List MRI
Crisis_Management.Critical_Incident_Management@list.project.whispir.com
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.
|
| 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):
- The name of the recipient
- The channel type (SMS, Email, Voice, Web)
- The sent timestamp for each channel
- The received timestamp for each channel
- The acknowledged timestamp for each channel
- The undeliverable timestamp (only present when the channel is undeliverable)
- The overall status for this recipient (PENDING, SENT, DELIVRD, READ, FAILED)
- The information text describing how this message has progressed.
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:
- The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
- The View parameter is specifying that the message responses should be shown in a summary view
- 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:
- The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
- The View parameter is specifying that the message responses should be shown in a detailed view
- 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.
- The responseMessage channel describes the messaging channel that the response has come in to the Whispir Platform via.
- The responseMessage content describes the actual content of the inbound message.
- The responseMessage acknowledged shows the date of when the response was received by the Whispir Platform
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:
- messageTemplateName - the name of the template to be stored
- subject - the first line or identifier of the SMS
- body - At least one of the Body fields must be populated (SMS, Email, Voice or Web).
- email - The email content for the message. If no email is required, an empty object must be presented.
- voice - The voice content for the message. If no voice call is required, an empty object must be presented.
- 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.
|
| features: | Object Allows the user to modify the push notifications properties if these are configured in the company. pushOptions:
|
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):
Accept: application/vnd.whispir.template-v1+xmlAccept: application/vnd.whispir.template-v1+json
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.
|
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:
- messageTemplateName - the name of the template to be stored
- subject - the first line or identifier of the SMS
- 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.
|
| features: | Object Allows the user to modify the push notifications properties if these are configured in the company. pushOptions:
|
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:
|
| 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?
- Create a response rule with required conditions
- Create a template/use and existing template - with the above responserule id added to it
- Create a callback/use an existing callback
- Send a message using the messages endpoint specifying the to, template, and callbackId values
After the Message is received:
- The user has replied to the message
- Message is received by Whispir
- Response Rules are applied to the response
- Callback is invoked
- Response body contains the response given by the user, the channel, timestamps (refer to callback Documentation) and customParameters
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?
- Custom Parameters gives you details of various processing/processed values associated with the message
While many parameters are sent, the ones that are associated with response rules are :
- responseRule - the name of responseRule that has matched
- matchedCategory - the category/condition inside the responseRule that has matched
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:
- firstName
- lastName
- workEmailAddress1
- workMobilePhone1
- workCountry
- timezone
| 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 -
|
| 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
|
| Work Place Address: | String Specifies the primary and Secondary values for each respective type. Of all these the workEmailAddress1 is the mandatory field.
|
| Work Place Phones: | Number Specifies the primary and Secondary values for each respective type. Of all these the workMobilePhone1 is the mandatory field.
|
| timezone: | String Specifies the timezone in which the contact lives in. Values in relation to GMT. Supported values are:
|
| Personal Address: | String Specifies the primary and Secondary values for each respective type
|
| Personal Phones: | Number Specifies the primary and Secondary values for each respective type
|
| Alias Fields: | String The other (alias) name and title fields
|
| 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.
|
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 -
- sms
- voice
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=truequery 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. |
| 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. |
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 Contentwith 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 -
- application/vnd.whispir.contact-v1+xml or
- application/vnd.whispir.contact-v1+json
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 -
- GET /contact/{id of contact}
- Update the contact field in the object to the required value
- 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:
- Mapped contacts
- Copied contacts
- Mapped contacts by contact mapping rules
- Mapped contacts via SFTP and contact mapping rules
- Mapped contacts of a customized company Account
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. |
| 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. |
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:
- deviceName
- appId
- platform
- deviceOS
- appVersion
- deviceModel
- pushToken
| 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 -
|
| deviceOS: | String Specifies the device OS. The value can be one of -
|
| 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
|
| pushToken: | String Specifies the pushToken .a.k.a. deviceToken given to your app by APNS/GCM to receive the push notification. |
Notes:
- Ensure that the deviceName is unique for each device.
- Ensure that the values for deviceOS, deviceModel are properly set. Do not leave them as blank or give invalid/erroneous data. These values are the ones that are shown on the UI and in the reports. So proper values gives you an easier way to identify the devices under a given contact.
- Ensure that before the Device is created, you have the appID, and the push token values available.
- A contact can have as many number of devices needed, but limited to the value set in the
deviceLimitin APP creation on the /apps endpoint. You can set it to a maximum of 10 per contact.
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 Contentwith 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 -
- application/vnd.whispir.contactdevice-v1+xml or
- application/vnd.whispir.contactdevice-v1+json
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 -
- GET /contact/{id of contact}/devices/{id of device}
- Update the device field in the object to the required value
- PUT /contact/{id of contact}/devices/{id of device} the new object
Reasons to Update
- Device token (Push tokens) might change when the user re-installs or upgrades the OS on their phone
- Device information might have changed as a result of user upgrading their OS
- 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”
- 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.
- 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
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.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.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 PushWhat 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.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.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.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.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
- Effective management and maintenance of contacts
- Group messaging
- Reporting
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.
- Static : In a static distribution list you manually add contacts and, if required, one or more existing distribution lists. The contacts on the list don’t change unless you manually add or remove them (unlike a dynamic distribution list).
- Dynamic : In a dynamic distribution list you add contacts based on rules relating to information saved in their Whispir profiles. The list of contacts updates automatically if those specified details change in any profiles. For example, if you add contacts based on a specific role (such as ‘trainer’) and a contact moves to a different role, the list will exclude that contact when the message is sent.
- Shared : You can create a shared distribution list that’s made up of manually selected recipients, like a static distribution list. This list is then available for sharing with other workspaces (unlike static 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 Createdresponse 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 Createdresponse after executing this request. If the rules are incorrectly passed, then a422 Unprocessible Entityis 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:
- name - the name of the distribution list to be created
- access - Open Or Restricted
- visibility - Private Or Public
- type - Static or Dynamic
In the case of Dynamic Distribution list, the required fields will be more than usual. As following -
- name - the name of the distribution list to be created
- access - Open Or Restricted
- visibility - Private Or Public
- type - Dynamic
- entityType - contact (limited to contacts only at the moment)
- 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.
|
| visibility |
String Allows the user to specify the visibility for this DL.
|
| type |
String Allows the user to specify the type for this DL. Default is `static`
|
| 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.
|
| 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.
|
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 Namequery 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 Descriptionquery 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
- &name= - to search for name
- &description= - to search by description
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
- Remove a contactId
- 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 -
- ContactIds (type: String) is a comma separated list of Contact IDs that you would like added to the list.
- UserIds (type: String) specifies the Whispir Users that should also be notified when this list is used.
- DistListIds (type: String) specifies the nested lists that are contained within this distribution list.
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 -
- Create a Distribution List (DL)
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.
After the DL is created, if you want to add/update the values, then
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
Modify the DL properties (name, description, contactIds, UserIds, dlIds, location etc) as needed
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:
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.
If the PUT request was successful, the expected response code is a
204 No ContentFor Modifying the Location Information refer to Location Tags for Distribution Lists
Sending Messages
Sending Messages to Distribution Lists
The API call is a
POSTrequest to the/messagesendpoint.
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:
- 'CurrentLocation’ - used to specify that the data is latest and is nearest best last known location of the DL asset
- ’-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 Createdresponse after executing this request. Or204 No Contentin case of a distribution lost update usingPUT
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:
- Whispir will instantly notify your callback server when there is change occurred in Whispir platform.
- You save on your daily API call limits by NOT having to call the /messageresponses or /messagestatus endpoints.
- Response based workflows can be built quickly and effectively.
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 -
- Always use a domain name for the callback. Do NOT use an IP.
- Ensure that your callback server is reachable on the internet. It should not be
localhostor an intranet only application that cannot be reached from the WWW. - Limit the port to 80 or 443. Do no use any other ports.
- 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.
- 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:
|
| contentType: | String Specifies the content type that should be sent to this endpoint. The choices are as follows:
|
| removeHTML: | String Specifies whether HTML should be stripped from responses. The choices are as follows:
|
| retriesEnabled: | Boolean Specifies whether Whispir should perform retries in the event there is a failure accessing the callback service. The choices are as follows:
|
| 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:
|
Note:
- The callback server must be expecting and accepting both GET and POST requests.
- 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. - 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:
- Read the error detail in the response body. It will give you the hint on what the issue is - immediately.
- Is the callback URL reachable from outside of your intranet?
Try again one more time from outside of your network. - 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.
- 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 asauth=:your_tokenon 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:
- Use SSL on your Callback URL
- Use an unique token
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:
- A message has been replied to, or
- A message delivery failure occurred (wrong number, or service unavailable)
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:
- reply: enabled/disabled
- undeliverable: enabled/disabled
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):
- Accept: application/vnd.whispir.api-callback-v1+xml
- Accept: application/vnd.whispir.api-callback-v1+json
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.
|
Using Callbacks
Using Callbacks
Callbacks can be added to messages by adding the
callbackIdparameter 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:
- If the Callback Server returns anything other than an HTTP 200 OK.
- If the authorization to the Callback Server fails (e.g. returns an HTTP 400 level error)
- If the Callback Server does not connect within 5 seconds.
- If the Callback Server does not return a response within 60 seconds.
Callback Retries
The retriesEnabled flag can be enabled on a callback to ensure that Whispir automatically attempts to retry in the event of a failure occurring.
When a failure conditions occurs, Whispir 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:
- When a failure to make a callback occurs, Whispir will begin retries ~every 5 minutes.
- Whispir will retry any callback for up to 24h.
- After 24h, the callbacks will no longer be retried.
- If the callback service becomes available prior to 24h, the callbacks will automatically re-process.
- If the callback service takes longer than 24h, the user can access the callback information from the
/callbacks/:id/callsendpoint.
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&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):
- Accept: application/vnd.whispir.api-call-v1+xml
- Accept: application/vnd.whispir.api-call-v1+json
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:
|
| from: | Object The details about this particular message sender / responder. The properties of this object are as follows:
|
| responseMessage: | Object The details about this particular message that has been sent to the callback. The properties of this object are as follows:
|
| callback: | Object The details about this particular callback attempt. The properties of this object are as follows:
|
| link: | Array Provides a list of URLs that can be used to manipulate or access the callback.
|
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:
|
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:
- Callback server becomes unavailable.
- A message is sent via Whispir with callbacks enabled.
- The Message gets a response, and this triggers the callback
- The callback server is unavailable, so the response is stored with a status of 'FAILED’
- After 24h, the callback server becomes available again. Retries have stopped, so this information will not automatically flow into the callback server.
- The customer writes a script to
GETall of the calls stored in the/callsendpoint and process them. - Once successfully processed, the customer’s script should update the contents of the
/callsendpoint 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):
- Accept: application/vnd.whispir.api-call-v1+xml
- Accept: application/vnd.whispir.api-call-v1+json
The expected response code for this operation is 204 - No Content
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:
|
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;
- App sends a POST /messages request to Whispir for sending a message to the Customer
- App gets a location, messageid with responseCode as
202. Means the message is received by Whispir successfully. - Whispir Queues the request and executes it at the next execution cycle (usually immediate)
then
- Customer receives the message and responds to it
- Whispir receives the message and pushes the response to App via the callback URI
then
- App needs to identify who is the customer that has responded
- App uses the messageid provided earlier (in step 2) to cross check and identify
As evident in the scenario, messageid plays a key role in identifying the message – response chain.
However, rather than using just the Whispir provided messageid, the App can send in its own free-will callback parameters like
- customerID or
- an unique hash that corresponds to a specific transaction, or
- just about anything that can be a unique value in the perspective of your App.
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 }
- in XML as
<entry>
<key>
<value>
</entry>
If there are more than one set of values, the data shall be set as:
- in JSON as
{ Key : Value }, { Key : Value }
- in XML as
<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.
- You are passing in parameters that are custom to a specific message in the /messages call. The parameters are sent included in the callback object. So, you include them in the callbackParameters at source and when you receive them, you get them as
customParameters. the way they are intended.while(1) { read again; }:)
Note:
- The calling App can supply any number of callback parameters.
- The information will be passed back to the application every time a response is triggered.
- The response type will always be string, even when an integer is used.
- Apart from the callback parameters specified in the /messages request, the API also gives other set of values, that are used to process it.
Custom Parameters
Custom Parameters are different from callbackParameters. To make it clear again -
- callbackParameters is used by you in /messages endpoint to pass in any custom values that you need to receive back in the callback response
- customParameters in used by Whispir in the callback response to pass back the callbackParameters (and other values) that you have passed in earlier
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
- the dynamically processed values that whispir used to fulfill your request (the sender, receiver channels, timestamps, and destination email address or phone number)
- the message response rule, and condition that was applied to the response (refer to Matched Rules)
- the callbackParameters (refer to Callback Parameters)
In Detail -
- the dynamically processed values that whispir used to fulfill your request
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.
|
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 -
For communications sent via Email, or web, Whispir has a clear 1:1 relationship, ensuring each outbound communication is unique, with any reply to that communication (regardless of the order of response, or length of time between message send and response) be threaded against the original outbound message.
For communications sent via SMS, things get slightly more complex. Whispir uses a pool of mobile numbers, with Whispir retaining knowledge as to which recipient SMS was sent which message via whispir pool number. This provides Whispir the ability to know which reply from which recipient is for which initial outbound message – it’s pretty clever. The only challenge is where you have very high volumes of messages being issued to the same recipient (e.g. a new sms sent to the same number every 5 minutes), and the list of pool numbers is exhausted with Whispir needing to re-use pool numbers. This is a highly unlikely communication use case, but a principal which needs to be understood.
{
"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 ?
- Two separate messages are sent to the same mobile number, with the both including a callbackid.
- Each message will have been received by the recipient via two different sender numbers.
- Assuming the recipient responds to the first message they received, Whispir will trigger the callback ‘callbackA’.
- If they respond to the second message they received, Whispir will trigger the callback ‘callbackB’
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?
- Two separate messages are sent to the same mobile number with a gap of 30 mins, with the both including a callbackid.
- Each message will have been received by the recipient via two different sender numbers.
- Assuming the recipient responds to the first message they received, Whispir will trigger the callback ‘callbackA’.
- If they respond to the second message they received, Whispir will trigger the callback ‘callbackB’
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?
- Assuming this was the only message sent to the recipient in the 30 minutes, the response will trigger the callback ‘callbackA’
How about 1 hour, 2 hours later?
- The duration between when the message is sent, and the reply received has no significance.
- The challenge in matching outbound messages and their inbound responses is only relevant when the entire pool of numbers (which continues to grow) is exhausted.
- Recipients can respond days (max 7) after the message send out occurred and Whispir will still track the correct message that the reply is relevant to.
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
- Whispir to store the Push Notifications credentials to facilitate Push. The entity to store this within Whispir is an ‘App’.
- Your Company Administrators need visibility over the Apps that are present within the company.
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: 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 Contentwith 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:
- name - name of the scenario
- description - details of the scenario
- 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 -
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
|
| voice: | Object Similar to a text message, a voice call can also be triggered. This provides the necessary information for the channel.
|
| 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):
- Accept: application/vnd.whispir.sceario-v1+xml
- Accept: application/vnd.whispir.scenario-v1+json
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.
|
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 -
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
|
| voice: | Object Similar to a text message, a voice call can also be triggered. This provides the necessary information for the channel.
|
| 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.
|
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 -
- Get all the scenarios
- Pick the required scenario’s link attribute
- 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:
- name - name of the scenario
- description - details of the scenario
- 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 -
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
|
| voice: | Object Similar to a text message, a voice call can also be triggered. This provides the necessary information for the channel.
|
| 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 a Whispir API user (Voice Module), If you want to be able to update the Whispir Activity Log as the call progresses through the IVR to ensure that the auditing shows exactly what information a caller heard.
- As a Whispir API user (SMS Module), If you want to able to retrieve the information about all the message sent by a specific user, the activity log can help you with that.
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:
- module - The name of the module in which the activity is performed (see the high-level request elements table below for list of modules).
- action - The action performed.
- 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 -
|
| module: | String Specifies the module to which this activity belongs to. The following are the list of actions that can be performed -
|
| 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 -
|
| 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):
- Accept: application/vnd.whispir.activity-v1+xml
- Accept: application/vnd.whispir.activity-v1+json
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 -
|
| 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.
|
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 -
- 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)
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 -
- Any API user will be able to perform a GET on /customlists
- 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
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):
- Accept: application/vnd.whispir.customlist-v1+xml
- Accept: application/vnd.whispir.customlist-v1+json
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 -
|
| sorttype: | String Specifies the sorting order. The order can be one of -
|
| linked: | String Specifies the linked status. Linked list item values are dependent on other lists. The linked can be one of -
|
| link: | Array Provides a list of URLs that can be used to manipulate or access the list.
|
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 -
|
| createdDate: | String Specifies the date of the List creation. |
| sorttype: | String Specifies the sorting order. The order can be one of -
|
| linked: | String Specifies the linked status. Linked list item values are dependent on other lists. The linked can be one of -
|
| 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.
|
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 Forbiddenresponse. 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 (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 -
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 -
|
| 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 -
|
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:
- userName
- password
- firstName
- lastName
- timezone
- workCountry
| 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:
|
| 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 -
|
| 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
|
| Work Place Address: | String Specifies the primary and Secondary values for each respective type. Of all these the workEmailAddress1 is the mandatory field.
|
| Work Place Phones: | Number Specifies the primary and Secondary values for each respective type. Of all these the workMobilePhone1 is the mandatory field.
|
| timezone: | String Specifies the timezone in which the user lives in. Values in relation to GMT. Supported values are:
|
| Personal Address: | String Specifies the primary and Secondary values for each respective type
|
| Personal Phones: | Number Specifies the primary and Secondary values for each respective type
|
| Alias Fields: | String The other (alias) name and title fields
|
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.
- First Name
- Last Name
- Title
- Job Title
- Country
- Timezone
- Organization Name
- Division
- Business Unit
- Department
- Team Name
- Role
- Additional Team Name
- Additional Role
- Work Email Address 1
- Work Mobile Phone 1
- Work Phone Area Code 1
- Work Phone 1
- Status * (see note below)
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. |
| 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. |
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 Contentwith 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 -
- application/vnd.whispir.user-v1+xml or
- application/vnd.whispir.user-v1+json
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 -
- GET /users/{id of user}
- Update the user field in the object to the required value
- 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 -
- POST /users for user account creation. Capture the
Locationheader value which is the unique link to the User record. This is used in Step 2 - GET /users/{id} for the user object
- PUT /users/{id} with STATUS set to 'INACTIVE’ - using the user object retreived in step 2
- 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:
- Event Label – The concatenated unique Event ID and Event Name e.g. (2701095 - Outage of Local Systems in Sydney)
- Event Status – The current status of the event e.g. 'Open’ or 'Inactive’
and one set of Actions for this event
- Action Date - The date and time of the action
- Action Owner - The contact who is responsible for this action execution
- Action Detail - The details of the action
All other fields on the event are defined through name/value pairs. E.g.
Optional Fields:
- Event Field Name – Start Date
Event Field Value – 11 Sep 2015
Event Field Name – End Date
Event Field Value – 12 Sep 2015
Event Field Name – Type
Event Field Value – Notification
contd..,
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 Createdalong 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 -
|
| 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 -
|
| 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 -
|
| 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 -
|
| subcategory: | String Specifies the subcategory in the category. The default values to choose from are -
|
| type: | String Specifies the type of event. The default values to choose from are -
|
| 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 -
|
| 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 -
|
| 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 -
actionDate2, actionOwner2, actionDetails2 … actionDate10, actionOwner10, actionDetails10 |
| Alias Fields: | String The other (alias) name and title fields
|
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.
- Any event fields populated on the event will automatically be populated within the message
- Any attributes that are supplied within the message will take priority over any attributes that are from the event.
- The user should not be required to enter any 'attributes’ as these will be retrieved from the linked event.
- The event fields will automatically populate the attributes in the message body (based on the relationships set in the Admin > Settings > Attributes > Message Event Attribute Map)
- The event label will be added to the label field in the message within the Whispir application
- If the event does not contain an event field, and there is no relevant attribute field supplied in the message payload, the @@ tag will not be resolved.
- If you do not supply an attribute in the message payload, and this has also not been supplied from the event, the field simply will not be resolved within the message.
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/
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
|
| POST |
/resources
|
| PUT |
/resources
|
| DELETE |
/resources
|
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 -
- Name
- Scope
- mimeType
- derefUri
| 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 -
|
| mimeType: | String The mime type of the file that is being uploaded. The type is dependent on the scope of the resource.
|
| derefUri: | String The base64 representation of the file being submitted. |
Note: When creating a resource, the following conditions apply -
- Maximum of 10MB per file being uploaded.
- Transactions will have an enforced timeout.
- Resources will be available in the Whispir Platform for a limited timeframe (90 days). These will then be automatically cleaned. This will be a configurable setting for Whispir Administrators.
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
|
| Provide an attachment that is bigger than 10 MB |
Response Code
|
| Provide a mime type that is not json, xml or csv |
Response Code
|
| Malformed XML or JSON passed |
Response Code
|
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.
|
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.
- Public -
&scope=public - Private -
&scope=private
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
auin 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
|
| 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
/resourcesendpoint 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:
- XML
- JSON
- CSV
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
|
| importType: |
Description
|
| importOptions |
Description
|
| importMode |
Description
|
| fieldMapping |
Description
|
| firstName |
Description
|
| lastName |
Description
|
| workMobilePhone1 |
Description
|