Back to API List

Hooks API for Internal Transfers

This API supports internal transfer events, reducing reliance on UI socket events. It captures transfer data initiated outside the UI, sends via API payloads, and displays in the Agent AI widget.

Method	POST
Endpoint	https://{{host}}/agentassist/api/v1/hooks/{{botId}}
Content Type	application/json
Authorization	auth: {{JWT}} See How to generate 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 bot.

Header Parameters

Header	Type	Required	Description
Content-Type	String	Yes	Indicates the media type of the request body. Set to application/json.
token	String	Yes	Authentication token used to authorize the request.

Sample Request

curl --location 'https://platform.kore.ai///agentassist/api/v1/hooks/st-XXXX-XXXX-XXXX-XXXX' \
--header 'Content-Type: application/json' \
--header 'token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6ImNzLTYzNjNmY2JiLTMxMGUtNWIwNy05MWE5LWM2MTRjZDNjYmY2ZSJ9.H-JGmnWDBm2mFIw_PoMLQ5WLTPT_9-iFFPTLrHxxxxx' \
--data '{
   "conversationId": "c-xxxx",
   "botId": "st-XXXX-XXXX-XXXX-XXXX",
   "events": [
       {
           "name": "INTERNAL_TRANSFER_EVENT",
           "transfertype": "NA",
           "transition": "entry",
           "isExtAD": "true",
           "language": "language",
           "experience": "chat",
           "participant": {
               "identity": "xxxxxx",
               "name": "Agent ai",
               "type": "agent"
           }
       }
   ]
}'

Request Body Parameters

Parameter	Type	Required	Description
conversationId	String	Yes	Unique identifier of the conversation.
botId	String	Yes	Identifier of the bot associated with the event.
events	Array of Objects	Yes	List of event objects that describe actions or state transitions.

Parameter	Type	Required	Description
name	String	Yes	Name of the event. Example: INTERNAL_TRANSFER_EVENT.
transfertype	String	Yes	Specifies the transfer type.
transition	String	Yes	Indicates the event transition (for example, entry).
isExtAD	String	Yes	Shows whether the transfer uses an external directory.
language	String	No	Language used during the event.
experience	String	Yes	Interaction mode. Example: chat or voice

Parameter	Type	Required	Description
participant	Object	Yes	Provides details about the participant involved in the event.
participant.identity	String	Yes	Unique identifier of the participant.
participant.name	String	Yes	Name of the participant.
participant.type	String	Yes	Type of participant. Example: agent.

Types of Transfers

The Hooks API supports the following transfer types:

Transfer Type	Description
NA Transfer (No Transfer)	The first agent accepts the conversation, or the last agent leaves the conversation.
Cold Transfer	Conversation moves from one agent to another—only one agent is active at a time.
Warm Transfer	A new agent joins while others remain in the conversation—multiple agents may be active.

Key principle: The conversation ID remains the same throughout all these events to ensure continuity in Agent AI’s context.

Sending Transfer Events

Use the following JavaScript code to send internal transfer events to the Agent AI backend.

async function sendInternalTransferEvent(payload) {
  await axios.post(
    `<baseurl>/agentassist/api/v1/hooks/<botId>`,
    payload,
    {
    headers: {
        token: jwt.sign(
        {
            appId: <clientId>,
        },
        <clientSecret>
        ),
    },
    }
  );
}

Where the payload includes:

• Transfertype: The type of transfer
• Transition: Indicates whether the agent is entering or exiting
• Participant: Details of the agent involved

Detailed Scenarios

Here are the scenarios in detail, with their purpose and sample payloads:

NA Transfer (No Transfer)

When a customer connects with the first agent, it’s unknown whether a transfer will occur. In this case, the payload includes an NA entry event.

