How to use the Sapho API to get notifications anywhere

Last update:

 Audience: Sapho app creator

There are situations in which you may want to allow employees to receive notifications in another system without having to log into Sapho.

You can now leverage our public REST API to integrate notifications from Sapho into any system. Our public API provides information about all important user-related events. The event notifications can be sorted and/or filtered by relevance or a specified timeframe.

The Sapho public API can be enabled or disabled, and it can be accessed with a secure API key.

 

1. Enable/disable events notification API


Public API access is not enabled by default. If you want to start using it, you will need to enable it first.

To enable API access, go to Publish -> Endpoints -> Desktop & Intranet -> API. Once in API, use the toggle switch to turn on Events Notification API for your Home app.

All micro apps that are available in your Home app (listed in the On Home column of your micro apps list) have the Events Notification API enabled by default, but this can be disabled by turning the toggle switch off.

The API key is generated and displayed in API configuration details. It is immutable, so if you disable and then re-enable the API, the API key will remain the same.

api_1.png

 

2. Get events notifications

To start receiving events notifications, you need to have at least one micro app published and available in Home app. If you do not have any, we recommend creating a sample micro app with sample data. Please make sure you have the On Home toggle switched on. Both your new micro app and Home app must be published in order to correctly complete your set up.

api_2.png

API call example:

curl 'http://localhost:8191/sapho/api/public/v1/events/user-feed?apiKey=1fbe80e7-49c2-4b26-bf14-fedb1836b871&limit=2&userEmail=john.doe%40acme.com'


The example above will retrieve the first 2 cards for the user whose email is john.doe@acme.com

API response payload:

{
"data" : [ {
"id" : 22,
"created" : "2018-01-16T19:55:52Z",
"title" : "New Approve Request",
"body" : "The approval request for \"CHG0001005 - Need assistance with local installation\" was submitted by Hjalte Frederiksen.",
"relevance" : 0,
"notificationId" : 11,
"notificationLabel" : "New Approve Request",
"appTitle" : "ServiceNow Approve",
"appThumbUrl" : "api/content/91.png",
"link" : "http://localhost:8191/sapho/renderer?appid=8&initiator_type=FEED&initiator_notification_id=11&pageid=3sxEmwnI&initiator_record_id=6"
}, {
"id" : 21,
"created" : "2018-01-16T19:55:52Z",
"title" : "New Approve Request",
"body" : "The approval request for \"CHG0001018 - Trouble accessing client environment\" was submitted by Stella Milne.",
"relevance" : 0,
"notificationId" : 11,
"notificationLabel" : "New Approve Request",
"appTitle" : "ServiceNow Approve",
"appThumbUrl" : "api/content/91.png",
"link" : "http://localhost:8191/sapho/renderer?appid=8&initiator_type=FEED&initiator_notification_id=11&pageid=3sxEmwnI&initiator_record_id=19"
} ],
"_metadata" : {
"totalCount" : 11,
"offset" : 0,
"limit" : 2
},
"_links" : {
"self" : "http://localhost:8191/sapho/api/public/v1/events/user-feed?offset=0&limit=2",
"next" : "http://localhost:8191/sapho/api/public/v1/events/user-feed?offset=2&limit=100",
"export" : "http://localhost:8191/sapho/api/public/v1/events/user-feed?"
}
}

 

3. Dismiss events notifications

It is also possible to dismiss event notifications from your Sapho feed using the Sapho public API. You can do this by calling HTTP DELETE method on the

/sapho/api/public/v1/events/user-feed/{cardId}

endpoint and specifying cardId as a parameter.

API call example:

curl -X DELETE 'http://localhost:8191/sapho/api/public/v1/events/user-feed/card/21?apiKey=1fbe80e7-49c2-4b26-bf14-fedb1836b871&limit=2&userEmail=john.doe%40acme.com'

A successful API call will return an HTTP response 200 OK with no response payload.

 

4. Undo dismiss events notifications

It is also easy to recall a dismissed notification by calling the Sapho REST API endpoint

/sapho/api/public/v1/events/user-feed/{cardId}/undo

 with the HTTP DELETE method if a user changes their mind.

API call example:

curl -X DELETE 'http://localhost:8191/sapho/api/public/v1/events/user-feed/card/21/undo?apiKey=1fbe80e7-49c2-4b26-bf14-fedb1836b871&limit=2&userEmail=john.doe%40acme.com'

A successful API call will return a HTTP response 200 OK with no response payload.

 

API documentation

You can find full public API documentation here.