Dialog Webhooks

Dialog webhooks are triggered as dialog actions within your AI Agent conversations. Moveo.AI sends information to your custom endpoint using simple HTTP POST calls whenever a webhook action is triggered within your dialog.

You can use dialog webhooks to perform the following actions:

Validate information collected from the user.
Send requests to an external application, such as checking the application status of a customer or accessing your inventory to see if a product is available for shipping.
Trigger an SMS notification or OTP verification.

info

For common webhook configurations like verifying origin and IP whitelisting, see the Webhooks Overview.

Receiving calls

Whenever a dialog webhook is triggered, Moveo.AI sends a payload of the following format (JSON) to your webhook URL.

Example

{
  "channel": "web",
  "session_id": "00d2ff33-706e-4a2c-8544-df6c9d0c1ecf",
  "brain_id": "d3d08940-f0ef-42e0-993c-1bea065dcqwe",
  "lang": "en",
  "context": {
    "total_months": 3,
    "destination": "England",
    "sys-unknown_counter": 0,
    "sys-channel": "web",
    "sys-user_message_counter": 1,
    "total_expenses": 500
  },
  "input": {
    "text": "Hello, my name is George and I would like to go for erasmus"
  },
  "intents": [
    {
      "intent": "erasmus",
      "confidence": 0.89
    }
  ],
  "entities": [
    {
      "entity": "firstname",
      "value": "George",
      "start": 18,
      "end": 36,
      "confidence": 1,
      "type": "user"
    }
  ],
  "tags": ["erasmus", "destination"],
  "debug": {
    "dialog_stack": [
      {
        "node_id": "35411a26-cff7-4fb3-a2e9-0e8e6ada048a",
        "name": "greetings"
      },
      {
        "node_id": "a85b10e8-e7f3-40df-9715-196c4eae5f14",
        "name": "plan_erasmus"
      }
    ]
  }
}

Reference

Outer level

Property	Type	Description
channel	string	Channel name the message is coming from ("viber", "web" etc.)
session_id	string	The ID representing the user that triggered the webhook call
brain_id	string	The ID representing the AI Agent for the webhook call
verify_token	string	The verify token you specified in the webhook configuration
context	Context	Context variables that have been collected for that user so far
input	Input	The user input that triggered the dialog node
intents	Intent	List of intents recognized, sorted by confidence
entities	Entity	List of entities recognized in the user input
debug	Debug	Information related to debugging the Moveo.AI dialog state

Context

Context consists of key-value pairs with the keys representing context variables names and values capturing the user input.

Input

Property	Type	Description
text	string	The text that was typed by the user

Intent

Property	Type	Description
intent	string	The intent name
confidence	float	The confidence for that intent (between 0 and 1)

Entity

Property	Type	Description
entity	string	The entity type
value	string	The entity value from the user's input
start	integer	Start index of the value within the user's text
end	integer	End index of the value within the user's text
confidence	float	Entity detection confidence
type	string	Type of entity (ie. "user", "system" etc.)

Debug/Dialog stack

Property	Type	Description
node_id	string	The node id as defined in the dialog
name	string	The node name as defined in the dialog

Sending replies

The webhook expects a JSON response with a specific structure. The response must be a JSON object containing either a context dictionary or a responses array, or both.

context: An object containing key-value pairs for session-specific data.
responses: An array of response objects, each specifying a particular type of response.

Context object

The context object is used to store session-specific data that can be passed between requests to maintain state.

Requirements:

Must be a JSON object.
Cannot include the following reserved keywords:
- "global"
- "channels"

Example:

{
  "context": {
    "selected_product": "apples",
    "amount": "6"
  }
}

Responses array

The responses array contains response objects that define how the AI Agent should respond to the user.

Requirements:

Must be a JSON array.
Each element must be a JSON object.
Each response object must have a "type" field.

Supported response types:

"text"
"image"
"video"
"audio"
"file"
"event"
"carousel"
"webview"
"reset"

Response object types

1. Text response

