Webhook event payloads

This page documents the payload schema for each webhook event type. All payloads include the base fields (event_type, request_id, session_id, external_session_id, integration_id, desk_id, channel_type, account_id, account_slug, and context), plus the timestamp carried by the event itself. The examples below show a representative subset of the base fields rather than repeating all of them.

AI agent message

Event type: message:brain_send

Sent when the AI agent responds to the user. The output.responses array contains one or more response objects.

{
  "event_type": "message:brain_send",
  "request_id": "req-123",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "output": {
    "responses": [
      {
        "type": "text",
        "text": "Hello! How can I help you today?",
        "options": [
          {
            "label": "Check Order",
            "text": "I want to check my order"
          },
          {
            "label": "Support",
            "text": "I need support"
          }
        ]
      }
    ]
  }
}

Response types

The output.responses array can contain multiple response objects. Each response has a type field and an action_id — the identifier of the dialog action that produced it, stable across sessions and useful for correlating a response with the dialog node that emitted it.

Type	Description
`text`	Plain text message, optionally with quick reply options.
`image`	Image attachment.
`video`	Video attachment.
`file`	File attachment.
`url`	A URL for your system to open or render.
`carousel`	Multiple cards with buttons.
`webview`	Open a webview.
`survey`	A survey to present to the user.
`handover`	Transfer to a human agent.
`close`	The AI Agent ended the conversation.
`pause`	A delay before the next response, optionally showing a typing indicator.
`whatsapp_flow`	A WhatsApp Flow. Only emitted by agents built for WhatsApp.

Moveo may also emit the internal types replay and reminder. They carry no message for the user — ignore any response type you do not handle rather than treating it as an error.

Text response

{
  "type": "text",
  "text": "Here's your order status.",
  "options": [
    {
      "label": "Track Order",
      "text": "Track my order"
    }
  ]
}

Field	Type	Description
`type`	string	`"text"`
`text`	string	The message text.
`options`	array	Optional quick reply buttons.
`options[].label`	string	Button label displayed to the user.
`options[].text`	string	The value associated with this option. Your system is responsible for handling the button click and sending this text back as a user message if needed.

Image response

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

Field	Type	Description
`type`	string	`"image"`
`url`	string	Image URL.
`name`	string	Optional image name/caption.

Video response

{
  "type": "video",
  "url": "https://example.com/video.mp4",
  "name": "Tutorial Video",
  "size": 5242880
}

URL response

{
  "type": "url",
  "url": "https://example.com/order/12345"
}

Field	Type	Description
`type`	string	`"url"`
`url`	string	The URL to open or render.

File response

{
  "type": "file",
  "url": "https://example.com/document.pdf",
  "name": "Invoice.pdf",
  "size": 102400
}

Field	Type	Description
`type`	string	`"file"`
`url`	string	File download URL.
`name`	string	Filename.
`size`	integer	File size in bytes (optional).

Carousel response

{
  "type": "carousel",
  "cards": [
    {
      "title": "Product A",
      "subtitle": "$29.99",
      "media": {
        "type": "image",
        "url": "https://example.com/product-a.jpg"
      },
      "buttons": [
        {
          "type": "postback",
          "label": "Buy Now",
          "trigger_node_id": "node-buy-product-a"
        },
        {
          "type": "url",
          "label": "Learn More",
          "url": "https://example.com/product-a"
        }
      ]
    }
  ]
}

Field	Type	Description
`type`	string	`"carousel"`
`cards`	array	Array of card objects. Between 1 and 6.
`cards[].title`	string	Card title.
`cards[].subtitle`	string	Card subtitle.
`cards[].media`	object	Card image or video (optional).
`cards[].media.type`	string	`"image"` or `"video"`.
`cards[].media.url`	string	Media URL.
`cards[].buttons`	array	Action buttons.
`cards[].buttons[].type`	string	`"postback"`, `"url"`, `"webview"`, `"phone"`, or `"event"`.
`cards[].buttons[].label`	string	Button text.
`cards[].buttons[].url`	string	URL for `url`, `webview`, and `phone` buttons.
`cards[].buttons[].trigger_node_id`	string	Dialog node triggered by `postback` and `event` buttons.
`cards[].buttons[].height`	string	Webview height for `webview` buttons.
`cards[].buttons[].auto_open`	boolean	Whether a `webview` button opens automatically.
`cards[].default_action`	object	Optional button applied when the card itself is tapped.

Handover response

Signals that the AI Agent is transferring the conversation to a human agent. The AI Agent stops replying from this point on.

{
  "type": "handover",
  "metadata": {
    "zendesk_department_id": "support"
  }
}

