Web View integration API

When a consumer exits a conversation flow to enter an external system (for example, a generic web view form or Apple Pay for making a payment), the Web View API makes it possible for the external system to post data back into the bot runtime.

The Web View API can be used by the external system to:

  • Set session-scoped variables in the bot runtime
  • Post a message to the chat client
  • Invoke a dialog starter to trigger a dialog flow

Don’t use this API to post Personally Identifiable Information (PII) or Payment Card Industry (PCI) data because the data is not masked.

If you have IP restrictions in place, you'll need to do some whitelisting before using this API. For details, see here.

The API requires three fields that the external system must obtain from the conversation:

  • userId: The user ID can be retrieved using the getUserPlatformId function.
  • botId: The bot ID can be retrieved from the bot settings; see the Bot ID field.
  • conversationId: The conversation ID can be retrieved using the getConversationId function.

Request

Use the POST method to set session-scoped variables in the bot runtime.

Method URL
POST https://{domain}/thirdparty-services-0.1/webview
Headers
Name Value Notes
Content-Type application/json  
Authorization The API access key that you need to pass; originally retrieved from the conversation This is an SHA authorization token that is a combination of the conversationId and the botId. It should be generated by creating a sha256 hash:

auth = sha256hex(conversationId + “ || “ + botId)

For example: sha256hex(“abcd || xyz”)

Note the space, two pipe characters, and space after the conversationId.
BODY/POST parameters
Name Description Type/Value Required Notes
botId The bot ID string Required  
conversationId The conversation ID string Required  
userId The consumer's user ID string Required  
message The message to send to the bot runtime string Optional If set, this message is posted to the chat client.

To also trigger a dialog starter, this message must match to a Dialog Starter interaction in one of the bot’s dialogs.

If unset, the Web View service only posts the variables.
contextVariables The key/value pairs that can be passed to the bot platform object:list of strings Optional These key/value pairs can be used in the bot runtime using the Get Web View Variables JavaScript functions.
Example
curl -X POST \
  https://{domain}/thirdparty-services-0.1/webview \
  -H 'Authorization: F8488E6143818BB0364717A91F235F7F7F0FE91C464EC6FAC7ECF0D3393EBBAF' \
  -H 'Content-Type: application/json' \
  -d '{
    "botId": "795bb1534e34fc89050304e6f6827c41c50410d7",
    "conversationId": "a845678d-fe5a-429e-bc46-b25d524b9fa7",
    "message":"webrequest",
    "userId": "b849678d-fe4a-439e-bc46-b25d524b9fa7",
    "contextVariables": [{"name": "PaymentId","value": "534e34fc89050304e6f6827c41c50410d7"}, {"name": "PaymentStatus","value": "PROCESSED"}]}'

Retrieve the Web View variables from the bot runtime

Use the Get Web View Variables JavaScript functions to retrieve the variables set via the Web View API.

System environment variables

If you’re using system_handleIntermediateUserMessage and system_intermediateBotResponseTimeout to block consumer interruptions for a period of time so that the bot can respond to the consumer (see here), be aware that these environment variables also cause the bot to likewise catch and ignore system messages received via a Web View integration. To get around this—so Web View messages are still processed by the bot—set the system_processWebviewIntermediateMessage environment variable to “true.”

Environment Variable Description Type Example
system_processWebviewIntermediateMessage If true, the bot processes messages received via a Web View integration even though system_handleIntermediateUserMessage is true.

If false, the system_handleIntermediateUserMessage environment variable is respected, causing the bot to catch and ignore Web View messages for the time period specified by system_intermediateBotResponseTimeout.		 Boolean true

Example guide

For a step-by-step, example guide that uses this API, see here.