Skip to content

Trigger Bot Application API V3

Sprinklr's Conversational AI is an automated, AI-powered virtual assistant that engages with customers. It interprets the intent behind a customer's query, identifies why they reached out, and takes the actions your brand configured. It also reads the sentiment of the message and replies appropriately.

The Trigger Bot Application API drives that assistant programmatically. You send it the bot application to run, the message text, and the conversation the message belongs to. It returns the bot's generated response together with the updated conversation context, letting you track where the conversation sits in the dialogue tree.

Prerequisite. Conversational AI must be enabled in your environment. Contact your Success Manager to enable it before you call this API.

Overview

OperationMethodPath
Trigger a conversational AI bot applicationPOST/api/v3/bot/trigger

The three things that identify a bot turn

Every call is addressed by a triple:

ConceptFieldWhat it identifiesLifetime
Bot applicationapplicationIdThe configured bot application (dialogue tree) to executeStatic — configured in the Sprinklr platform
ConversationconversationIdThe dialogue thread this message belongs toCaller-owned; you generate it and reuse it
TurntextThe single user utterance being processedOne call

conversationId is caller-supplied. Enter a random conversation ID to start a new conversation, or the exact existing conversation ID to continue one. Sprinklr does not issue conversation IDs — you generate one, store it, and send it back on every subsequent turn. If you lose it, the customer restarts the dialogue tree from the root.

conversationId and conversationContext.id are different values. The server maintains its own context record, returned as data.response.conversationContext.id. Do not send that value back as your conversationId.

FieldOwned by
conversationContext.conversationIdYou
conversationContext.idSprinklr
conversationContext.applicationIdYou (echoed back)
conversationContext.openAIConversationIdSprinklr

When to use this API

In the platform, bots are normally driven by a Bot Rule — the "Sprinklr Live Chat Bot (Conversational AI)" rule under the Customer/Queue rule type — which runs the bot, tags custom fields, and adds bot cases to assignment queues.

Use this API when an external system owns the channel: your own chat widget, an IVR front end, a test harness, a regression suite, or a third-party messaging integration where you need the bot's reply in the HTTP response.


Base URL

https://api3.sprinklr.com/{env}/api/v3/bot/trigger

Replace {env} with your assigned environment identifier: prod, prod0, prod2, prod3, prod4, prod5, prod6, prod8, prod11, prod12, prod15, prod16, prod17, prod18, prod19, prod21, or prod25.

Make the base URL a single configuration value so that moving between environments is a configuration change rather than a code change.


Authentication

All calls are authenticated with OAuth 2.0. See API Overview and API Key and Secret Generation.

Required headers

HeaderValuePurposeRequired on
AuthorizationBearer {{accessToken}}Authenticates the user with the serverAll requests
Key{{apiKey}}Authenticates the application with the serverAll requests
Content-Typeapplication/jsonDeclares the request body media typeAll requests
Acceptapplication/jsonDeclares the acceptable response typeAll requests

Credential hygiene. Never commit an access token or API key to source control, never paste one into a ticket, chat, or screenshot, and never log the Authorization or Key header values. Every credential on this page is a placeholder.


Trigger a bot application

POST https://api3.sprinklr.com/{env}/api/v3/bot/trigger

Request body parameters

ParameterRequiredTypeDescription
applicationIdRequiredStringUnique identifier of the bot application to trigger
textRequiredStringThe message text sent to the bot to trigger a response
conversationIdRequiredStringIdentifier of the conversation the message belongs to. Reusing an existing ID continues that conversation; a new ID starts a fresh one
languageRequiredStringLanguage code for the message. Use "en" for English or "all" for all languages
snIdOptionalStringSocial network ID. New in V3
snTypeOptionalStringSocial network type. Defaults to DEFAULT when blank. New in V3
contextVariablesOptionalObjectAdditional context variables passed to the bot application. New in V3

Using contextVariables

contextVariables is an open map, so values are not restricted to strings. Use it to seed the bot with information your system already knows — order number, customer tier, cart value, the page the chat was launched from — so the dialogue tree does not have to ask for it.

Keys correspond to variables configured on your bot application. Coordinate key names with whoever built the application in the Sprinklr UI.

Using snId and snType

