Actions Webhook

Actions webhook

The actions’ webhook only receive action events, which means no eventType parameter is defined. This webhook is used to execute custom routines in your application, like updating the system with the information that the bot has collected about a customer.

The action should be executed SYNCHRONOUSLY, and it should return a response to the bot with a list of parameters That can be stored in the conversation session if necessary. These parameters can later be used to drive the dialog or in other actions.

For more information on Actions, see the Actions and Metadata article

In our template project, this webhook is defined under the url /action-webhook, but it can be defined under any url.

Request payload

The payload received in the custom CRM actions webhook looks like:

Field	Type	Description
botId	string	The ID of the bot
conversationId	string	ULTIMATE internal ID (can be ignored)
platformConversationId	string	The ID of the conversation
name	string	The name of the action (ie `updateCustomerBalance`)
data	ActionData[]	The parameters of the Action request. Each object of type `ActionData` in the array needs to contain the following fields: key `string` - key of the parameter value `string` - value of the parameter saveAs `string` - name for this parameter when saved in conversation

An example in JSON format:

{
  "botId" : "BOT_ID",
  "conversationId": "CONVERSATION_ID",
  "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5"
  "name": "updateCustomerBalance",
  "data": [
    {
      "key": "userId",
      "value": [ "123345" ],
      "saveAs?": "customerId"
    },
    {
      "key": "balance",
      "value": [ "100" ]
    }
  ]
}

Response payload

As mentioned above, the action webhook can optionally return a response to the bot with a list of parameters to be stored in the conversation session.

The structure of the response is:

Field	Type	Description
results	ActionResult[]	List of key/value pairs to be stored in Ultimate conversation session

Each actionResult object needs to be defined:

Field	Type	Description
key	string	Name of the variable to create in the conversation session
value	string or number or boolean	Value of the variable to create in the conversation session
sanitize	boolean	Marks if the value should be sanitised

An example in JSON format:

{
  "results": [
    {
      "key": "userId",
      "value": "123345"
    },
    {
      "key": "newBalance",
      "value": "210",
      "sanitize": true
    }
  ]
}