> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook API for Conversation Events

[← Back to API List](/ai-for-service/apis/agent-ai/api-list)

Use the Hooks API to send conversation lifecycle events to Agent AI. This API supports:

* Internal transfer events (NA, cold, warm)
* Conversation summary trigger events
* End-of-conversation events
* User/Agent Message propagation

Send all events to the same endpoint using the appropriate event name and payload structure.

| Field                    | Value                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Method**               | `POST`                                                                                                                               |
| **Endpoint**             | `https://{{host}}/agentassist/api/v1/hooks/{{botId}}`                                                                                |
| **Content-Type**         | `application/json`                                                                                                                   |
| **Authorization Header** | `auth: {{JWT}}` <br />See [How to generate the JWT Token](/ai-for-service/apis/automation/api-introduction#generating-the-jwt-token) |

## Path Parameters

| Parameter | Required | Description                                                   |
| --------- | -------- | ------------------------------------------------------------- |
| host      | Yes      | The environment URL. For example, `https://platform.kore.ai`. |
| botId     | Yes      | Unique identifier of the AI Agent (Stream ID).                |

## Request Body

The following fields are mandatory for user/agent message events:

* `query`
* `agentId`
* `experience`
* `author.type`
* `source`
* `sendUserMessage`
* `sendAgentMessage`
* `language`

Consider the following field for events such as internal transfer, end of conversation, or trigger summary:

`"events": [{ ... }]`

```json theme={null}
{
  "conversationId": "string",
  "botId": "string",
  "query": "Price is too expensive",
  "agentId": "xxxxx",
  "experience": "chat",
  "author": {
    "type": "USER"
  },
  "source": "genesys",
  "sendUserMessage": true,
  "sendAgentMessage": false,
  "language": "en",
  "events": [{ ... }]
}
```

| Field              | Type    | Required    | Description                                                                                                                    |
| ------------------ | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `conversationId`   | String  | Yes         | Unique identifier of the conversation. Must remain the same throughout the lifecycle.                                          |
| `botId`            | String  | Yes         | AI Agent (Stream) ID.                                                                                                          |
| `query`            | String  | Conditional | User or agent message content. Required for user/agent message events.                                                         |
| `agentId`          | String  | Conditional | Unique identifier of the agent sending or associated with the message. Required for message events.                            |
| `experience`       | String  | Conditional | Interaction type (for example, `chat` or `voice`). Required for message events.                                                |
| `author.type`      | String  | Conditional | Indicates the message origin. Use `USER` or `AGENT`. Required for message events.                                              |
| `source`           | String  | Conditional | Source platform of the message (for example, `genesys`). Required for message events.                                          |
| `sendUserMessage`  | Boolean | Conditional | Set to `true` to send user messages to Agent AI.                                                                               |
| `sendAgentMessage` | Boolean | Conditional | Set to `true` to send agent messages to Agent AI.                                                                              |
| `language`         | String  | Conditional | Language of the message or conversation (for example, `en`).                                                                   |
| `events`           | Array   | Conditional | List of event objects. Required for event-driven scenarios such as internal transfer, summary trigger, or end of conversation. |

## Supported Events

### Internal Transfer Event

Tracks agent join and exit actions, including cold and warm transfers.

#### Event Name

INTERNAL\_TRANSFER\_EVENT

#### Event Structure

```json theme={null}
{
 "name": "INTERNAL_TRANSFER_EVENT",
 "transfertype": "NA | COLD | WARM",
 "transition": "entry | exit",
 "isExtAD": true,
 "language": "en",
 "experience": "chat | voice",
 "participant": {
   "identity": "string",
   "name": "string",
   "type": "agent",
   "customFields": {
     "agentEmail": "string",
     "queueId": "string",
     "queueName": "string"
   }
 }
}
```

#### Field Description

| Field                      | Required | Description                                                         |
| -------------------------- | -------- | ------------------------------------------------------------------- |
| `transfertype`             | Yes      | Transfer type: `NA`, `COLD`, or `WARM`.                             |
| `transition`               | Yes      | `entry` when agent joins, `exit` when agent leaves.                 |
| `isExtAD`                  | Yes      | Indicates whether an external directory is used.                    |
| `language`                 | No       | Conversation language.                                              |
| `experience`               | Yes      | Interaction type (`chat` or `voice`).                               |
| `participant`              | Yes      | Agent details.                                                      |
| `participant.customFields` | No       | Required only when using the Quality Module for post-call analysis. |

#### Transfer Types

| Type | When to Use                                                  |
| ---- | ------------------------------------------------------------ |
| NA   | First agent entry and final agent exit.                      |
| COLD | One agent replaces another. Only one active agent at a time. |
| WARM | Multiple agents participate simultaneously.                  |

### Transfer Flow Scenarios

#### Cold Transfer Flow

In this scenario, Agent-1 accepts the call and redirects it to Agent-2, and later Agent-3 gets the call.

* Customer connects to Agent 1 → `NA` + `entry`
* Agent 1 exits the conversation → `cold` + `exit`
* Agent 2 accepts the conversation → `cold` + `entry`
* Agent 2 exits the conversation → `cold` + `exit`
* Agent 3 accepts the conversation → `cold` + `entry`
* Conversation ends → Last agent → `NA` + `exit`

#### Warm Transfer Flow

* Customer connects to Agent 1 → `NA` + `entry`
* Agent 1 invites Agent 2 as a consultant
* Agent 2 joins → `warm` + `entry`
* Agent 1 invites Agent 3 as a consultant
* Agent 3 joins → `warm` + `entry`
* Agent 2 leaves → `warm` + `exit`
* Agent 3 leaves → `warm` + `exit`
* Conversation ends → Agent 1 exits → `NA` + `exit`

#### Redial Scenario

* Customer connects to Agent 1 → `NA` + `entry`
  * Conversation drops unexpectedly
* Agent reconnects to the same conversation → `redial` + `entry`
  * Conversation continues without creating a new segment
* Conversation ends → Agent 1 exits → `NA` + `exit`

### Trigger Summary Event

Triggers the generation of a conversation summary.

#### Event Name

TRIGGER\_SUMMARY\_EVENT

#### Event Structure

```json theme={null}
{
 "name": "TRIGGER_SUMMARY_EVENT",
 "data": {
   "language": "English",
   "locale": "en",
   "type": "post"
 }
}
```

#### Field Description

| Field           | Required | Description                              |
| --------------- | -------- | ---------------------------------------- |
| `data.language` | Yes      | Summary language (for example, English). |
| `data.locale`   | Yes      | Locale code (for example, en).           |
| `data.type`     | Yes      | Summary type (for example, `post`).      |

### End of Conversation Event

Notifies Agent AI that the conversation has terminated.

#### Event Name

END\_OF\_CONVERSATION

<Info>Invoke this event **only once**, at the final termination of the conversation—whether normal or unexpected—to prevent duplicate processing.</Info>

#### Event Structure

```json theme={null}
{
 "name": "END_OF_CONVERSATION",
 "reason": "agent_initiated",
 "language": "en",
 "experience": "voice",
 "participant": {
   "identity": "string",
   "name": "string",
   "type": "agent",
   "customFields": {
     "agentEmail": "string",
     "queueId": "string",
     "queueName": "string"
   }
 }
}
```

#### Field Description

| Field                      | Required | Description                                              |
| -------------------------- | -------- | -------------------------------------------------------- |
| `reason`                   | Yes      | Reason for termination (for example, `agent_initiated`). |
| `language`                 | Yes      | Conversation language.                                   |
| `experience`               | Yes      | Interaction type (`chat` or `voice`).                    |
| `participant`              | Yes      | Agent responsible for termination.                       |
| `participant.customFields` | No       | Optional metadata.                                       |

## Event Payload Examples

### No Transfer

**First Agent Accepts (INTERNAL\_TRANSFER\_EVENT)**

This event triggers when the first agent accepts the customer interaction (not a transfer).

**Entry Scenario:** The system triggers this scenario when the Agent AI widget loads with transition as `entry` along with the agent details.

**Exit Scenario:** The system triggers this scenario at the end of the interaction with transition as `exit` along with the agent details.

```json theme={null}
{
    "events": [
        {
            "name": "INTERNAL_TRANSFER_EVENT",
            "transfertype": "NA",
            "transition": "entry",
            "isExtAD": "true",
            "language": "en",
            "experience": "voice",
            "participant": {
                "identity": "Agent1",
                "name": "Agent AI",
                "type": "agent",
                "customFields": {
                    "agentEmail": "TP000037111@xxxxbank.com",
                    "queueId": "1694",
                    "queueName": "Kore_UAT_AGT_EN"
                }
            }
        }
    ]
}
```

### Cold Transfer: New Agent Joins

**(INTERNAL\_TRANSFER\_EVENT)**

The system triggers this scenario when the internal conversation transfer happens between Agent-1 to Agent-2.

```json theme={null}
{
    "events": [
        {
            "name": "INTERNAL_TRANSFER_EVENT",
            "transfertype": "cold",
            "transition": "entry",
            "isExtAD": "true",
            "language": "en",
            "experience": "voice",
            "participant": {
                "identity": "Agent2",
                "name": "Agent AI",
                "type": "agent",
                "customFields": {
                    "agentEmail": "TP000037111@xxxxbank.com",
                    "queueId": "1694",
                    "queueName": "Kore_UAT_AGT_EN"
                }
            }
        }
    ]
}
```

### Cold Transfer: Agent-1 Exits

**(INTERNAL\_TRANSFER\_EVENT)**

```json theme={null}
{
    "events": [
        {
            "name": "INTERNAL_TRANSFER_EVENT",
            "transfertype": "cold",
            "transition": "exit",
            "isExtAD": "true",
            "language": "en",
            "experience": "voice",
            "participant": {
                "identity": "Agent1",
                "name": "Agent AI",
                "type": "agent",
                "customFields": {
                    "agentEmail": "TP000037111@xxxxbank.com",
                    "queueId": "1694",
                    "queueName": "Kore_UAT_AGT_EN"
                }
            }
        }
    ]
}
```

### Warm Transfer: Agent-2 Joins

**(INTERNAL\_TRANSFER\_EVENT)**

The system triggers this scenario when one or multiple agents join the conversation as consultants.

```json theme={null}
{
    "events": [
        {
            "name": "INTERNAL_TRANSFER_EVENT",
            "transfertype": "warm",
            "transition": "entry",
            "isExtAD": "true",
            "language": "en",
            "experience": "voice",
            "participant": {
                "identity": "agent2",
                "name": "Agent AI2",
                "type": "agent",
                "customFields": {
                    "agentEmail": "TP000037111@xxxxbank.com",
                    "queueId": "1694",
                    "queueName": "Kore_UAT_AGT_EN"
                }
            }
        }
    ]
}
```

### Warm Transfer: Agent-1 Leaves

**(INTERNAL\_TRANSFER\_EVENT)**

```json theme={null}
{
    "events": [
        {
            "name": "INTERNAL_TRANSFER_EVENT",
            "transfertype": "warm",
            "transition": "exit",
            "isExtAD": "true",
            "language": "en",
            "experience": "voice",
            "participant": {
                "identity": "agent1",
                "name": "Agent AI",
                "type": "agent",
                "customFields": {
                    "agentEmail": "TP000037111@xxxxbank.com",
                    "queueId": "1694",
                    "queueName": "Kore_UAT_AGT_EN"
                }
            }
        }
    ]
}
```

### Redial Scenario

**(INTERNAL\_TRANSFER\_EVENT)**

Similar to the General Entry Scenario, this redundant operation creates multiple segments for the same agent with the initial segment start time.

```json theme={null}
{
    "events": [
        {
            "name": "INTERNAL_TRANSFER_EVENT",
            "transfertype": "redial",
            "transition": "entry",
            "reason": "agent_initiated",
            "language": "en",
            "experience": "voice",
            "participant": {
                "identity": "agent1",
                "name": "Agent AI",
                "type": "agent",
                "customFields": {
                    "agentEmail": "TP000037111@xxxxbank.com",
                    "queueId": "1694",
                    "queueName": "Kore_UAT_AGT_EN"
                }
            }
        }
    ]
}
```

**Sample cURL for Redial**:

```bash theme={null}
curl --location 'https://ind-platform.kore.ai/api/v1/hooks/st-4beef2ed-bf1d-59e3-bd7f-5467f84dxxxx' 
--header 'Content-Type: application/json'
--header 'token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXxxxx...'
--data '{
    "conversationId": "303030303333393234303137363037343631xxxx",
    "botId": "st-4beef2ed-bf1d-59e3-bd7f-5467f84dxxxx",
    "events": [
        {
            "name": "INTERNAL_TRANSFER_EVENT",
            "transfertype": "redial",
            "transition": "entry",
            "isExtAD": "true",
            "language": "en",
            "experience": "voice",
            "participant": {
                "identity": "731hssad",
                "name": "Agent AI",
                "type": "agent",
                "customFields": {
                    "agentEmail": "TP000037111@xxxxbank.com",
                    "queueId": "1694",
                    "queueName": "Kore_UAT_AGT_EN"
                }
            }
        }
    ]
}'
```

#### Standard Conversation Flow: Event Sequence

For any conversation lifecycle, the system must trigger the following events in the prescribed order to ensure accurate analytics, proper session tracking, and complete reporting within Kore.ai.

| Step | Event                     | Transfer Type   | Transition       | Requirement     | Description                                                                                                                                                                             |
| ---- | ------------------------- | --------------- | ---------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | `INTERNAL_TRANSFER_EVENT` | `NA`            | `entry`          | **Mandatory**   | Marks the beginning of the conversation when the first agent accepts the interaction. This is the starting point for all conversations.                                                 |
| 2    | `INTERNAL_TRANSFER_EVENT` | `cold` / `warm` | `entry` / `exit` | **Conditional** | Include this event only if internal transfers occur during the conversation. Each transfer (cold or warm) must include the appropriate entry and exit events for the respective agents. |
| 3    | `INTERNAL_TRANSFER_EVENT` | `NA`            | `exit`           | **Mandatory**   | Marks the final agent's exit from the conversation. This must always be triggered before conversation closure.                                                                          |
| 4    | `TRIGGER_SUMMARY_EVENT`   | —               | —                | **Conditional** | Include this only if you need to generate a disposition summary. It triggers after the agent exits and before the conversation is formally closed.                                      |
| 5    | `END_OF_CONVERSATION`     | —               | —                | **Mandatory**   | Signals the formal closure of the conversation. This must always be the final event in the sequence to ensure proper post-call analytics and Quality Management processing.             |

**Key Rule**: Every conversation must begin with Step 1 and end with Steps 3 and 5 at minimum. The system triggers steps 2 and 4 based on the conversation context (for example, transfers or summary generation).

#### Abrupt Conversation End (Redial): Event Sequence

When a conversation drops unexpectedly (for example, due to a network failure or system disconnection), you must follow this event sequence to re-establish the session and close it properly. The `conversationId` remains the same as the original dropped call to maintain session continuity.

| Step | Event                     | Transfer Type | Transition | Description                                                                                                                                                                     |
| ---- | ------------------------- | ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | `INTERNAL_TRANSFER_EVENT` | `NA`          | `exit`     | Registers the agent's exit from the dropped conversation, formally closing the interrupted session.                                                                             |
| 2    | `INTERNAL_TRANSFER_EVENT` | `redial`      | `entry`    | Marks the agent's re-entry into the same conversation after reconnection. This event is also applicable when an agent initiates a callback without a prior active conversation. |
| 3    | `INTERNAL_TRANSFER_EVENT` | `NA`          | `exit`     | Marks the agent's final exit once the reconnected conversation concludes.                                                                                                       |
| 4    | `TRIGGER_SUMMARY_EVENT`   | —             | —          | Triggers the generation of the Disposition Summary for the completed conversation.                                                                                              |
| 5    | `END_OF_CONVERSATION`     | —             | —          | Signals the formal closure of the conversation. Ensures capture of all post-call analytics and Quality Management data.                                                         |

<Note>In a redial scenario, keep the **conversationId** the same as the original dropped call. This ensures the system treats the session as a continuation, not a new conversation, and preserves the full interaction history for analytics.</Note>

## Sample Request

```bash theme={null}
curl --location 'https://platform.kore.ai/agentassist/api/v1/hooks/st-XXXX' 
--header 'Content-Type: application/json' 
--header 'token: <JWT;' 
--data '{
 "conversationId": "c-12345",
 "botId": "st-XXXX",
 "events": [
   {
     "name": "INTERNAL_TRANSFER_EVENT",
     "transfertype": "NA",
     "transition": "entry",
     "isExtAD": "true",
     "experience": "voice",
     "participant": {
       "identity": "agent1",
       "name": "Agent One",
       "type": "agent"
     }
   }
 ]
}'
```

## Responses

**Success**: `200 OK`

or

```json theme={null}
{
 "STATUS": "OK"
}
```

**Error (Invalid botId)**:

```json theme={null}
{
 "code": 400,
 "message": "Linked bot details couldn't be found. Please verify that the botId provided in the request body is correct."
}

```