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 can be authenticated in three ways.
1. Authenticate using API-KEY and API-SECRET (For your backend)
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 console.
2. Authenticate using API-KEY and USER-ID (For Inbox)
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.
3. Authenticate using Bearer Token (For Inbox - Secure Mode)
This mode is for the same purpose as above. But uses a JWT Token in Auth Bearer header for increased security.
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 console. |
X-ENGAGESPOT-API-SECRET | Your Engagespot API Secret. You can see this on your Engagespot console. 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. Required for authenticating inbox APIs |
Authentication Bearer Token | Use a token for your users and sign them using your secret signing key generated from Engagespot console. This method must be used for authenticating inbox in production apps. Read more. |
X-ENGAGESPOT-USER-SIGNATURE Deprecated |
This is optional. You need this param only if you have turned on HMAC Authentication for your app in Engagespot console. This method is now deprecated. If you want to enable high security for inbox APIs, use JWT Auth instead |
Engagespot uses HTTP response codes to indicate the success or failure of an API request.
- Codes in the
2xx
range indicate success. - Codes in the
4xx
range indicate an error with your request. - Codes in the
5xx
range indicate an error with Engagespot server. Please contact support if you encounter this.
Handling Errors
Along with the HTTP Response, the body will contain the details of error. Usually, the format is
Authentication Errors
This will be the format of 401
errors, usually represents an issue with auth credentials.
{
"status": "error",
"message": "No auth params (or combination of params) were found in the request"
}
Validation Errors
This will be the format of 400
errors, usually represents an issue with the request.
{
"status": "error",
"message": [
"notification must be an object"
]
}
Notification is the entity that represents an information that you need to send to a recipient. Engagespot provides API to send, read and manage notifications. Please note that, the permission levels required for each API might be different. For example, to send notification, you will need to authenticate as an app, with your secret Key. But to read and manage notifications on behalf of your users, you should authenticate as the User.
Send notification
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx Your Engagespot app's api key which can be found in your console. |
X-ENGAGESPOT-API-SECRET required | string Example: 7rd9fahc6f5tam9ccdrig3h7j15b6cd0jc79708d4814j7ia Your Engagespot app's api secret which can be found in your console. |
Request Body schema: application/json
required | object |
recipients | Array of strings Deprecated Deprecated. Use |
required | object |
object Override delivery preferences configured in your account. |
Responses
Request samples
- Payload
- Node.js
- PHP
{- "notification": {
- "templateIdentifier": "new_friend_request"
}, - "sendTo": {
- "recipients": [
- "bd8b8a66-7c76-4a97-a2e0-f85f2f450e7e"
]
},
}
Response samples
- 202
- 400
- 401
{- "requestId": "9d9fca81-a5e6-4ff6-8024-94cc0dffe9a1"
}
List all notifications for a user
This API returns list of notifications for the given user.
query Parameters
pageNo | string Example: pageNo=1 Required for pagination |
limit | string <= 20 Example: limit=15 How many notifications should be returned in a single page. |
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
Responses
Request samples
- cURL
- Javascript
curl --location 'https://api.engagespot.co/v3/notifications' \ --header 'X-ENGAGESPOT-API-KEY: your-api-key' \ --header 'X-ENGAGESPOT-USER-ID: unique-user-id' \
Response samples
- 200
{- "unreadCount": 0,
- "pagination": {
- "totalCount": 0
}, - "data": [
- {
- "id": 7483759,
- "title": "Hey, you have a new notification!",
- "message": "Let's connect!",
- "icon": "string",
- "url": "string",
- "data": {
- "friend_request_id": "4748-284759-4859"
}, - "blocks": [
- { }
], - "createdAt": "2024-01-26T04:11:50.107Z",
- "seenAt": "2024-01-26T04:11:50.107Z",
- "clickedAt": "2024-01-26T04:11:50.107Z"
}
]
}
Retrieve a notification
Retrieves the notification object based on its id
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
Responses
Response samples
- 200
{- "id": 13952659,
- "title": "Agent X has sent you a friend request",
- "message": "Hey, let's connect!",
- "icon": "string",
- "url": "string",
- "blocks": [
- { }
], - "data": {
- "friend_request_id": 4859902
}, - "createdAt": "2024-01-28T10:37:18.302Z",
- "seenAt": "2024-01-28T10:37:18.302Z",
- "clickedAt": "2024-01-28T10:37:18.302Z"
}
Delete a notification
Deletes a notification by its id
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 | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
Responses
Response samples
- 200
{- "statusCode": 200,
- "message": "Notification deleted successfully"
}
/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 | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
Responses
Mark notification as read
Marks a notification as read.
path Parameters
id required | integer Example: 428152 Notification ID |
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: shiynklpz18l3ktqyy6d9a |
X-ENGAGESPOT-USER-ID required | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
Responses
Mark notification as unseen
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 | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
Responses
Mark notification as unread
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 | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
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 | string Example: unique-user-identifier |
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
[- {
- "op": "replace",
- "path": "/email",
- "value": "jack@titanic.com"
}
]
/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 | string Example: unique-user-identifier |
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": "jack@titanic.com"
}
/profile
Gets a user's profile.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-USER-ID required | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
Responses
/preferences
Gets a user's profile.
header Parameters
X-ENGAGESPOT-API-KEY required | string Example: at410rizwpsm6s4jjqmlx |
X-ENGAGESPOT-USER-ID required | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
Responses
/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 | string Example: unique-user-identifier |
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 | string Example: unique-user-identifier |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
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 | string Example: unique-user-identifier |
X-ENGAGESPOT-DEVICE-ID required | string Example: Any value Any unique id to identify your user's device / app installation. |
Authentication Bearer | string This header is required if you have enabled secure mode for your Engagespot app. The JWT token for your user, generated from your backend using the secret signing key. |
X-ENGAGESPOT-USER-SIGNATURE | string Deprecated Example: USER-SIGNATURE For secure mode, use |
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
{ }