const payload = {
    conversationId: "atesta-xxxx",
    botId: "st-XXXX-XXXX-XXXX-XXXX",
    events: [
    {
        name: "INTERNAL_TRANSFER_EVENT",
        transfertype: "NA",
        transition: "entry",
        isExtAD: true,
        language: "en",
        experience: "voice",
        participant: {
        identity: "agentId1",
        name: "AgentName1",
        type: "agent"
        }
    }
    ]
  }
sendInternalTransferEvent(payload);

Explanation:

• transfertype: "NA"—No transfer has occurred yet.
• transition: "entry"—The agent has entered the conversation.

Cold Transfer

This occurs when the conversation is moved from one agent to another.
At any given time, only one agent is in the conversation.

New Agent Joins

const payload = {
    conversationId: "atesta-xxxx",
    botId: "st-XXXX-XXXX-XXXX-XXXX",
    events: [
    {
        name: "INTERNAL_TRANSFER_EVENT",
        transfertype: "COLD",
        transition: "entry",
        isExtAD: true,
        language: "en",
        experience: "voice",
        participant: {
        identity: "agentId2",
        name: "AgentName2",
        type: "agent"
        }
    }
    ]
  }
sendInternalTransferEvent(payload);

Previous Agent Leaves

const payload = {
    conversationId: "atesta-xxxx",
    botId: "st-XXXX-XXXX-XXXX-XXXX",
    events: [
    {
        name: "INTERNAL_TRANSFER_EVENT",
        transfertype: "COLD",
        transition: "exit",
        isExtAD: true,
        language: "en",
        experience: "voice",
        participant: {
        identity: "agentId1",
        name: "AgentName1",
        type: "agent"
        }
    }
    ]
  }
sendInternalTransferEvent(payload);

Repeat the same pattern if there are more transfers.

Warm Transfer

This occurs when one or more additional agents join the conversation while others remain active.
Multiple agents can participate and be active at the same time.

Agent Joins

const payload = {
    conversationId: "atesta-xxxx",
    botId: "st-XXXX-XXXX-XXXX-XXXX",
    events: [
    {
        name: "INTERNAL_TRANSFER_EVENT",
        transfertype: "WARM",
        transition: "entry",
        isExtAD: true,
        language: "en",
        experience: "voice",
        participant: {
        identity: "agentId3",
        name: "AgentName3",
        type: "agent"
        }
    }
    ]
  }
sendInternalTransferEvent(payload);

Agent Leaves (Not the Last Agent)

const payload = {
    conversationId: "atesta-xxxx",
    botId: "st-XXXX-XXXX-XXXX-XXXX",
    events: [
    {
        name: "INTERNAL_TRANSFER_EVENT",
        transfertype: "WARM",
        transition: "exit",
        isExtAD: true,
        language: "en",
        experience: "voice",
        participant: {
        identity: "agentId2",
        name: "AgentName2",
        type: "agent"
        }
    }
    ]
  }
sendInternalTransferEvent(payload);

Final Agent Leaves at the End of the Conversation

const payload = {
    conversationId: "atesta-xxxx",
    botId: "st-XXXX-XXXX-XXXX-XXXX",
    events: [
    {
        name: "INTERNAL_TRANSFER_EVENT",
        transfertype: "NA",
        transition: "exit",
        isExtAD: true,
        language: "en",
        experience: "voice",
        participant: {
        identity: "agentId3",
        name: "AgentName3",
        type: "agent"
        }
    }
    ]
  }
sendInternalTransferEvent(payload);

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
  • Agent 1—cold + exit
• Agent-2 accepts the conversation
  • Agent 2—cold + entry
• Agent-2 exits the conversation
  • Agent 2—cold + exit
• Agent-3 accepts the conversation
  • Agent 3—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

Key Takeaways

• Always send the correct transfer events when agents join or leave.
• Maintain a consistent conversation ID throughout the conversation.
• Use:
  • NA for the first agent entry and last agent exit
  • cold for Conversation handovers
  • warm for multi-agent participation

Sample Response

if the request is successful, you get a success response (200 OK).

Send Feedback