Proactive Notifications API v2

Back to API List Sends various types of messages to users via IVR, Google Chat, Webhook,msteam, and WhatsAppchannels. Use cases include:

Nudge employees to reset their passwords before expiry.
Remind users to submit expense reports.
Inform customers about their order status.
Send other defined reminders.

Webhook Proactive Notifications only support Asynchronous V2.

Field	Value
Method	POST
Endpoint	`https://{{host}}/api/public/bot/{{streamId}}/notifyV2`
Content Type	`application/json`
Authorization	`auth: {{JWT}}` — See How to generate the JWT Token.
API Scope	App Builder: Proactive Messages; Admin Console: Channel Management > Proactive Messages

Path Parameters

Parameter	Required/Optional	Description
`host`	Required	The environment URL. For example, `https://platform.kore.ai`
`BotId`	Required	Bot ID or Stream ID. Accessible under General Settings on the App Builder. Note: Required only for App Builder API scope of Proactive Messages.

Sample Requests

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 adjustment for Google Chat:

"identities": [
  { "spaceId": "AAQAPWixxxx" },
  { "spaceId": "o7ZNt8Axxxx" }
]

Custom Message — Sends a personalized message if customMessage is specified; otherwise 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" }
  ]
}

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" } }
  ]
}

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" } }
  ]
}

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"
        }
    ]
}

MS-Teams:

{
    "channel": "msteams",
    "userIdentityType": "resolve",
    "message": {
      "type": "template",
      "value": {
        "type": "message",
        "attachments": [{
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": {
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "type": "AdaptiveCard",
            "version": "1.0",
            "body": [
              { "type": "TextBlock", "text": "Hello from Kore API", "wrap": true, "size": "medium", "weight": "bolder" },
              { "type": "Image", "url": "https://raw.githubusercontent.com/OfficeDev/Microsoft-Teams-Adaptive-Card-Samples/refs/heads/main/samples/recipe/assets/recipe_image.png", "size": "stretch", "altText": "recipe" }
            ]
          }
        }]
      }
    },
    "identities": [{ "email": "john.do@example.com"}]
  }

Body Parameters

Field	Type	Required/Optional	Description
`channel`	`string`	Required	Name of the channel for notifications (for example, `ivr`, `hangouts`, `whatsapp`,`msteams`)
`webhookInstanceName`	`string`	Optional	Name of the webhook instance. Applicable only for the `ivr` channel.
`userIdentityType`	`string`	Optional	Identity resolution logic (for example, `resolve`).
`message`	`object`	Required	Message object containing message type and content.
`message.type`	`string`	Required	Message format: `text`, `template`, or `script`.
`message.value`	`string` or `json`	Required	Actual message content to send.
`identities`	`array`	Required	List of recipient identity objects.

Identities Array

Field	Type	Required/Optional	Description
identity field	`string`	Required	Identity key depending on the channel: `ivr` uses `email`, `hangouts` uses `spaceId`, `whatsapp` uses `phoneNumber`. Note: Other channels (for example, `msteams`, `slack`) aren’t yet supported in public API v2.
`customMessage`	`string`	Optional	Overrides the default message for this recipient. Supports placeholders like `{name}`, `{refId}`.
`parameters`	`object`	Optional	Key-value map where each key corresponds to a placeholder in `customMessage`. If no `customMessage` is provided, this field is ignored for that identity.

Schema Constraints

identities array: minimum 1 item, maximum 1000 items.
parameters object: maximum 20 properties; each value must be a string of 200 characters or fewer.
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
}

​Path Parameters

​Sample Requests

​Body Parameters

​Identities Array

​Schema Constraints

​Sample Response

Path Parameters

Sample Requests

Body Parameters

Identities Array

Schema Constraints

Sample Response