Introduction
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
Limitations
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 use this API to post a message back to the bot, there’s a time restriction: That message must be sent within 24 hours of receipt of the consumer’s most recent message via the channel. Otherwise, the message sent via the API is ignored by the bot, which means the bot won't respond to it.
Getting started
Retrieve your domain based on your environment:
Environment | Domain |
---|---|
LivePerson Cloud US | va.bc-intg.liveperson.net |
LivePerson Cloud UK | lo.bc-intg.liveperson.net |
LivePerson Cloud SY | sy.bc-intg.liveperson.net |
Google Cloud Platform PROD | cbsrvc-us-p.liveperson.net |
Also review the API terms of use.
Requirements
If you have IP restrictions in place, you'll need to do some whitelisting before using this API.
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"}]}'
Retrieving the Web View variables
Use the Get Web View Variables JavaScript functions to retrieve the variables set via the Web View API from the bot runtime.
Example guide
See this step-by-step guide that uses this API.