Configuring an API Notification for an Alert

Modified on Fri, 03 Mar 2023 at 01:53 PM

Purpose

The SupportLogic Events API is an additional feature that builds on top of the SupportLogic Alerts functionality introduced in June 2020. The Events API sends Alert POST data when a SupportLogic Alert is triggered. 

Summary

To use the Events API:

  1. Confirm users have permissions for both Personal and Shared Alerts
  2. Create an Alert Definition 
  3. Select “Events API” in the Notification Method drop-down
  4. Enter the URL where you want us to POST Alert data and API Key (optional)
  5. From the system receiving the POST return a 200 OK response



Confirm Users Have Permissions

Make sure the SupportLogic user that will create the API Notification Method has permission for creating both Personal and Shared Alerts under Control Center > Manage User section. You can review a more detailed list of permissions in the User Permissions article. 




Create an Alert Definition

Review detailed instructions for creating an Alert in the My Alerts article. When creating the Alert, select the "Events API" option under the Notification Method section (see below).






SupportLogic Events API

The SupportLogic Events API is an additional feature that builds on top of the SupportLogic Alerts functionality introduced in June 2020. The Events API sends Alert POST data when a SupportLogic alert is triggered.  Here are the steps you need to complete to create an Alert using the SupportLogic API:


In SupportLogic:

  1. Create an Alert Definition 
  2. Select “Events API” in the Notification Method section
  3. Specify where you want us to POST Alert data (your target server to receive the alert)
  4. Generate a SupportLogic API Key (if needed by your target server receiving the alert)


As mentioned above, the SupportLogic user must have permission to create Personal and Shared Alerts. See the Managing Users article on how to set user permissions.


In target server:

  1. Handle the SupportLogic API request
  2. Send a return response:  200 OK response


The request must be acknowledged within 3 seconds, and the alert will attempt to deliver before 5 minutes before giving up.


Behavior Caveats

The SupportLogic Events API expects a 200 OK response within 3 seconds. If it does not receive one

the Events API will retry every 5 minutes for 60 minutes. 




Return Response