These fields let a single bot application be driven on behalf of an identified social identity rather than an anonymous conversation. When neither is sent, snType defaults to DEFAULT, which is reflected as botParameters.SN_TYPE in the response.

Example request

curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/bot/trigger' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "applicationId": "0000000000000000000000a1",
    "text": "Where is my order?",
    "conversationId": "chat-7f3a91c2-0001",
    "language": "en"
  }'

Extended form using the V3-only fields:

curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/bot/trigger' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "applicationId": "0000000000000000000000a1",
    "text": "Where is my order?",
    "conversationId": "chat-7f3a91c2-0001",
    "language": "en",
    "snType": "DEFAULT",
    "snId": "webchat-user-42",
    "contextVariables": {
      "orderId": "ORD-10045",
      "customerTier": "gold",
      "cartValue": 129.5
    }
  }'

contextVariables keys are placeholders — use the variable names configured on your own bot application.


Response format

The envelope

FieldTypeDescription
dataObjectThe bot trigger result — response plus botStatus
errorsArrayError objects. Empty when there are no transport or validation errors
metadataObjectResponse metadata

Each error object has three fields:

FieldTypeDescription
idStringError identifier
codeIntegerNumeric error code
messageStringError key, for example account.not.found

data.response.responseDTOList[] — the bot's turn

The reply itself

FieldTypeMeaning
responseDetailsArrayThe bot's reply — this is what you render to the customer. Each entry has the form {"responseType": "TEXT", "detail": {"text": "…", "responseDelay": 0}}
accumulatedMessagesArrayUser messages accumulated for this turn: assetCreatedTime (epoch ms), messageText, matchedThemes
botParametersObjectBot execution variables — see below

Flow control — what your client should do next

FieldTypeMeaning
endOfConversationBooleanThe conversation has ended
endOfApplicationBooleanThe bot application has finished
routeToAgentBooleanHand the conversation to a human agent
routedToIVRBooleanThe conversation was routed to IVR
transitionBooleanA transition to another bot or node occurred
reTriggerBooleanThe bot should be triggered again
endAndReplayOngoingBotBooleanEnd and replay the in-flight bot
repeatParentReplyBooleanRepeat the parent node's reply
waitForAsyncResponseBooleanAn asynchronous response is pending
waitForAccumulation / accumulatedBooleanMessage accumulation state
accumulateAtNodeWaitTimeIntegerAccumulation wait at the node, in milliseconds
ignoredBooleanThe message was ignored

Error, fallback, and guardrail state

FieldTypeMeaning
errorBooleanThis turn errored
fallbackResponseBooleanThe reply is a fallback response
retryOnFallbackBooleanRetry behaviour on fallback
userReplyNotMatchedBooleanThe user's reply matched no configured path
stuckBooleanThe conversation is stuck
publishingStoppedBooleanPublishing was stopped
isGuardrailSuccessBooleanGuardrail evaluation result
rateLimitReachedBooleanA rate limit was reached at the bot layer
triggerFilterMatchedBooleanThe trigger filter matched

Position in the dialogue tree

FieldTypeMeaning
currentBotActivityIdStringCurrent node or activity ID
currentBotActivityTypeStringActivity type, for example DYNAMIC_CONVERSATION_ACTIVITY
processDefinitionIdStringProcess definition (bot) ID
botsExecutedArrayBot IDs executed on this turn
pathToButtonObjectButton path map

Voice and IVR

FieldTypeMeaning
botGatherDTMFBooleanThe bot is gathering DTMF input
bargeInParams.minPromptDurationMillisForBargeInIntegerMinimum prompt duration before barge-in is allowed, in milliseconds
bargeInParams.percentToTriggerBargeInAfterNumberPercentage of the prompt after which barge-in triggers
bargeInParams.triggerBargeInAfterVadMillisIntegerVoice-activity-detection threshold before barge-in, in milliseconds

Other

FieldTypeMeaning
openAIConversationIdStringGenerative-AI conversation ID
addDummyResponseIfRequiredBooleanWhether a dummy response is inserted if required
futureMessageCustomFieldsObjectCustom fields to apply to future messages

data.response.conversationContext — the durable state

