Sending messages

Send user message

Sends a message from the end-user to the AI Agent. The response is delivered asynchronously to your webhook.

POST /v1/custom/:integration_id/sessions/:session_id/messages

Path parameters

Parameter	Type	Required	Description
integration_id	UUID	Yes	Your custom integration ID.
session_id	UUID	Yes	The session ID from the create session response.

Request body

{
  "input": {
    "text": "Hello, I need help with my order",
    "attachments": [
      {
        "type": "image",
        "mime_type": "image/png",
        "url": "https://example.com/uploads/screenshot.png",
        "filename": "error-screenshot.png"
      }
    ]
  },
  "context": {
    "current_page": "order-tracking"
  }
}

Field	Type	Required	Description
input	object	Yes	The message input.
input.text	string	No*	Text message content.
input.attachments	array	No*	Array of attachments. See attachment object.
context	object	No	Context updates. See context object.

*Either text or attachments must be provided. The message cannot be empty.

Response — 202 Accepted

{
  "request_id": "550e8400-e29b-41d4-a716-446655440002"
}

Example

curl -X POST "https://channels.moveo.ai/v1/custom/YOUR_INTEGRATION_ID/sessions/SESSION_ID/messages" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Hello, I need help with my order"
    }
  }'

---

Send agent message

Records a message from an external human agent into the conversation history. Use this endpoint when your system handles agent messaging externally and you want Moveo to track the full conversation, including agent replies.

Hands the session over

If the session has not been handed over yet, this endpoint hands it over before recording the message, so the AI Agent stops replying alongside your human agent. Sessions the AI Agent has never processed are left as they are. You do not need to call handover first, though doing so is safe.

POST /v1/custom/:integration_id/sessions/:session_id/messages/agent

Path parameters

Parameter	Type	Required	Description
integration_id	UUID	Yes	Your custom integration ID.
session_id	UUID	Yes	The session ID.

Request body

{
  "input": {
    "text": "Hi, I'm Sarah and I'll help you today."
  },
  "agent": {
    "agent_id": "agent-123",
    "agent_name": "Sarah Johnson",
    "agent_avatar": "https://example.com/avatars/sarah.jpg",
    "team_id": "support-team"
  }
}

Field	Type	Required	Description
input	object	Yes	The message input (same as send user message).
input.text	string	No*	Text message content.
input.attachments	array	No*	Array of attachments.
agent	object	No	Agent identity information. Defaults to "External Agent" if not provided.
agent.agent_id	string	No	Agent's unique identifier.
agent.agent_name	string	No	Agent's display name.
agent.agent_avatar	string	No	URL to agent's avatar image.
agent.team_id	string	No	Agent's team or department ID.

*Either text or attachments must be provided.

Response — 202 Accepted

{
  "request_id": "550e8400-e29b-41d4-a716-446655440003"
}

---

Mark messages as read

Marks messages as read up to a given timestamp. If no timestamp is provided, the current time is used.

POST /v1/custom/:integration_id/sessions/:session_id/messages/read

Path parameters

Parameter	Type	Required	Description
integration_id	UUID	Yes	Your custom integration ID.
session_id	UUID	Yes	The session ID.

Request body

{
  "timestamp": 1789084800000
}

Field	Type	Required	Description
timestamp	integer	No	Unix timestamp in milliseconds. Defaults to the current time.

Response — 200 OK

{
  "request_id": "550e8400-e29b-41d4-a716-446655440011"
}

---

Mark messages as delivered

Marks messages as delivered up to a given timestamp. If no timestamp is provided, the current time is used.

POST /v1/custom/:integration_id/sessions/:session_id/messages/delivered

Path parameters

Parameter	Type	Required	Description
integration_id	UUID	Yes	Your custom integration ID.
session_id	UUID	Yes	The session ID.

Request body

{
  "timestamp": 1789084800000
}

Field	Type	Required	Description
timestamp	integer	No	Unix timestamp in milliseconds. Defaults to the current time.

Response — 200 OK

{
  "request_id": "550e8400-e29b-41d4-a716-446655440012"
}

---

Attachment object

Used in message inputs for both user and agent messages.

Field	Type	Required	Description
type	string	Yes	Attachment type: image, audio, video, or file.
mime_type	string	Yes	MIME type (e.g., image/jpeg, audio/mp3, application/pdf).
url	string	No	URL to the attachment file.
id	string	No	Attachment identifier (use with presigned URLs from the file upload endpoint).
title	string	No	Display title for the attachment.
filename	string	No	Original filename.