Agent Transfer Integration API

Back to API List

Agent Transfer Integration API

Use the Agent Transfer Integration API to enable, update, and reset Agent Integrations for an app. The API supports Custom (Botkit), Kore, Genesys Web Messaging, ServiceNow, and Salesforce MIAW integrations.

Field	Value
Method	POST – Enables a new Agent Integration. PUT – Updates an existing Agent Integration. DELETE – Resets an existing Agent Integration configuration.
Endpoint	https://{{host}}/api/public/bot/{{botId}}/agentintegrations/chat/{{integration}}
Content Type	application/json
Authorization	auth: {{JWT}} See How to generate the JWT Token.
API Scope	agent_integrations:read and agent_integrations:write

All supported Agent Integrations are chat integrations. Use chat as the integration type in the endpoint.

Path Parameters

Parameter	Required	Description
botId	Required	ID of the app. Access it through App Settings → App Profile.
integration	Required	Identifier of the Agent Integration to configure. Supported integrations are custom, genesys, kore, servicenow, and salesforce.

Query Parameters

Parameter	Required	Type	Description
setAsDefault	Optional	Boolean	Sets the Agent Integration as the default when set to true. Only one Agent Integration can be the default at a time.

Do not use isDefault in the request body.

Body Parameters

For POST and PUT, provide the configuration fields required for the selected Agent Integration.

Parameter	Required	Type	Description
<integration-specific-fields>	Conditional	Object	Configuration fields required for the selected Agent Integration.

Sample Request for POST

Use POST to enable an Agent Integration.

curl --location --request POST 'https://{{host}}/api/public/bot/{{botId}}/agentintegrations/chat/{{integration}}' \
--header 'auth: {{jwt-token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  <integration-specific-fields>
}'

To enable the integration and set it as the default:

curl --location --request POST 'https://{{host}}/api/public/bot/{{botId}}/agentintegrations/chat/{{integration}}?setAsDefault=true' \
--header 'auth: {{jwt-token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  <integration-specific-fields>
}'

Sample Request for PUT

Use PUT to update an existing Agent Integration. Provide the complete configuration.

curl --location --request PUT 'https://{{host}}/api/public/bot/{{botId}}/agentintegrations/chat/{{integration}}' \
--header 'auth: {{jwt-token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  <complete-integration-configuration>
}'

Sample Request for DELETE

Use DELETE to reset an Agent Integration.

curl --location --request DELETE 'https://{{host}}/api/public/bot/{{botId}}/agentintegrations/chat/{{integration}}' \
--header 'auth: {{jwt-token}}' \

Use this API to reset all the configured Agent Integration.

curl --location --request DELETE 'https://{{host}}/api/public/bot/{{botId}}/agentintegrations' \
--header 'auth: {{jwt-token}}' \

Request Body Examples

Custom Botkit

Use custom as the integration value.

{
  "sdkClientId": "<sdkClientId>",
  "sdkHostUri": "<sdkHostUri>",
  "PIIMaskingDisabledForAgentTransfer": false,
  "connectorEnabled": false
}

Genesys Web Messaging

Use genesys as the integration value.

{
  "apiType": "webMessagingAPI",
  "baseURL": "<baseURL>",
  "organizationId": "<organizationId>",
  "deploymentId": "<deploymentId>",
  "queueName": "<queueName>",
  "webSocketURL": "<webSocketURL>",
  "disableEndMessage": false
}

Kore

Use kore as the integration value.

{
  "conversationType": "livechat",
  "isAgentAssistRequired": "yes",
  "isAgentAssistSendBtnEnabled": "yes"
}

ServiceNow - Basic Authentication

Use servicenow as the integration value.

{
  "host": "<host>",
  "authType": "basic",
  "userId": "<userId>",
  "password": "<password>",
  "VAApi": false,
  "queueId": "<queueId>"
}

ServiceNow - OAuth Refresh Token

Use servicenow as the integration value.

{
  "enabled": true,
  "config": {
    "host": "<host>",
    "authType": "oauth2_refresh_token",
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}",
    "refresh_token": "{{refresh_token}}",
    "tenant": "{{tenant}}",
    "VAApi": true,
    "queueId": "{{queueId}}"
  }
}

Salesforce - MIAW

Use salesforce as the integration value.

{
  "integrationType": "salesforcemiaw",
  "organizationId": "<organizationId>",
  "liveAgentUrl": "<liveAgentUrl>",
  "esDeveloperName": "<esDeveloperName>"
}

Salesforce - Legacy Live Chat

Use salesforce as the integration value.

{
  "enabled": true,
  "config": {
    "integrationType": "liveChat",
    "organizationId": "{{organizationId}}",
    "liveAgentUrl": "<liveAgentUrl>",
    "deploymentId": "{{deploymentId}}",
    "buttonId": "{{buttonId}}"
  }
}

Sample Response for POST

{
  "state": "configured",
  "requiresPublish": true
}

Sample Response for PUT

{
  "state": "configured",
  "requiresPublish": true
}

Sample Response for DELETE

{
  "status": "deleted",
  "integration": "<integration>"
}

Channel Mappings API

Field	Value
Method	GET – Retrieves the channel mappings configured for the app. PUT – Updates the channel mappings configured for the app.
Endpoint	https://{{host}}/api/public/bot/{{botId}}/agentintegrations/channelmappings
Content Type	application/json
Authorization	auth: {{JWT}} See How to generate the JWT Token.
API Scope	agent_integrations:read and agent_integrations:write

The channel mapping configuration contains the app’s default Agent Integration and a mapping for each enabled chat channel. Voice channels are not included.

Path Parameters

Parameter	Required	Description
botId	Required	ID of the app. Access it through App Settings → App Profile.

Body Parameters

Parameter	Required	Type	Description
channelMappings	Required	Object	Contains the default Agent Integration and a mapping for each enabled chat channel.
channelMappings.default	Required	String	The app’s default Agent Integration.
channelMappings.<channel>	Required	String	Agent Integration mapped to an enabled chat channel. The channel keys depend on the channels enabled for the app.
state	Optional	String	Configuration state. The API accepts and ignores this field.
requiresPublish	Optional	Boolean	Indicates whether the configuration requires publishing. The API accepts and ignores this field.

The PUT request replaces the entire channel mapping configuration. To update a single mapping, retrieve the current configuration using GET, modify the required mapping, and send the complete configuration using PUT.

Sample GET Request

Retrieves the channel mappings configured for the app.

curl -s "https://{{host}}/api/public/bot/{{botId}}/agentintegrations/channelmappings" \
--header 'auth: {{jwt-token}}' \

Sample PUT Request

Updates the channel mappings configured for the app.

The request must include the default mapping and a mapping for every enabled chat channel. The API replaces the entire channel mapping configuration. If a channel is omitted, the API returns a 400 error.

curl -s -X PUT "https://{{host}}/api/public/bot/{{botId}}/agentintegrations/channelmappings" \
--header 'auth: {{jwt-token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "channelMappings": {
      "default": "salesforce",
      "rtm": "genesys",
      "agentassist": "genesys",
      "smartassist": "genesys"
    }
  }'