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 for analytics and reporting purposes. Use this endpoint when your system handles agent messaging externally and you want Moveo to track the full conversation, including agent replies.

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

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

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.