FieldTypeMeaning
idStringSprinklr-side context ID (not your conversationId)
conversationIdStringThe conversation ID you supplied, echoed back
applicationIdStringThe bot application ID, echoed back
botConversationStatusStringConversation status, for example WAITING_FOR_RESPONSE
botVsConversationStatusObjectPer-bot status map, keyed by bot ID
finishedBooleanWhether the conversation is finished
freshContextBooleanWhether this is a newly created context
createdTime / modifiedTimeLongEpoch milliseconds
expireAtStringExpiry as a formatted date string, for example "Nov 18, 2026, 05:24:42 AM". Note this is not epoch milliseconds like the sibling timestamps
detectedIssueTypes, pendingIssueTypes, completedIssueTypes, currentDetectedIssueTypes, newlyDetectedIssueTypes, currentPendingIssueTypesArrayIssue-type tracking across the conversation
detectedIntents, currentDetectedIntents, intentsToDiscoverArrayIntent tracking
detectedSlots, detectedSlotEntities, entitiesToDiscoverObject / ArraySlot and entity extraction state
buttonsToDiscover, buttonLabelMapArray / ObjectButton state
userReplyPathsArrayReply paths taken
orders, currentOrdersArrayOrder context
processVariablesToTransferObjectVariables carried across a transition
processedAssetIdsArrayAssets already processed
openAIConversationIdStringGenerative-AI conversation ID
latestActivityType, latestActivityId, latestProcessDefinitionIdStringMost recent execution pointers
profileContextBooleanWhether profile context is attached
voiceBotBooleanWhether this is a voice bot conversation
replay, ignoreTransition, simpleContextSwitch, skipAlwaysRunBots, anyTriggerFilterMatchedBooleanExecution flags
issueTypeVsTriggeredByIntents, botVsTriggeredByIssueTypeObjectTrigger provenance maps

Sibling fields of conversationContext under data.response: repeatedIssueTypeFallback, issueTypeDetectionSkipped, botsExecuted, issueTypeDetectionInfos.

botParameters — bot execution variables

ParameterNotes
BOT_APPLICATION_IDEchoes your applicationId
BOT_CONTEXT_IDMatches conversationContext.id
ROOT_BOTRoot bot ID
GLOBAL_CONTEXT_VARIABLESGlobal context variable reference
TEXTEchoes your text. V2 called this USER_SAYS_TEXT
LanguageEchoes your language. Note the mixed-case key
SN_TYPECorresponds to the snType request field
TEST_MODE, FALLBACK_BOT, INLINE_PUBLISH, TYPING_INDICATOR_ENABLED, DISABLE_TRANSITION_ON_LOCAL_FALLBACKBoolean execution flags
SUBSEQUENT_ISSUE_TYPE_CONTEXTReturned as the string "false", not a boolean
CURRENT_DETECTED_ISSUE_TYPE_DETECTED_AGAINReturned as the string "false", not a boolean
NUM_DETECTED_ISSUE_TYPES, NUM_DETECTED_ISSUE_TYPES_ON_CURRENT_MESSAGE, NUM_PENDING_ISSUE_TYPESInteger counts
DETECTED_ISSUE_TYPES, ALL_DETECTED_ISSUE_TYPES, DETECTED_INTENTS, UPDATED_FIELDS, ORDERS, CURRENT_ORDERSArrays
CURRENT_APPLICATION_DETECTED_SLOT, CURRENT_APPLICATION_DETECTED_SLOT_ENTITIESObjects

Parse botParameters defensively. Several boolean-looking values are returned as strings ("false" rather than false).


Detecting the outcome of a turn

A 200 response does not mean the bot succeeded

The API returns HTTP 200 with an empty top-level errors array even when the bot itself failed to produce a reply. Always branch on the bot-level outcome fields, not on the HTTP status code alone.

An errored turn looks like this — note that errors is empty and the status is 200:

{
  "data": {
    "response": {
      "responseDTOList": [
        {
          "responseDetails": [],
          "error": true,
          "routeToAgent": true,
          "endOfConversation": true,
          "endOfApplication": true
        }
      ],
      "conversationContext": {
        "botConversationStatus": "ERROR",
        "botVsConversationStatus": {
          "0000000000000000000000b1": "ERROR"
        }
      }
    },
    "botStatus": "ERROR"
  },
  "errors": []
}