Used to send text messages, possibly with quick reply options.

Schema:

{
  "type": "text",
  "texts": [ "string" ],
  "options": [ { ... } ] // optional
}

Fields:

type (string): Must be "text".
texts (array of strings): The text messages to send.
- Required.
options (array of option objects): Quick reply options.
- Optional.
- Minimum 1, maximum 10 options.

Option object:

{
  "text": "string",
  "label": "string"
}

text (string): The text sent back when the option is selected.
- Required.
- Minimum length: 1 character.
label (string): The display label for the option.
- Required.
- Minimum length: 1 character.
- Maximum length: 64 characters.

Example:

{
  "type": "text",
  "texts": ["Hello! How can I assist you today?"],
  "options": [
    {
      "text": "I need help",
      "label": "Help"
    },
    {
      "text": "Just browsing",
      "label": "Browse"
    }
  ]
}

2. Media response

Used to send media files like images, videos, audio, or files.

Schema:

{
  "type": "string",
  "url": "string",
  "name": "string", // optional
  "size": integer // optional
}

Fields:

type (string): One of "image", "video", "audio", "file".
- Required.
url (string): The URL of the media file.
- Required.
- Must be a valid URI.
name (string): The name of the file.
- Optional.
size (integer): The size of the file in bytes.
- Optional.

Example:

{
  "type": "image",
  "url": "https://example.com/image.jpg",
  "name": "Sample Image",
  "size": 102400
}

3. Event response

Used to trigger specific events in the conversation flow.

Schema:

{
  "type": "event",
  "trigger_node_id": "string"
}

Fields:

type (string): Must be "event".
- Required.
trigger_node_id (string): The UUID of the node to trigger.
- Required.
- Must match the UUID format.

Example:

{
  "type": "event",
  "trigger_node_id": "123e4567-e89b-12d3-a456-426614174000"
}

4. Carousel response

Used to send a carousel of cards, each with media, title, subtitle, and buttons.

Schema:

{
  "type": "carousel",
  "cards": [ { ... } ],
  "action_id": "string"
}

Fields:

type (string): Must be "carousel".
- Required.
cards (array of card objects): The carousel cards.
- Required.
- Minimum 1, maximum 6 cards.
action_id (string): A UUID representing the action.
- Required.
- Must match the UUID format.

Card object:

{
  "media": { ... },
  "title": "string",
  "subtitle": "string", // optional
  "buttons": [ { ... } ], // optional
  "default_action": { ... } // optional
}

Fields:

media (object): The media associated with the card.
- Required.
- Must include:
  - url (string): Valid URI.
  - type (string): "image" or "video".
title (string): The title of the card.
- Required.
- Minimum length: 1 character.
- Maximum length: 64 characters.
subtitle (string): The subtitle of the card.
- Optional.
- Maximum length: 100 characters.
buttons (array of button objects): Interactive buttons.
- Optional.
- Minimum 1, maximum 3 buttons.
default_action (object): The default action when the card is tapped.
- Optional.
- Must be one of the action types defined below.

Button object:

Buttons can be of the following types:

Postback Button:

{
  "type": "postback",
  "label": "string",
  "value": "string"
}

URL Button:

{
  "type": "url",
  "label": "string",
  "url": "string"
}

Webview Button:

{
  "type": "webview",
  "label": "string",
  "url": "string",
  "height": "string", // "tall", "compact", "full"
  "trigger_node_id": "string" // optional
}

Default action object:

Same structure as the button object, but without the label field for postback and URL types.

Example:

{
  "type": "carousel",
  "cards": [
    {
      "media": {
        "url": "https://example.com/product1.jpg",
        "type": "image"
      },
      "title": "Product 1",
      "subtitle": "Description of product 1",
      "buttons": [
        {
          "type": "postback",
          "label": "Buy Now",
          "value": "buy_product_1"
        },
        {
          "type": "url",
          "label": "Learn More",
          "url": "https://example.com/product1"
        }
      ],
      "default_action": {
        "type": "url",
        "url": "https://example.com/product1"
      }
    }
  ],
  "action_id": "123e4567-e89b-12d3-a456-426614174000"
}

