Scenarios

Retrieving scenarios

To retrieve a list of scenarios from the developers.whispir.com API you can execute a HTTP GET using the /scenarios endpoint.

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

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

An array of scenarios will be returned to you in the HTTP response body. Each scenario will provide the following information:

Response elements

name

String

Specifies the name of the scenario.

description

String

Specifies the broad description of the scenario.

createdTime

Number

Specifies the scenario created time value in Epoch

link

Array

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

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


While that specifies the master list, doing a GET on a single scenario provides the following information:

Response elements

name

String

Specifies the name of the scenario.

description

String

Specifies the description of the scenario.

createdTime

Number

Specifies the scenario created time value in Epoch.

allowedUsers

String

Specifies the usage permission:

  • EVERYONE
  • SELECTEDUSERS

When SELECTEDUSERS is provided, then ‘allowedUserIds’ shall contain the userID of the allowed users.

allowedUserIds

String

Specifies the comma separated list of users who can run this scenario.

Only contains values when allowedUsers is set to ‘SELECTEDUSERS’.

message

Object

Specifies the messaging options.

to

String

Specifies the phone number or MRI or distribution list to which the message has to be sent

subject

String

Specifies the subject of the message.

body

String

Specifies the body of the message.

label

String

Specifies the label for the message (to view during reporting).

email

Object

Email message that can be sent as part of this scenario:

  • body: The main content of the email.
  • footer: The email footer.
  • type: Text/plain or text/HTML.

voice

Object

Similar to a text message, a voice call can also be triggered. This provides the necessary information for the channel.

  • header: Header for message. This will be played before the subject.
  • body: The main content of the message.
  • footer: The message footer. Played after the body. Usually contains a thank-you note.
  • type: ConfCall:, ConfAccountNo:, ConfPinNo:, ConfModPinNo:, Pin:

web

Object

See Web and social messaging. The web message structure remains exactly the same.

social

Object

See Web and social messaging. The social message structure remains exactly the same.

from

String

The user/contact that the communication will be sent from when the scenario is run.

Example:
joe.bloggs.company@Contact.Melbourne.whispir.au

link

Array

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

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

  • JSON
  • XML

Retrieving a scenario

The following API calls allow users to retrieve scenarios using the Whispir API:

{{codeStart}}

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

{

"scenarios": [

{

"title": "Emergency Comms - Fire",

"description": "Scenario to use during fire evacuation",

"createdTime": 1554787088000,

"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": 1554788441000,

"link": [

{

"uri": "https://api.<region>.whispir.com/scenarios/6EE7F6F2E48B73B4?apikey=[your_api_key]",

"rel": "self",

"method": "GET"

}

]

}],

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

"link": []

}

{{codeEnd}}

 

Retrieving details of a single scenario

Retrieving a single scenario details needs the ID of the scenario:

{{codeStart}}

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

{

"title": "Emergency Comms - Fire",

"description": "Scenario to use during fire evacuation",

"createdTime": 1554789045000,

"allowedUsers": "EVERYONE",

"message": {

"to": "+1000000000",

"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": 1554963750000,

},

"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"

}

]

}

{{codeEnd}}