Sending and receiving messages

The message exchange follows a specific flow with various events that can be triggered by both the client and server. Here's a breakdown of all possible events in a conversation, their direction, and their payloads:

Client to server events

Client sends message (message:send)

This is the primary event for sending messages from the client to the server. Messages can include text, media attachments, or both.

Field	Type	Required	Description
input.text	string	No	The text content of the message
input.attachments	array	No	Array of media attachments
session_id	string	Yes	Unique identifier for the conversation session
timestamp	integer	Yes	Unix timestamp in milliseconds

warning

The input object is optional, but sending an empty message to the AI Agent

will not trigger any response. This results in an empty output.responses array.

Attachment fields

Field	Type	Required	Description
type	string	Yes	Type of attachment: "audio", "image", "video", "file"
mime_type	string	Yes	MIME type of the attachment
id	string	No	Unique identifier for the attachment
url	string	No	URL where the attachment can be accessed
title	string	No	Display title for the attachment
filename	string	No	Original filename of the attachment

important

The attachment url must be the upload_url received from the upload process

. Other URLs are not supported.

{
  "input": {
    "text": "Hello, I need help with my order",
    "attachments": [
      {
        "type": "image",
        "mime_type": "image/jpeg",
        "url": "<presigned-url>",
        "title": "Order Screenshot"
      }
    ]
  },
  "session_id": "70e33a98-b55f-4500-bb62-f29cc7049356",
  "timestamp": 1744036886028
}

Client sends typing indicator (message:compose)

Indicates that the user has started or stopped typing.

Field	Type	Required	Description
session_id	string	Yes	Unique identifier for the conversation session
timestamp	integer	Yes	Unix timestamp in milliseconds
action	string	Yes	Typing action: "start" or "stop"

{
  "session_id": "70e33a98-b55f-4500-bb62-f29cc7049356",
  "timestamp": 1744036886028,
  "action": "start" // or "stop"
}

Client marks message as read (message:read)

Indicates that the user has viewed a message.

Field	Type	Required	Description
session_id	string	Yes	Unique identifier for the conversation session
timestamp	integer	Yes	Unix timestamp in milliseconds

{
  "session_id": "70e33a98-b55f-4500-bb62-f29cc7049356",
  "timestamp": 1744036886030
}

Client confirms message delivery (message:delivered)

Indicates that a message has been delivered to the user.

Field	Type	Required	Description
session_id	string	Yes	Unique identifier for the conversation session
timestamp	integer	Yes	Unix timestamp in milliseconds

{
  "session_id": "70e33a98-b55f-4500-bb62-f29cc7049356",
  "timestamp": 1744036886029
}

Server to client events

Server sends message (message:received or message:brain_received)

Messages can be received from either an AI Agent or a Human Agent, each with a different event type and payload structure.

• For AI Agent responses (message:brain_received):

  Field	Type	Required	Description
  session_id	string	Yes	Unique identifier for the conversation session
  output.responses	array	Yes	Array of response objects
  timestamp	integer	Yes	Unix timestamp in milliseconds
  brain_language	string	Yes	Language code of the AI response
  request_id	string	Yes	Unique identifier for the request

• For Human Agent responses (message:received):

  Field	Type	Required	Description
  session_id	string	Yes	Unique identifier for the conversation session
  from.agent_id	string	Yes	ID of the human agent
  from.team_id	string	No	ID of the agent's team
  from.agent_name	string	No	Display name of the agent
  from.agent_avatar	string	No	URL to the agent's avatar image
  to.user_id	string	Yes	ID of the user receiving the message
  body.text	string	No	Text content of the message
  body.attachments	array	No	Array of media attachments
  timestamp	integer	No	Unix timestamp in milliseconds

Server sends typing indicator (message:compose)

Indicates when an agent (human or AI) starts or stops typing.

