Subscribing to Notifications
Establishes a subscription to notifications of a given type or types for a given user or users, with a given callback URL and optional associated parameters.
Once a subscription has been created, relevant notifications will be provided via an invocation of the given callback URL. Cogito will invoke the callback URL by making a POST request, providing any parameters associated with the subscription as HTTP request headers, and providing the notification in the request body in the form of a JSON object as described in Notification Event JSON Objects.
E.g., if a subscription is established with:
- "https://myserver.com/my/endpoint" as the callback URL;
- "token=JIUzUxMiJ9.eyJzdWIiOiJwZXJmVGV&intent=Cogito"as request parameters;
- "UserData: myData" as a request header;
A typical invocation of the callback to provide a notification would make an HTTPS connection to myserver.com and send a POST request to /my/endpoint with the following headers:
token: JIUzUxMiJ9.eyJzdWIiOiJwZXJmVGV
intent: Cogito
UserData: myData
Content-Type: application/json
and the following JSON data in the request body:
{“subscriptionId”: 123, “notification”: {"id":"adbce960-4d47-4d42-8fd5-52f70d867412", "time":1603158961452,"ver":"1.0",
"type":"lowEnergyAgentOpened","payload":{"callId":"TestCall-12a86f31-a569-4873-a121-b5137aca721d","username":"testAgent","bTime":21648,"nTime":35912,"idx":0}}}
If an error occurs while attempting to invoke the callback URL, the error will be logged, but the attempt will not be retried with that notification. If three consecutive attempts to invoke the callback fail, then the subscription will be automatically terminated.
The Caller may update the parameters associated with a subscription by calling the Update Subscription Authentication Token API method. The updated parameters will be sent in subsequent callback URL invocations.
Only one subscription may exist for a given user, notification type, and callback URL at any one time.Typically, if such a subscription already exists, an attempt to create a new subscription for the same user, notification type, and callback URL will result in a
409 Conflicterror. However, as discussed below, if therecreateIfExistsparameter is provided in the request with a value of true, then any such existing subscription will be automatically deleted before creating the requested new subscription.
When a subscription includes multiple notification types and/or users, then only a subscription exactly matching those notification types and users will be considered as a duplicate, and hence subject to the delete and recreate logic described above if the recreateIfExists parameter is provided in the request. If an attempt is made to create a subscription that partially matches an existing subscription, then that attempt will always result in a 409 Conflict error, even if the recreateIfExists parameter is provided in the request.
E.g., if a create subscription request is made with:
- notification_type = "behavioral,call-score,conversation-ai";
- username = "agent_1,agent_2,agent_3";
- callback_url = "/my/url";
Then a single subscription will be created and /my/url will be called any time Cogito has either a behavioral notification or a call score notification, or a conversation ai notification update to provide for agent_1, agent_2, or agent_3.
Assume then that a second create subscription request is made with:
- notification_type = "behavioral,call-score,conversation-ai";
- username = "agent_1,agent_2,agent_4";
- callback_url="/my/url";
I.e., this subscription partially matches the existing subscription, as it is for agent_1, agent_2, and agent_4 instead of agent_1, agent_2, and agent_3. Even if the recreateIfExists parameter is provided, the existing subscription cannot simply be deleted and replaced with the new subscription, since they are not identical subscriptions. The new subscription cannot be created alongside the existing subscription either, since that would cause two subscriptions for the same notification type and callback URL for users agent1 and agent2, which is not allowed.
Hence, this second create subscription request will fail with a 409 Conflict error.
Endpoint
POST /api/subscriptions
Headers
| Name | Required | Description |
|---|---|---|
Authorization | required | If Basic Authentication is being used, then header value must be of the form Basic <encoded_data>, where <encoded_data> is the Base64 encoding of the username and the password joined by a colon. If JWT authentication is being used, then header value must be of the form Bearer , where is the JWT obtained via the get authentication token method described earlier. |
Content-Type | required | application/x-www-form-urlencoded |
<header name> | optional | An optional header name/value pair to be associated with the subscription. Any number of additional optional headers may be specified. These headers will be echoed back as request headers when invoking the callback URL. Any headers to be interpreted in this way must be specified in the cogito.subscriptions-webhook.subscribeHeaderParams section of the DAS config. |
Body Parameters
| Name | Required | Type | Description |
|---|---|---|---|
notification_type | required | string | Can be behavioral, call-score and conversation-ai. A subscription to multiple notification types may be created by listing all the required types separated by a comma, e.g., behavioral,call-score,conversation-ai |
username | required | string | The Cogito username of the user for whom notifications are desired. A subscription may be created for multiple users by listing the usernames separated by commas, e.g., agent1,agent2,agent3 |
callback_url | required | string | The URL to be invoked when Cogito has a notification relevant to this subscription to provide |
recreateIfExists | optional | boolean | If true, and a subscription already exists for the given user(s), notification type(s), and callback URL, the existing subscription will be deleted and a new one created. If false, then a 409 Conflict error will be returned in this situation. |
<parameter name> | optional | string | An optional parameter name/value pair to be associated with the subscription. Any number of additional optional parameters may be specified. These parameters will be sent as HTTP request headers when invoking the callback URL. |
Request Example
Example 1 - Basic Authentication
curl --request POST 'https://notifications.cogito.us/api/subscriptions' \
--header 'Authorization: Basic dGVzdDp0ZXN0' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'UserData: myData' \
--data-urlencode 'notification_type=behavioral'
--data-urlencode 'username=testuser'
--data-urlencode 'callback_url=https://myserver.com/my/endpoint'
--data-urlencode 'recreateIfExists=true'
--data-urlencode 'token=JIUzUxMiJ9.eyJzdWIiOiJwZXJmVGV'
--data-urlencode intent=Cogito'
Example 2 - JWT Authentication
curl --request POST 'https://notifications.cogito.us/api/subscriptions' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJwZXJmVGVzdEFnZW50XzIwIiwiZXhwaXJ' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'UserData: myData' \
--data-urlencode 'notification_type=behavioral'
--data-urlencode 'username=testuser'
--data-urlencode 'callback_url=https://myserver.com/my/endpoint'
--data-urlencode 'recreateIfExists=true'
--data-urlencode 'token=JIUzUxMiJ9.eyJzdWIiOiJwZXJmVGV'
--data-urlencode intent=Cogito'
Response Example
A successful response will return HTTP Status 201 Created with a JSON body consisting of a unique subscription ID, which must be provided to the Unsubscribe method in order to terminate the subscription.
{
"subscription_id": 123
}
If a subscription for the same notification type, user, and callback URL already exists, and the recreateIfExists parameter is not provided or is false, then a 409 Conflict error will be returned.
Updated over 1 year ago