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, context, timestamp).

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": 1704067200000,
  "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:

Type	Description
`text`	Plain text message, optionally with quick reply options.
`image`	Image attachment.
`video`	Video attachment.
`audio`	Audio attachment.
`file`	File attachment.
`carousel`	Multiple cards with buttons.
`webview`	Open a webview.
`handover`	Transfer to human agent.
`pause`	Typing delay.

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

Audio response

{
  "type": "audio",
  "url": "https://example.com/audio.mp3",
  "name": "Voice Message"
}

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",
          "value": "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.
`cards[].title`	string	Card title.
`cards[].subtitle`	string	Card subtitle (optional).
`cards[].media`	object	Card image/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"`, or `"webview"`.
`cards[].buttons[].label`	string	Button text.
`cards[].buttons[].value`	string	Value for postback buttons.
`cards[].buttons[].url`	string	URL for url/webview buttons.

Handover response

{
  "type": "handover",
  "text": "Transferring you to a human agent...",
  "desk_id": "desk-123",
  "department_id": "support"
}

Field	Type	Description
`type`	string	`"handover"`
`text`	string	Message shown during transfer.
`desk_id`	string	Target desk ID (optional).
`department_id`	string	Target department (optional).

Webview response

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

Field	Type	Description
`type`	string	`"webview"`
`url`	string	Webview URL.
`label`	string	Button label.
`height`	string	`"full"`, `"tall"`, `"compact"`, or `"new_window"`.

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": 1704067200000,
  "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": 1704067200000,
  "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": 1704067200000,
  "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": 1704067200000,
  "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": 1704067200000,
  "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": 1704067200000,
  "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": 1704067200000,
  "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": 1704067200000
}

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": 1704067200000,
  "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": 1704067200000
}

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​