Receiving calls

Just like Cloud code Webhook integrations are triggered using actions. Simply drag and drop them below any trigger and select the action.

POST Request

Whenever a webhook is triggered Flow.ai sends along data in JSON format to your callback url .

{
  "type": "action",
  "verifyToken": "b34768df-4768-4768-8cfe-0ac99db46ca9",
  "threadId": "99eb45ed85a0a00cef41f55aa03bea17",
  "channelName": "socket",
  "query": "hi",
  "action": "onboarding",
  "params": {
  },
  "originator": {
    "actorId": "23249a99-a243-448b-asdf-daddd7bafb6c",
    "userId": "flowai|23249a99-1233-448b-ada1-daasafbafb6c",
    "name": "EN Bot",
    "role": "bot",
    "profile": {
      "description": "Flow.ai",
      "locale": "en",
      "picture": "https://flow.ai/img/brains/flowai.svg"
    }
  },
  "user": {
    "name": "Jane Doe",
    "role": "external",
    "profile": {
      "fullName": "Jane Doe",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "picture": "https://...",
      "locale": "nl",
      "timezone": 2,
      "gender": "M"
    }
  },
  "replyUrl": "https://..."
}

Reference

Property Description
type By default this is: action
verifyToken The verify token you specified in the webhook configuration
threadId The ID representing the thread that triggered the webhook call
channelName Name of the channel on which the Webhook call was triggered
query Optionally a user query that triggered this Webhook call
action Each action triggering a Webhook call can customise this. See the Design app
params Optional object with params retrieved by Flow.ai
originator The sender of the action
user The user that triggered the Webhook call
replyUrl Unique url to be used to reply to this thread on the correct channel

Action:

You can control the value of action, like in the example above (onboarding), from within the designer. This makes it easy to use a single endpoint with different actions.

Params

As with Cloud code you can expect a set of various params. For example a user shares a file or the bot detects a named entity.

{
  "type": "action",
  "verifyToken": "...",
  "threadId": "...",
  "channelName": "alexa",
  "query": "What is the weather like in Toronto?",
  "action": "get-weather-report",
  "params": {
    "city": [
      {
        "match": "Toronto",
        "type": "system.query",
        "value": "Toronto"
      }
    ]
  },
  ...
}

In the above example you can see that the engine extracted data and placed it into a params object. Each param is always a list (array) because you might get multiple results.

{
  "type": "action",
  "verifyToken": "...",
  "threadId": "...",
  "channelName": "amazon",
  "query": "What is the weather like in New York and Toronto?",
  "action": "get-weather-report",
  "params": {
    "city": [
      {
        "match": "New York",
        "type": "system.query",
        "value": "New York"
      },
      {
        "match": "Toronto",
        "type": "system.query",
        "value": "Toronto"
      }
    ]
  },
  ...
}

Reference

Property Description
value The extracted value
match Optionally, the piece of text that matched
type Optionally, the type of data that was extracted

Further reading