Get Started with Slingshot WS API

This document will describe the steps included in making the first SlingShot API calls required to run a notification through the SlingShot staging system.

The SlingShot Staging base API URL is:

http://slingshot-stage.surgentnetworks.com/notificationplatform-web/api/

In order to use the staging system, 2 account variable are required that will be provided  to customers separately:

  • Web Service Id (wsid)
  • Secret Key (key)

In parentheses are the variable names used in the sample WS calls below.

Overview

In order to add one (or several) notification(s) into the SlingShot system, complete the following steps:

  1. Generate a security token
  2. Add a notifications to the default campaign
  3. After the notifications have been delivered, retrieve the notification result from the system

Step 1: Get the security token

Each call to the SlingShot API includes a header with a security token for identification. The first step in executing any call is to retrieve a valid security token. The token, once retrieved will be valid for 1 hour and can be reused.

HTTP method: GET

URL:  /auth/token

Path parameters: wsid and key

Sample call:

/GET http://slingshot-stage.surgentnetworks.com/notificationplatform-web/api/auth/token?wsid=11111111-1111-1111-1111-111111111111&key=abcdefghijklmnop

Sample Return:

Response Body:

11111111-0000-0000-0000-100000000002:RQWQzToTGVy9o7CVIyo5JEElxnrS12oDWdX_Yv6MITKEb6hELWowXueycf19GjpE5R6uyxZsTgPu2p_PGpNPPWZtR_96Gry6_NO7v65bFTgJkWQQiOvf0h9JH3dI-HNh

Note: The returned value contains the Web Service Id followed by an encoded value. The value for X-Security-Token in the following examples is the concatenated string of both, not just the encrypted part.

Note: We encourage production users to generate the token on their own. Please refer to ‘Security’ section below.

Step 2: Add your notifications to the default campaign

Next, use the token just created in step one to add a list of notifications to SlingShot. Below are sample Web Service bodies for a voice- and an text message notification.

HTTP method: PUT

URL: /queue/list

Headers:

  • accept = application/json
  • X-Security-Token={retrieved token}
  • Content-Type=application/json

Sample Call

/PUT http://slingshot-stage.surgentnetworks.com/notificationplatform-web/api/queue/list

Sample JSON Body for Phone Call:

[
{
"callReferenceId":"testNotification150912",
"outboundNumber":"18579917607",
"notificationType":1,
"callBackNumber":"16665557777",
"priority":"1",
"messageType":"VXML",
"message":"http://slingshot-stage.surgentnetworks.com/notificationplatform-web/testNVP5AMD.vxml"
}
]

Sample JSON Body for Text Message:

[
{
"callReferenceId":"testNotification150912",
"outboundNumber":"18579917607",
"notificationType":2,
"callBackNumber":"16665557777",
"priority":"1",
"messageType":"SMS",
"message":"Simple SMS test message from Surgent"
}
]

Optional Parameters:
In the sample body above, we add a notification to the accounts default campaign, to be executed right away and without expiration time. There are a few optional parameters we can use to specify more details:

  • executionId: Each notification in the SlingShot system has to be assigned to a campaign execution. Assigning a notification to an execution can be helpful in organizing notifications, but it can also add unnecessary complications. Each customer account has a default campaign. If this optional field is omitted, that default campaign is used. See the full API Documentation for how to create executions.
  • startSchedule: This field can be used to set a specific time, at which the notification should be delivered. Note that at this time, the notification will be added to the delivery queue.
  • endSchedule: This field can be used to make sure that the notification is not delivered after a certain time.

Both date fields use the format defined in RFC3339 (i.e. 2012-10-02T10:00:00-05:00)

Expected Result:

Response Body:

[{"callId":"testNotification150912","result":"ADDED"}]

The result will indicate if there were any problems while adding the notification.

Step 3: Retrieve Result by Id

Once the notification is delivered, use the following call to retrieve the results of the notification:

HTTP method: GET

URL: /notification/cust/{notificationId}

Headers:

  • accept = application/json
  • X-Security-Token={retrieved token}

Sample Call

/GET http://slingshot-stage.surgentnetworks.com/notificationplatform-web/api/notification/cust/testNotification150912

Expected Result:

Response Body: 

[
{
"callId":"1448240515672testNotification150912",
"appId":null,
"callAlertId":"testNotification150912",
"callDate":"2015-11-22T20:02:28-05:00",
"callPriority":1,
"callbackNumber":"16665557777",
"outboundCallNumber":"18579917607",
"requestedCompletionTime":"2022-10-02T11:00:00-04:00",
"requestedStartTime":"2012-10-02T11:00:00-04:00",
"campaignId":null,
"timezone":null,
"results":[
{
"resultId":3440,
"notificationId":"1448240515672testNotification150912",
"timeOfCall":"2015-11-22T20:02:28-05:00",
"callDuration":"4840",
"slingshotResultCode":"200",
"moduleResultCode":null,
"moduleResultMessage":null,
"clientResultMessage":null
}
]
}
]

Security

Every call made to the SlingShot Web Service API must contain a security token as a header parameter (X-Security-Token). Click Security for more information.