Back to API List

Proactive Notifications API v2

The Proactive Notifications API V2 enables sending various types of messages to users via IVR, Hangout, Webhook and Whatsapp 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	App Builder: Proactive Messages Admin Console: Channel Management > Proactive Messages

Refer How to generate the JWT Token.

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 App Builder. Note: This is required only for App 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": "AAQAPWixxxx" },
  { "spaceId": "o7ZNt8Axxxx" }
]

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": "AAQAPWixxxx", "customMessage": "Hi John, your package is on the way!" },
  { "spaceId": "o7ZNt8Axxxx" }
]

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": "AAQAPWixxxx", "parameters": { "name": "Charlie", "refId": "XYZ-789" } },
  { "spaceId": "o7ZNt8Axxxx" }
]

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": "AAQAPWixxxx", "parameters": { "name": "Charlie", "orderId": "XYZ-789" } },
  { "spaceId": "o7ZNt8AAxxxx" }
]

whatsapp:

{
    "channel": "whatsapp",
    "userIdentityType": "resolve",
    "message": {
        "type": "template",
        "value": {
            "type": "image",
            "image": {
                "link": "https://imagej.net/images/2D_Gel.jpg",
                "caption": "Random Image"
            }
        }
    },
    "identities": [
        {
            "phoneNumber": "91xxxxxxx4"
        }
    ]
}

Body Parameters

Field	Type	Required / Optional	Description
channel	string	Required	Name of the channel for which notifications to be sent (e.g., ivr, hangouts and whatsapp)
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, and whatsapp: phone number Note: Other channels (e.g., 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.

Schema Constraints

• identities array:

  • Minimum items: 1

  • Maximum items: 1000

• parameters object:

  • Maximum properties: 20

  • Each value must be a string ≤ 200 characters

• No additional properties are allowed at any level unless explicitly defined.

Sample Response

{
   "_id": "ds-d0f6fed2-87ff-52b7-bf2b-a15216f0xxxx",
   "streamId": "st-736ff917-d836-55b4-9a6b-3dad20c0xxxx",
   "jobType": "PROACTIVE_NOTIFICATIONS_API",
   "action": "PROACTIVE_NOTIFICATIONS",
   "status": "IN_PROGRESS",
   "statusLogs": [],
   "percentageComplete": 0,
   "store": {
       "identitiesCount": 2
   },
   "createdBy": "u-ecff03e8-ba90-532e-ab7b-209082d9xxxx",
   "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
}

Send Feedback