Abridged to the outcome fields.

Check these five signals:

SignalErrored turn
data.botStatus"ERROR"
data.response.conversationContext.botConversationStatus"ERROR"
botVsConversationStatus[botId]"ERROR"
responseDTOList[0].errortrue
responseDTOList[0].responseDetailsEmpty — the bot produced no reply text

A successful turn returns a populated responseDetails array and error: false.

function turnFailed(res) {
  const dto = res.data?.response?.responseDTOList?.[0];
  return res.data?.botStatus === 'ERROR'
      || dto?.error === true
      || !dto?.responseDetails?.length;
}

botStatus

data.botStatus carries the outcome of the turn. The platform's Bot Rule documentation describes five bot status scenarios:

ScenarioMeaning
Error StateThe application encountered an error state
Routed to AgentThe conversation is routed to an agent
FallbackThe bot triggered a fallback
Conversation with BotThe conversation is currently with the bot
Conversation EndedThe conversation has ended

Always include a default branch when switching on botStatus. New status values may be introduced, so treat any unrecognised value as a non-success outcome rather than falling through silently.


Status codes

HTTP CodeDescription
200 OKSuccess
400 Bad RequestBad request
401 UnauthorizedMissing or invalid authentication
403 ForbiddenInsufficient permissions
404 Not FoundResource not found

Troubleshooting

From the platform-wide REST API Errors and Status Codes guide:

CodePossible reasonsRecommended solution
400 Bad RequestBad syntax; missing or wrong key; missing access token; wrong method type; invalid request or responseRecheck the documentation and update the request. If unchanged, contact the integration support team.
401 UnauthorizedThe bearer token may be invalid, expired, or may lack the necessary permissionsRefresh the authorization token. The access token is valid for 30 days; refresh after that.
401 UnauthorizedInvalid consumer keyCheck whether the key is associated with the right environment. Key information is under MY ACCOUNT on the developer portal.
403 Developer InactiveProbable issue with the headersRecheck Key, Authorization token, and Content-Type. If it persists, check whether you have access to the requested endpoint.
403 ForbiddenThe call is correct but the user is not permitted the resourceCross-check the endpoint URI, clear cookies, and request the required permissions.
403 Developer Over RateAPI calls per second or hour exceed the set call limitRetry after some time.
404 Resource Not FoundThe requested resource could not be foundCross-check the endpoint URL; recheck headers, method type, and request body.
411 Length RequiredA POST or PUT was made without a Content-Length headerAdd Content-Length. If there is no request body, send Content-Length: 0.
415 Unsupported Media TypeIncorrect or unsupported payload formatCheck Content-Type and Accept.
421 Misdirected RequestThe API key and the environment do not matchCheck the API key and the environment it is mapped against. A key issued for Prod2 will not work for Prod3.
429 Too Many RequestsExceeding the set call rate limitWait for the rate limit to reset.
500 Internal Server ErrorServer-side issueUsually resolves on its own; contact integration support if it persists.
503 Service UnavailableServer not ready; possibly scheduled maintenanceRetry after some time.
504 Gateway TimeoutThe gateway could not fetch a timely responseRetry after some time.

Migrating from V2

What changed at a glance

AspectV2V3
EndpointPOST /api/v2/triggerBotApplicationPOST /api/v3/bot/trigger
Path styleSingle camelCase verb segmentResource (/bot) plus action (/trigger)
Request fieldsapplicationId, text, conversationId, languageThe same four, plus snId, snType, contextVariables
Response envelope{ data, errors }{ data, errors, metadata }
HeadersAuthorization, Key, Content-Type, AcceptUnchanged
AuthenticationOAuth 2.0Unchanged

The request body is unchanged

All four V2 fields keep their exact names, types, and meanings. A V2 payload is a valid V3 payload. For a parity migration, this is a URL change:

- https://api3.sprinklr.com/{env}/api/v2/triggerBotApplication
+ https://api3.sprinklr.com/{env}/api/v3/bot/trigger
V2 fieldV3 fieldChange
applicationIdapplicationIdNone
texttextNone
conversationIdconversationIdNone
languagelanguageNone
—snIdNew in V3
—snTypeNew in V3, defaults to DEFAULT when blank
—contextVariablesNew in V3