Field	Type	Description
`type`	string	`"handover"`
`metadata`	object	Optional flat key-value map configured on the dialog action, used to route the transfer.
`department_id`	string	Deprecated. A target department set on older agents, still sent where it was configured. Prefer `metadata`.

Any message shown to the user before a transfer arrives as a separate text response, not as a field on this one.

Close response

Signals that the AI Agent ended the conversation.

{
  "type": "close"
}

Pause response

A deliberate delay before the next response, used to pace a multi-part reply.

{
  "type": "pause",
  "duration": 2,
  "show_typing": true
}

Field	Type	Description
`type`	string	`"pause"`
`duration`	integer	Delay in seconds.
`show_typing`	boolean	Whether to show a typing indicator for the duration.

Webview response

{
  "type": "webview",
  "url": "https://example.com/form",
  "name": "Order form",
  "label": "Fill out form",
  "height": "full",
  "auto_open": false
}

Field	Type	Description
`type`	string	`"webview"`
`url`	string	Webview URL.
`name`	string	Webview name.
`label`	string	Button label.
`height`	string	`"full"`, `"tall"`, `"compact"`, or `"new_window"`.
`auto_open`	boolean	Whether the webview should open without the user tapping the button.

A survey response has the same fields as a webview response and points at a survey URL.

Human agent message

Event type: message:send

Sent when a human agent from Moveo's live chat replies to the user.

{
  "event_type": "message:send",
  "request_id": "req-456",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "from": {
    "agent_id": "agent-123",
    "agent_name": "Sarah Johnson",
    "agent_avatar": "https://example.com/avatars/sarah.jpg",
    "team_id": "support-team"
  },
  "to": {
    "user_id": "user-789"
  },
  "body": {
    "text": "Hi! I'm Sarah from support. How can I help you?",
    "attachments": []
  }
}

Field	Type	Description
`from.agent_id`	string	Agent's unique identifier.
`from.agent_name`	string	Agent's display name.
`from.agent_avatar`	string	URL to agent's avatar (optional).
`from.team_id`	string	Agent's team/department ID (optional).
`to.user_id`	string	Target user ID.
`body.text`	string	Message text.
`body.attachments`	array	Attachments (same format as input attachments).

Typing indicator

Event type: message:compose

Sent when someone starts or stops typing.

{
  "event_type": "message:compose",
  "request_id": "req-789",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "author_id": "agent-123",
  "author_name": "Sarah Johnson",
  "author_type": "agent",
  "action": "start"
}

Field	Type	Description
`author_id`	string	ID of the person typing.
`author_name`	string	Name of the person typing.
`author_type`	string	`"agent"` or `"brain"`.
`action`	string	`"start"` or `"stop"`.

Message read

Event type: message:read

Sent when messages are marked as read.

{
  "event_type": "message:read",
  "request_id": "req-101",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "author_type": "agent"
}

Field	Type	Description
`author_type`	string	Who marked messages as read: `"agent"`, `"brain"`, or `"visitor"`.

Message delivered

Event type: message:delivered

Sent when messages are confirmed delivered.

{
  "event_type": "message:delivered",
  "request_id": "req-102",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "author_type": "brain"
}

Member join

Event type: conversation:member_join

Sent when an agent joins the conversation.

{
  "event_type": "conversation:member_join",
  "request_id": "req-103",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "author_id": "agent-123",
  "author_name": "Sarah Johnson",
  "author_type": "agent"
}

Member leave

Event type: conversation:member_leave

Sent when an agent leaves the conversation.

{
  "event_type": "conversation:member_leave",
  "request_id": "req-104",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "author_id": "agent-123",
  "author_name": "Sarah Johnson",
  "author_type": "agent"
}

Conversation closed

Event type: conversation:closed

Sent when a conversation is marked as resolved.

{
  "event_type": "conversation:closed",
  "request_id": "req-105",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "status": "resolved",
  "agent_id": "agent-123",
  "agent_name": "Sarah Johnson"
}

Conversation reopened

Event type: conversation:reopened

Sent when a resolved conversation is reopened.

{
  "event_type": "conversation:reopened",
  "request_id": "req-106",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000
}

Session closed

Event type: session:closed

Sent when a session is explicitly closed.

{
  "event_type": "session:closed",
  "request_id": "req-107",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000,
  "status": "closed"
}

Session expired

Event type: session:expired

Sent when a session expires due to inactivity timeout.

{
  "event_type": "session:expired",
  "request_id": "req-108",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000
}

AI agent message​

Response types​

Human agent message​

Typing indicator​

Message read​

Message delivered​

Member join​

Member leave​

Conversation closed​

Conversation reopened​

Session closed​

Session expired​