The return response needs to include:

  1. Your SupportLogic base URL
  2. api/v2/notifications
  3. The UUID for this alert (see the alert_id field in the API Field Reference table below
  4. From the target system, you can send a return response to SupportLogic to mark the Notification as read or unread as long as your system can query and store the uuid for the targeted user for the notification:


Below is an example return response: 


endpoint :: https://<domain>.supportlogic.io/api/v2/notifications/<uuid>?action=[read | unread]
method :: POST




Authentication and Testing

You can set up authentication and generate an API key, if one is needed by your target server, from the Alerts Builder UI. Details on configuring an Alert can be found in the My Alerts article.


1. Enter the POST URL directly into the API entry box.

 

If an API key is required, generate a SupportLogic key first.

2. Enter the POST URL into the API entry, inserting the generated SupportLogic key where appropriate for your system's POST URL syntax.


3. Test the connection to verify the post will be successful (see image below).




Below is the expected results from a successful test:






API Reference with Field References

Below is a Field Reference table with descriptions, examples and requirements. See the example API under that table for a complete syntax example.


Top-Level FieldFieldDescriptionExamplesRequired?
type

The value of this field determines the type of the payload. Only “alert” events will be sent to the endpoint.

alertYes
version
The version of this API is “1.0”.1.0Yes
timestamp

An ISO 8601 timestamp of the time at which the Event was sent. This and all other timestamps include a time zone offset but are always in UTC.

2022-11-15T16:43:55.236ZYes
id

This is the unique UUID4 identifier for the Event object.

5hind4dh6wfmfj1s2qtml8h21u7hwpwkwdYes
payload
This field contains the bulk of the content of the response. Further definitions of its contents are provided below.(see details below)Yes

alert_definition_id


A unique identifier for the Alert Definition that triggered the Alert.

W5LGmsr9K-d4oZLVKSEw3Yes

alert_definition_name

alert_definition_name is the name provided for the Alert within the SupportLogic UI.

Silver Customers Expressing Negative SentimentsYes

alert_id

alert_id is the unique UUID4 identifier of the Alert that sent a POST request to the endpoint.

34vbdk7qz0xehcf9kg77lk2e1s91495z4xYes

sl_case_id

sl_case_id is a human-readable integer case number corresponding to the case. 

54904Yes

sl_crm_idThis is the original ID of the case in the System of Record.5002E00001ZmsNQQAZYes

additional_payloadAdditional payload corresponds to the fields selected in the Payload section of an Alerts definition. Yours may differ from our example.
"additional_payload": {
"sl_assignee_name": "Bobby Thomas",
"sl_need_attention_score": 55,
"sl_created_at": "2020-05-01T00:53:30+00:00",
"sl_category_c": "Browser",
"sl_account_name": "Baltimore Bonkers",
"sl_last_inbound_ms": 1588367477000,
"sl_last_outbound_ms": 1588368489000,
"contains_spans": [
"Very Negative",
"Negative"
],
"sl_op_sys_c": "RHEL Santiago",
"sl_sentiment_score": 32,
"sl_status": "Open"
  }
No

sl_assignee_name

This is the name of the support agent to which the case is currently assigned.

Bobby ThomasNo

sl_account_name

This is the name of the account for the corresponding case in the SupportLogic system according to your System of Record.

Baltimore EmporiumNo

sl_first_escalation_prediction


An ISO 8601 timestamp describing the first time the case was predicted to escalate.2022-11-15T16:43:55.236ZNo

sl_is_escalated

This is the escalation status of the corresponding case.

true | falseNo

sl_is_predicted_to_escalate

A boolean that is true if the case is currently predicted to escalate.

true | falseNo

sl_need_attention_scoreThis is the Need Attention score of the corresponding case. An integer between 0 and 100.55No

sl_sentiment_score

This is the Sentiment Score of the corresponding case. An integer between 0 and 100.

32No

contains_spans

This is a list of the sentiments found in the case . If none were found but this field is defined to be part of the additional payload, it will be empty.

[
"Very Negative",
"Negative"
],
No

message_typeThis is a string value that corresponds to the type of message being evaluated by the alert ("Inbound" | "Outbound" | "Inbound or Outbound").InboundNo

sl_XXXX_XXXAdditional fields may be configured for your instance of SupportLogic.

You can review which are available when configuring an Alert in the SupportLogic UI.
No



For SalesForce, the sl_case_id is the same as the "Case Number" field in SupportLogic. Your CRM may be different, however.



Example JSON Payload

Below is an example JSON payload that is visible from the Alerts builder within SupportLogic under the Preview section. 


{
  "type": "alert",
  "version": "1.0",
  "timestamp": "2022-11-15T16:43:55.236Z",
  "id": "5hind4dh6wfmfj1s2qtml8h21u7hwpwkwd",
  "payload": {
    "alert_definition_id": "W5LGmsr9K-d4oZLVKSEw3",
    "alert_definition_name": "Silver Customers Expressing Negative Sentiments",
    "alert_id": "34vbdk7qz0xehcf9kg77lk2e1s91495z4x",
    "sl_case_id": 54904,
    "sl_crm_id": "5002E00001ZmsNQQAZ",
    "additional_payload": {
      "sl_assignee_name": "Bobby Thomas",
      "sl_need_attention_score": 55,
      "sl_created_at": "2020-05-01T00:53:30+00:00",
      "sl_category_c": "Browser",
      "sl_account_name": "Baltimore Emporium",
      "sl_is_escalated": false,
      "sl_is_predicted_to_escalate": true,
      "sl_last_inbound_ms": 1588367477000,
      "sl_last_outbound_ms": 1588368489000,
      "contains_spans": [
        "Very Negative",
        "Negative"
      ],
      "sl_op_sys_c": "RHEL Santiago",
      "sl_sentiment_score": 32,
      "sl_status": "Open"
    }
  }
}



Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article