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 plus button to create your new public API key for chosen API(s).

Screen_Shot_2018-05-21_at_13.24.14.png

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. API key can be disabled by turning the toggle switch off or revoked by clicking delete icon.

The API key is generated and displayed in the green information box.Make sure to copy your API key now. You will not be able to see it again. You can see your newly created API key with listed APIs enabled for this key in the list.

api_keys.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 -H 'Authorization: Bearer 1fbe80e7-49c2-4b26-bf14-fedb1836b871' 'http://localhost:8191/sapho/api/public/v1/events/user-feed?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 -H 'Authorization: Bearer 1fbe80e7-49c2-4b26-bf14-fedb1836b871' -X DELETE 'http://localhost:8191/sapho/api/public/v1/events/user-feed/card/21?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-H 'Authorization: Bearer 1fbe80e7-49c2-4b26-bf14-fedb1836b871' -X DELETE 'http://localhost:8191/sapho/api/public/v1/events/user-feed/card/21/undo?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.