Send Notification API
Allows users to send push notifications to respondents via API.
Request information
method="POST"
must be done over https
POST URL format: https://<branded_instance>/reactor-webapp/pt/<project_name>/pn/lumicompass/api/send_notifications
URL parameters
<branded_instance>
The first word of your Dashboard URL, e.g. "dashboard"
<project_name>
You can find this at the top right corner of your dashboard, please note this field is case sensitive
Parameters
|
Name |
Value |
Description |
Required |
|
user_name |
String |
A valid backend user's credentials |
Yes |
|
password |
String |
A valid backend user's credentials |
Yes |
|
respondents_json |
String |
A JSON String containing the participant data. See below. |
No* |
JSON Format
{"company_id":"","survey_id":"","group_id":"","message":"","respondents":[ {"username":"r1"}, {"username":"r2"}, ...]} |
|
Parameter |
Value |
Description |
Required |
|
company_id |
Integer |
The id of the company the respondents belong to. |
No, but the API call will fail if the user has access to more than one company and this variables has not been specified |
|
survey_id |
Integer |
If specified the API will send a notification to all respondents belonging to this survey. |
No* |
|
group_id |
Integer |
If specified the API will send a notification to all respondents belonging to this group. |
No* |
|
message |
String |
The custom message to send to the respondents |
No, if not specified the default "A new survey has been added for you" notification will be sent (translated according to the respondents language) |
|
respondents |
Json Array |
Container for the respondent data |
Yes |
|
username |
String |
Respondent id/username |
Yes |
*) One of these parameters have to be specified. If more than one is specified, the system will prioritise in the following order: "respondents_json", "group_id", "survey_id"
Responses
HTTP error responses that are implemented
|
Response |
Message |
Reason |
|
HTTP 400 |
Action not supported |
Not a POST request |
|
HTTP 403 |
Not supported |
Not using HTTPS |
JSON responses are given if the request passes the initial validation (i.e. if the HTTP errors do not apply)
Format: {"message":"","status":""}
Where message will contain a descriptive message string, and status is either "ok" if the upload succeeded or "error" if it failed.
|
Status |
Message |
Reason |
|
ok |
API sent notifications to <number_of_respondents> respondents |
Success message. |
|
error |
Error missing required parameter. |
One of user_name/password is missing. |
|
error |
Authentication failure. |
Failed to authenticate with given credentials. |
|
error |
Could not parse json parameter as a JSONObject. |
Parse error when parsing the respondents_json - not valid Json string |
|
error |
Could not validate respondents. Could not fetch respondent list. |
Error when fetching respondents from storage. |
|
error |
Could not validate respondents. Respondent(s) does not exist! (...) |
Failed because listed respondents were not found in storage. |
|
error |
No respondents found in group <group_id> please check the group id. |
Failed because no respondents found in specified group id, possibly group does not exist. |
|
error |
No respondents assigned to survey <survey_id>, please check the survey id. |
Failed because no respondents found in specified survey_id, possibly survey id does not exist. |
|
error |
No survey id, group id or respondents specified! |
Missing parameter survey_id, group_id or respondents_json. |
|
error |
PushNotification API Could not sent standard notification to respondents |
Storage exception on server. |
|
error |
PushNotification API Could not sent customer "message" notification to respondents |
Storage exception on server. |