Engagespot API (3.0.0)
Our REST API allows you to send notifications to users on your app, and to do actions like Fetch Notifications, Delete Notification etc on behalf of them.
This API should be authenticated in two ways.
Authenticate using API-KEY and API-SECRET
This mode is required when you want to authenticate as your Engagespot app and send a notification to one or more recipients. The credentials can be found in your Engagespot dashboard.
Authenticate using API-KEY and USER-ID
This mode should be used when you want to authenticate as your user and want to perform actions on behalf of them. For example, reading the notification inbox of a user, deleting a notification from a user's inbox etc.
These authentication parameters should be passed via headers.
Header Parameter | Description |
---|---|
X-ENGAGESPOT-API-KEY | Your Engagespot API Key. You can see this on your Engagespot dashboard. |
X-ENGAGESPOT-API-SECRET | Your Engagespot API Secret. You can see this on your Engagespot dashboard. You should never use this secret on any front-end apps. |
X-ENGAGESPOT-USER-ID | Your user's unique identifier such as their email id that you used to register them on Engagespot. |
X-ENGAGESPOT-USER-SIGNATURE | This is optional. You need this param only if you have turned on HMAC Authentication for your app in Engagespot Dashboard. Your user's HMAC signature can be generated in your server as follows - createHmac('sha256', Your_API_Secret).update(user_Id, 'utf8').digest('base64'); |
/notifications
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx Your Engagespot app's api key which can be found in your dashboard. |
X-ENGAGESPOT-API-SECRET required | string Example: 7rd9fahc6f5tam9ccdrig3h7j15b6cd0jc79708d4814j7ia Your Engagespot app's api secret which can be found in your dashboard. |
Request Body schema: application/json
required | object |
recipients required | Array of strings Unique id's of your users to send this notification to. Read Who is a User? |
category | string Category identifier to tag this notification. If category specified doesn't exist, it will be created. For templated notifications, no need to use this field because category can be specified when you create the template using Engagespot dashboard. |
data | object Add any key value pair or meta data to be passed along with this notification. This will also be used to replace the placeholders (if you're using templates) |
object Override delivery preferences configured in your account. |
Responses
Request samples
- Payload
{- "notification": {
- "title": "Rose accepted your friend request"
}, - "recipients": [
- "bd8b8a66-7c76-4a97-a2e0-f85f2f450e7e"
], - "data": {
- "optional": "meta data"
}, - "override": {
- "channels": [
- "email",
- "webPush",
- "mobilePush",
- "inApp",
- "sms",
- "whatsapp",
- "slack"
]
}
}
/notifications
This API returns list of notifications for the given user.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
string |
Responses
Response samples
- 200
{- "unreadCount": 0,
- "pagination": {
- "totalCount": 0
}, - "data": [
- {
- "id": 0,
- "title": "string",
- "message": "string",
- "icon": "string",
- "data": { },
- "createdAt": "string",
- "seenAt": "string",
- "clickedAt": "string"
}
]
}
/notifications/:notificationId
Gets the details of a notification. This will also mark the notification as seen
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
Responses
/markAllNotificationsAsSeen Deprecated
Marks the first 15 unseen notifications as seen
for the given user.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
Responses
/notifications/:id/click
Marks a notification as clicked.
path Parameters
id required | integer Example: 428152 Notification ID |
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
Responses
/notifications/:id/views
Marks a notification as Unseen.
path Parameters
id required | integer Example: 428152 Notification ID |
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
Responses
/notifications/:id/reads
Marks a notification as Unread.
path Parameters
id required | integer Example: 428152 Notification ID |
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
Responses
/notifications/:id
Deletes a notification
path Parameters
id required | integer Example: 428152 id of notification to be deleted. |
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
Responses
/profile
Sets one or more key value pairs to User's profile. This method expects array of JSON Patch rules as mentioned in JSON Patch syntax to do complex operations the existing user object.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: jYt501jhd736hcbcGt34D6HyCxdFrEhkskpurgs36bbK6Xxzl1Lp Required If HMAC Authentication is Turned On for your app. |
Request Body schema: application/json
JSON Patch Operation as mentioned in JSON Patch
Responses
Request samples
- Payload
[
]
/profile
Sets one or more key value pairs to User's profile. Simply pass the JSON profile object of the user, and we'll update the existing profile.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: jYt501jhd736hcbcGt34D6HyCxdFrEhkskpurgs36bbK6Xxzl1Lp Required If HMAC Authentication is Turned On for your app. |
Request Body schema: application/json
Key value pairs for the user's profile
Responses
Request samples
- Payload
{- "name": "Jack",
- "email": "[email protected]"
}
/preferences
Set notification delivery preference on notification categories and channels.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER_SIGNATURE Required If HMAC Authentication is Turned On |
Request Body schema: application/json
required | Array of objects | ||||
Array
|
Responses
Request samples
- Payload
{- "preference": [
- {
- "categoryId": 1,
- "channels": [
- {
- "channel": "inApp",
- "enabled": true
}
]
}
]
}
/categories
Lists all categories in the app.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
Responses
Response samples
- 200
[- {
- "id": 0,
- "name": "string",
- "identifier": "string"
}
]
/categories
Create a new category.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-SECRET-KEY required | string Example: Ht410rCJ09Hy8Uyzwpsm6s4jjqmlx |
Request Body schema: application/json
identifier required | string A unique identifier for the new category (Example - comment_replies) |
name required | string A name for the new category (Example - Comment Replies). This will be shown to your users. |
Responses
Request samples
- Payload
{- "identifier": "string",
- "name": "string"
}
Response samples
- 200
{- "id": 0,
- "name": "string",
- "identifier": "string"
}
/sdk/connect
API to authenticate your app user with Engagespot. This API is called from every front-end SDK's initialization step. If you're using a front-end platform that do not have a native SDK support from Engagespot, you can simply use this API.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-USER-ID required | |
X-ENGAGESPOT-DEVICE-ID required | string Example: Any value Any unique id to identify your user's device / app installation. |
X-ENGAGESPOT-USER-SIGNATURE | string Example: USER-SIGNATURE Required If HMAC Authentication is Turned On |
Request Body schema: application/json
deviceType required | string Should be any value from - "browser", "android", "ios" |
Responses
Request samples
- Payload
{- "deviceType": "string"
}
Response samples
- 200
{- "unreadCount": 0,
- "app": {
- "id": "string",
- "categories": [
- {
- "id": 0,
- "name": "string"
}
]
}
}
/users
API to create a new user
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-API-SECRET required | string Example: Xt41rizwprizwpqmlxkriZwpk7huInx |
Request Body schema: application/json
identifier required | string Any identifier to uniquely identify your user. |
profile | object Any key value pair that will be attached to the user's profile |
Responses
Request samples
- Payload
{- "identifier": "string",
- "profile": { }
}
/users/:identifier
Create or update a User with profile data
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-API-SECRET required | string Example: Xt41rizwprizwpqmlxkriZwpk7huInx |
Request Body schema: application/json
Any key value pair to be attached to this user's profile
Responses
Request samples
- Payload
{ }