Identifier format change

This is the change most likely to break a V2 client, and it is easy to miss because no field was renamed.

FieldV2 formatV3 format
currentBotActivityIdPrefixed UUID, for example node-d1052330-dd70-48c7-948d-1b12953a64c224-character hex ID
processDefinitionIdUUID24-character hex ID
botParameters.ROOT_BOTUUID24-character hex ID
botVsConversationStatus keysUUID24-character hex ID

If you persist, index, log-correlate, regex-validate, or size a database column against these values, the V2 format will not validate and the V3 format will not fit a UUID column. Audit every place a bot activity or process definition ID is stored before cutover.

Response field changes

Renamed

V2V3
botParameters.USER_SAYS_TEXTbotParameters.TEXT

New in V3

AreaNew fields
Flow controlendOfApplication, endAndReplayOngoingBot, repeatParentReply, accumulateAtNodeWaitTime, addDummyResponseIfRequired
Error and guardrailstuck, publishingStopped, userReplyNotMatched, isGuardrailSuccess, rateLimitReached
Dialogue positioncurrentBotActivityType, botsExecuted, pathToButton
Voice and IVRbargeInParams
Generative AIopenAIConversationId on both responseDTOList[] and conversationContext
ContextexpireAt, detectedSlotEntities, newlyDetectedIssueTypes, buttonLabelMap, processVariablesToTransfer, botConversationStatus, profileContext, voiceBot, freshContext, orders, currentOrders, simpleContextSwitch, latestActivityType, latestActivityId, latestProcessDefinitionId, skipAlwaysRunBots
Bot parametersTEST_MODE, SN_TYPE, CURRENT_DETECTED_ISSUE_TYPE_DETECTED_AGAIN, ALL_DETECTED_ISSUE_TYPES, DETECTED_ISSUE_TYPES, GLOBAL_CONTEXT_VARIABLES, ORDERS, CURRENT_ORDERS, CURRENT_APPLICATION_DETECTED_SLOT_ENTITIES
Envelopemetadata

Common Use Cases

Start a new conversation

Generate a fresh conversationId and send the first utterance. conversationContext.freshContext returns true.

{
  "applicationId": "0000000000000000000000a1",
  "text": "Hi",
  "conversationId": "chat-7f3a91c2-0001",
  "language": "en"
}

Store conversationId against your session — you need it for every subsequent turn.

Continue an existing conversation

Send the same conversationId with the next utterance. Do not send anything else back from the previous response; the server holds the state.

{
  "applicationId": "0000000000000000000000a1",
  "text": "Order 10045",
  "conversationId": "chat-7f3a91c2-0001",
  "language": "en"
}

Do not send conversationContext.id as your conversationId — they are different fields.

Seed the bot with known context

Pass what your system already knows so the dialogue tree does not have to ask:

{
  "applicationId": "0000000000000000000000a1",
  "text": "Where is my order?",
  "conversationId": "chat-7f3a91c2-0001",
  "language": "en",
  "contextVariables": {
    "orderId": "ORD-10045",
    "customerTier": "gold"
  }
}

Hand off to a human agent

When responseDTOList[0].routeToAgent is true, stop sending turns to the bot and transfer the conversation to your agent workflow. Render any content in responseDetails first — the bot may have a closing message.

Drive a voice bot

For voice channels, read bargeInParams to configure interruption handling and botGatherDTMF to know when the bot expects keypad input. conversationContext.voiceBot confirms the conversation is running in voice mode.


Best practices

  • Never treat 200 as success. Inspect data.botStatus and responseDTOList[].error on every turn.
  • Always include a default branch when switching on botStatus.
  • Store and reuse conversationId. Losing it restarts the customer's dialogue from the root.
  • Never send conversationContext.id as your conversationId.
  • Parse defensively — some botParameters values are strings rather than booleans, and expireAt is a formatted date string rather than epoch milliseconds.
  • Handle rate limiting at two layers. 403 Developer Over Rate and 429 Too Many Requests indicate HTTP-level rate limiting; responseDTOList[].rateLimitReached signals a limit at the bot layer. Implement retry with exponential backoff.
  • Never log or screenshot the Authorization or Key header values.