5. Webview response

Used to display a webview within the chat interface.

Schema:

{
  "type": "webview",
  "name": "string",
  "label": "string",
  "url": "string",
  "height": "string", // "tall", "compact", "full"
  "trigger_node_id": "string" // optional
}

Fields:

type (string): Must be "webview".
- Required.
name (string): The name of the webview.
- Required.
label (string): The label for the webview.
- Required.
url (string): The URL to load in the webview.
- Required.
- Must be a valid URI.
height (string): The height of the webview.
- Optional.
- Acceptable values: "tall", "compact", "full".
trigger_node_id (string): The UUID to trigger upon webview events.
- Optional.
- Must match the UUID format.

Example:

{
  "type": "webview",
  "name": "Survey",
  "label": "Visit our website",
  "url": "https://example.com/",
  "height": "full",
  "trigger_node_id": "123e4567-e89b-12d3-a456-426614174000"
}

6. Reset response

Used to reset the conversation or user context.

Schema:

{
  "type": "reset"
}

Fields:

type (string): Must be "reset".
- Required.

Example

Full response example with context and multiple responses

{
  "context": {
    "user": {
      "language": "en"
    }
  },
  "responses": [
    {
      "type": "text",
      "texts": ["Welcome back! What would you like to do today?"],
      "options": [
        {
          "text": "View Products",
          "label": "Products"
        },
        {
          "text": "Contact Support",
          "label": "Support"
        }
      ]
    },
    {
      "type": "carousel",
      "cards": [
        {
          "media": {
            "url": "https://example.com/product1.jpg",
            "type": "image"
          },
          "title": "Product 1",
          "buttons": [
            {
              "type": "postback",
              "label": "Buy Now",
              "value": "buy_product_1"
            }
          ]
        },
        {
          "media": {
            "url": "https://example.com/product2.jpg",
            "type": "image"
          },
          "title": "Product 2",
          "buttons": [
            {
              "type": "postback",
              "label": "Buy Now",
              "value": "buy_product_2"
            }
          ]
        }
      ]
    }
  ],
  "context": {
    "total_expenses": 100
  }
}

Reference

Outer level

Property	Type	Description
responses	Responses	List of responses that Moveo should use to respond to the user
context	dictionary	Key-value pairs that can be used to update user context variables

Responses

Property	Type	Description
type	string	Integration type
texts	string	List of texts that should be used to reply
name	string	Media name
url	string	Media URL

Receiving calls​

Example​

Reference​

Outer level​

Context​

Input​

Intent​

Entity​

Debug/Dialog stack​

Sending replies​

Context object​

Requirements:​

Example:​

Responses array​

Requirements:​

Supported response types:​

Response object types​

1. Text response​

Schema:​

Fields:​

Option object:​

Example:​

2. Media response​

Schema:​

Fields:​

Example:​

3. Event response​

Schema:​

Fields:​

Example:​

4. Carousel response​

Schema:​

Fields:​

Card object:​

Fields:​

Button object:​

Default action object:​

Example:​

5. Webview response​

Schema:​

Fields:​

Example:​

6. Reset response​

Schema:​

Fields:​

Example​

Full response example with context and multiple responses​

Reference​

Outer level​

Responses​

Receiving calls

Example

Reference

Outer level

Context

Input

Intent

Entity

Debug/Dialog stack

Sending replies

Context object

Requirements:

Example:

Responses array

Requirements:

Supported response types:

Response object types

1. Text response

Schema:

Fields:

Option object:

Example:

2. Media response

Schema:

Fields:

Example:

3. Event response

Schema:

Fields:

Example:

4. Carousel response

Schema:

Fields:

Card object:

Fields:

Button object:

Default action object:

Example:

5. Webview response

Schema:

Fields:

Example:

6. Reset response

Schema:

Fields:

Example

Full response example with context and multiple responses

Reference

Outer level

Responses