Bot/Agent commands and requests
A bot or an agent can send info requests and commands to the visitor.
The commands are sent using the conversation data endpoint: /conversation/${conversationId}/Data
Commands
Commands can be sent to the visitor which will execute them. Some commands return a commandResponse while others are fire and forget.
They can be used for disabling the chat input when showing rich content that the visitor should interact with or navigating the visitor.
| Parameter | required/optional | Value |
|---|---|---|
| dataType | required | Is set to command |
| id | optional | A unique id for the command |
| type | required | The name of the command |
| params | optional | command parameters if any |
{
dataType: 'command',
data: {
id: 'uniqueId',
type: 'command name',
...params
}
}Command response
The response returned after a command.
| Parameter | Value |
|---|---|
| dataType | Is set to commandResponse |
| eventId | eventId of the command request |
| id | The same unique id as for the command. |
| type | The same type as the command. |
| status | success or error |
| values | values returned if any. |
{
dataType: 'commandResponse',
data: {
eventId: 'eventId of the command',
id: 'uniqueId',
type: 'requestType',
status: 'success/error'
...values
}
}Info request
Info requests are used for getting information from the visitor. The info response returns the result.
They are used for things like, requesting a value of an element matched by a html selector or getting the visitor time.
| Parameter | required/optional | Value |
|---|---|---|
| dataType | required | Is set to infoRequest |
| id | optional | A unique id for the infoRequest. |
| type | required | The type of info request |
| params | optional | Additional parameters used by the infoRequest |
{
dataType: 'infoRequest',
data: {
id: 'uniqueId',
type: 'requestType',
...params
}
}Info response
The response returned from an info request. This is only used by the visitor.
| Parameter | Value |
|---|---|
| dataType | Is set to infoResponse |
| eventId | eventId of the info request |
| id | The same unique id as for the infoRequest. |
| type | The same type as the infoRequest |
| status | success or error |
| values | values returned |
{
dataType: 'infoResponse',
data: {
eventId: 'eventId of the request',
id: 'uniqueId',
type: 'requestType',
status: 'success/error'
...values
}
}Status
| Status | description |
|---|---|
ok | Everything worked |
error|invalidSelector | This error is related to commands that use selectors. The selector could not be resolved. |
error|originMismatch | This error is related to the navigateTo command. The provided url was of a different origin. |
error|cancelled | This error is related to the navigateTo command. The navigateTo was cancelled by the user. |
error|notAllowed | This error occurs when trying to get the co browsing dom when the co-browsing is denied by the user |
error|functionNotFound | This error is related to the callVisitorApi command. The specified function was not found on window.pzl.api |
error|executionError | This error is related to the callVisitorApi command. The called api function threw an error during execution |
Examples
Example for getting the visitor time
{
dataType: 'infoRequest',
data: {
id: 'uniqueId',
type: 'getLocalTime',
}
}Response
{
dataType: 'commandResponse',
data: {
eventId: 'infoRequestEventId',
id: 'uniqueId',
type: 'getLocalTime',
status: 'success',
value: '2024-02-28T07:43:09.039Z'
}
}Example command for disabling the chat input
{
dataType: 'command',
data: {
id: 'uniqueId',
type: 'disableChatInput',
value: true
}
}Response
{
dataType: 'commandResponse',
data: {
eventId: 'command event id',
id: 'uniqueId',
type: 'disableChatInput',
status: 'success',
value: true/false
}
}navigateTo
{
dataType: 'command',
data: {
id: 'uniqueId',
type: 'navigateTo',
url: 'url'
}
}Response
{
dataType: 'commandResponse',
data: {
eventId: 'command event id',
id: 'uniqueId',
type: 'navigateTo',
url: 'url',
status: 'success/error'
}
}Command API currently implemented
disableChatInput
{
dataType: 'command',
data: {
id: <uniqueId>,
type: 'disableChatInput',
value: true/false
}
}Response (successful)
{
dataType: 'commandResponse',
data: {
id: <uniqueId>,
eventId: 'command event id'
status: 'success'
}
}highlightDom
If the highlight fails the status will be set to error. The colors property is optional and so are the individual colors within it. They will default to yellow, red and black.
{
dataType: 'command',
data: {
id: <uniqueId>,
type: 'highlightDom',
selector: 'xPathSelector',
label: 'text'
colors: {
background: 'yellow',
square: 'red',
label: 'black',
}
}
}highlightDom using rect
If you set the selector to empty and supply a rect with top, left, width and height it will use the rect for highlight instead. The values in the rect are css values, so you can use relative coordinates or static.
{
dataType: 'command',
data: {
id: <uniqueId>,
type: 'highlightDom',
selector: '',
label: 'text'
rect: {
top: '10px',
left: '20%',
width: '30%',
height: '100px'
}
}
}initiateCoBrowse
The agent can initiate coBrowse by sending initiateCoBrowse with a starting state.
The visitor can revoke the permission at any time, thus disabling coBrowse for the agent.
The response is sent when the visitor has consented or denied permission to coBrowse.
| co-browse states | description |
|---|---|
requestPermission | This will prompt the visitor for coBrowse consent |
active | This will start coBrowse without visitors consent |
disabled | This will end the coBrowse session. |
{
dataType: 'command',
data: {
id: <uniqueId>,
type: 'initiateCoBrowse',
coBrowseState: 'requestPermission'
}
}Response
{
dataType: 'commandResponse',
data: {
id: <uniqueId>,
eventId: 'command event id',
type: 'initiateCoBrowse',
coBrowseState: 'active'
status: 'success/error'
}
}callVisitorApi
Calls a function on the visitor's window.pzl.api object. This allows bots and agents to execute visitor API functions remotely, such as setting claims, triggering identification flows, etc.
The function is called with the provided arguments, and the result (or error) is returned in the command response.
The command takes the following properties:
| Parameter | required/optional | Value |
|---|---|---|
id | optional | A unique id for the command |
type | required | 'callVisitorApi' |
functionName | required | The name of the function to call on window.pzl.api |
args | optional | An array of arguments to pass to the function |
Example command:
{
"dataType": "command",
"data": {
"id": "<uniqueId>",
"type": "callVisitorApi",
"functionName": "setClaims",
"args": [{ "customerId": "12345", "tier": "premium" }]
}
}Response (successful)
{
"dataType": "commandResponse",
"data": {
"id": "<uniqueId>",
"eventId": "command event id",
"type": "callVisitorApi",
"result": null,
"status": "success"
}
}Error Response (function not found)
{
"dataType": "commandResponse",
"data": {
"id": "<uniqueId>",
"eventId": "command event id",
"type": "callVisitorApi",
"functionName": "nonExistentFunction",
"args": [],
"result": "Error message from the function",
"status": "error|functionNotFound"
}
}Error Response (execution error)
{
"dataType": "commandResponse",
"data": {
"id": "<uniqueId>",
"eventId": "command event id",
"type": "callVisitorApi",
"functionName": "someFunction",
"args": ["invalid argument"],
"result": "Error message from the function",
"status": "error|executionError"
}
}See the Visitor Front-End API - documentation for all available visitor api functions
Info request API currently implemented
getLocalTime
{
dataType: 'infoRequest',
data: {
id: <uniqueId>,
type: 'getLocalTime'
}
}getLocalTime response
{
dataType: 'commandResponse',
data: {
id: <uniqueId>,
eventId: 'command event id',
type: 'getLocalTime',
status: 'success',
value: '2024-02-28T07:43:09.039Z'
}
}