The Proactive Notifications API V2 enables sending various types of messages to users via IVR and Hangout channels.
Proactive notification includes:
- Nudge the employees to reset their passwords before it expires in a certain days
- Remind users to submit expense reports.
- Inform customers about their order status.
- Other reminders that are defined.
Note: Webhook Proactive Notifications only support Asynchronous V2.
| Method | POST |
| Endpoint | https://{{host}}/api/public/bot/{{streamId}}/notifyV2 |
| Content Type | application/json |
| Authorization | auth: {{JWT}} |
| API Scope |
|
Path Parameters
| PARAMETER | DESCRIPTION | MANDATE |
| host | The environment URL. For example, https://platform.kore.ai | Required |
| BotId | Bot ID or Stream ID can be accessed under General Settings on the Bot Builder.
Note: This is required only for the Bot Builder API scope of Proactive Messages. |
Required |
Sample Request
Static Text Message
Sends a non-personalized message to multiple users.
{ "channel": "ivr", "webhookInstanceName": "Webhook", "userIdentityType": "resolve", "content": { "type": "text", "value": "Hello! Your order has been shipped. Track it using the provided details." }, "identities": [ { "email": "user1@example.com" }, { "email": "user2@example.com" } ] }
Channel-Specific Adjustments:
hangoutchat:
"identities": [ { "spaceId": "AAQAPWibMjE" }, { "spaceId": "o7ZNt8AAAAE" } ]
Custom Message
Sends a personalized message if customMessage is specified, else uses the main message.
{ "channel": "ivr", "webhookInstanceName": "Webhook", "userIdentityType": "resolve", "content": { "type": "text", "value": "Hello! Your order has been shipped." }, "identities": [ { "email": "user@example.com", "customMessage": "Hi John, your package is on the way!" }, { "email": "user@example.com" } ] }
Channel-Specific Adjustments:
hangoutchat:
"identities": [ { "spaceId": "AAQAPWibMjE", "customMessage": "Hi John, your package is on the way!" }, { "spaceId": "o7ZNt8AAAAE" } ]
Parameterized Message
Personalizes the message using dynamic parameters.
{ "channel": "ivr", "webhookInstanceName": "Webhook", "userIdentityType": "resolve", "content": { "type": "text", "value": "Hello {name}! Your reference number is {refId}." }, "identities": [ { "email": "user@example.com", "parameters": { "name": "Charlie", "refId": "XYZ-789" } }, { "email": "user@example.com", "parameters": { "name": "Diana", "refId": "UVW-012" } } ] }
Channel-Specific Adjustments:
hangoutchat:
"identities": [ { "spaceId": "AAQAPWibMjE", "parameters": { "name": "Charlie", "refId": "XYZ-789" } }, { "spaceId": "o7ZNt8AAAAE" }
]
Template-Based Message
Uses templates with optional parameter substitution.
{ "channel": "ivr", "webhookInstanceName": "Webhook", "userIdentityType": "resolve", "content": { "type": "template", "value": "Hello {name}, your order ID is {orderId}." }, "identities": [ { "email": "user@example.com", "parameters": { "name": "Alice", "orderId": "ABC-123" } }, { "email": "user@example.com", "parameters": { "name": "Bob", "orderId": "DEF-456" } } ] }
Channel-Specific Adjustments:
hangoutchat:
"identities": [ { "spaceId": "AAQAPWibMjE", "parameters": { "name": "Charlie", "orderId": "XYZ-789" } }, { "spaceId": "o7ZNt8AAAAE" } ]
Body Parameters
| Field | Type | Required / Optional | Description |
| channel | string | Required | Platform to send message to (e.g., ivr, hangouts) |
| webhookInstanceName | string | Optional | Name of the webhook instance, applicable only for ivr channel |
| userIdentityType | string | Optional | Identity resolution logic, e.g., resolve |
| message | object | Required | Message object containing message type and content |
| message.type | string | Required | Message format (e.g., text, template, script) |
| message.value | string or json | Required | Actual message content to send |
| identities | array | Required | List of recipient identity objects |
Identities Array
| identity field | string | Required | Identity key depending on the channel:- ivr: email– hangouts: spaceId Note: Other channels (e.g., whatsapp, msteams, slack) are not yet supported in public API v2 |
| customMessage | string | Optional | Overrides the default message for this recipient. Supports placeholders like {name}, {refId} |
| parameters | object | Optional | A key-value map where each key corresponds to a placeholder in the customMessage.These values dynamically replace the placeholders when sending the message.If no customMessage is provided, this field is ignored for that identity. |
Sample Response
{ "_id": "ds-d0f6fed2-87ff-52b7-bf2b-a15216f0a563", "streamId": "st-736ff917-d836-55b4-9a6b-3dad20c09af3", "jobType": "PROACTIVE_NOTIFICATIONS_API", "action": "PROACTIVE_NOTIFICATIONS", "status": "IN_PROGRESS", "statusLogs": [], "percentageComplete": 0, "store": { "identitiesCount": 2 }, "createdBy": "u-ecff03e8-ba90-532e-ab7b-209082d91936", "lMod": "2025-05-22T05:37:56.000Z", "countOfDockStatuses": 1, "createdOn": "2025-05-22T05:37:56.693Z", "requestedTime": "2025-05-22T05:37:56.693Z", "__v": 0 }