// Human Agent sending typing indicator
{
  "session_id": "70e33a98-b55f-4500-bb62-f29cc7049356",
  "author_id": "b4c22e23-4b82-45e0-9a12-1c2572ba52c9",
  "desk_id": "0f05b1b1-5b82-45e2-a477-6443dd2b9d79",
  "author_name": "John Doe",
  "timestamp": 1744036886028,
  "author_type": "agent",
  "action": "start"  // or "stop"
}

// AI Agent sending typing indicator
{
  "session_id": "77ce27e2-676a-4536-a7d1-0deec8499ade",
  "author_id": "d6197ecf-5a8d-405d-94e5-65e9ab747850",
  "timestamp": 1744037057045,
  "author_type": "brain",
  "action": "start"  // or "stop"
}

Server confirms message delivery (message:delivered)

Indicates that a message has reached its destination.

Field	Type	Required	Description
session_id	string	Yes	Unique identifier for the conversation session
author_type	string	Yes	Type of author: "brain", "agent", or "visitor"
timestamp	integer	Yes	Unix timestamp in milliseconds

{
  "session_id": "70e33a98-b55f-4500-bb62-f29cc7049356",
  "author_type": "visitor",
  "timestamp": 1744036886029
}

AI Agent response types

When the AI Agent responds with a synthetic response using its knowledge

, it can only be of the text type. Other response types are available when the AI Agent returns a dialog response.

Text response

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

Field	Type	Required	Description
type	string	Yes	Must be "text"
texts	array	Yes	Array of text messages to send
options	array	No	Array of quick reply options

Option fields:

Field	Type	Required	Description
text	string	Yes	The text sent back when the option is selected
label	string	Yes	Display label for the option

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

Media response

Used to send media files such as images, videos, audio, or files.

Field	Type	Required	Description
type	string	Yes	One of "image", "video", "audio", "file"
url	string	Yes	URL where the media can be accessed
name	string	No	Display name for the media
size	number	No	Size of the file in bytes
action_id	string	Yes	Unique identifier for tracking interactions

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

Carousel response

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

Field	Type	Required	Description
type	string	Yes	Must be "carousel"
cards	array	Yes	Array of card objects
action_id	string	Yes	Unique identifier for tracking interactions

Card fields:

Field	Type	Required	Description
title	string	Yes	Title of the card
subtitle	string	No	Subtitle or description
media	object	No	Media object with type and URL
buttons	array	No	Array of button objects
default_action	object	No	Default action when card is clicked

Button 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",
    "trigger_node_id": "string"
  }

{
  "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"
}

Webview response

Used to display a webview within the chat interface.

Field	Type	Required	Description
type	string	Yes	Must be "webview"
name	string	Yes	Display name for the webview
label	string	Yes	Button label to open the webview
url	string	Yes	URL to load in the webview
height	string	No	Height of the webview ("tall", "compact", "full")
trigger_node_id	string	No	ID of the node to trigger when opened
action_id	string	Yes	Unique identifier for tracking interactions

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

Survey response

Used to send a survey to the user.

Field	Type	Required	Description
type	string	Yes	Must be "survey"
url	string	Yes	URL of the survey form
name	string	Yes	Display name for the survey
label	string	Yes	Button label to open the survey
height	string	No	Height of the survey form ("tall", "compact", "full")
trigger_node_id	string	No	ID of the node to trigger when opened
action_id	string	Yes	Unique identifier for tracking interactions

{
  "type": "survey",
  "url": "https://webhooks.moveo.ai/common/survey?channel=web&integration_id=c3725769-d20e-4391-9f15-63f47eefe211&lang=en&session_id=8f4e66a4-c95b-4287-b1c0-bbb9a7bcc5b7&user_id=UouxR137cqf_YaRQvRKgI",
  "name": "Survey",
  "label": "Fill survey",
  "height": "tall",
  "trigger_node_id": "123e4567-e89b-12d3-a456-426614174000",
  "action_id": "1c46cb13-ebb7-4aed-ade7-9cb09a75cf1b"
}