Sessions and conversations

Create session

Creates a new conversation session.

POST /v1/custom/:integration_id/sessions

Path parameters

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

Request body

{
  "external_session_id": "order-12345",
  "channel_user_id": "user-67890",
  "context": {
    "user": {
      "display_name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "language": "en"
    },
    "tags": ["vip", "returning-customer"],
    "global": {
      "client_url": "https://example.com/support"
    },
    "order_id": "ORD-12345",
    "subscription_tier": "premium"
  }
}

Field	Type	Required	Description
external_session_id	string	No	Your system's unique identifier for this session. Stored in context.channels.custom.external_session_id.
channel_user_id	string	No	Unique identifier for the user in your system. Stored in context.user.custom_psid.
context	object	No	Session context with user information and custom variables. See context object.

Response — 201 Created

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "660e8400-e29b-41d4-a716-446655440001",
  "context": {
    "user": { ... },
    "tags": [...],
    "global": { ... }
  }
}

Field	Type	Description
request_id	string	Unique identifier for this request.
session_id	UUID	The created session ID. Use this for all subsequent API calls.
context	object	The session context, which may include default values.

Example

curl -X POST "https://channels.moveo.ai/v1/custom/YOUR_INTEGRATION_ID/sessions" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_session_id": "order-12345",
    "channel_user_id": "user-67890",
    "context": {
      "user": {
        "display_name": "John Doe",
        "email": "john.doe@example.com",
        "language": "en"
      },
      "tags": ["vip"],
      "order_id": "ORD-12345"
    }
  }'

---

Update session context

Updates the context variables for an existing session without sending a message. Only the fields you include are updated.

PATCH /v1/custom/:integration_id/sessions/:session_id/context

Path parameters

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

Request body

Same structure as the context object in create session. Only included fields are updated.

{
  "user": {
    "email": "john.updated@example.com"
  },
  "tags": ["verified-user", "premium"],
  "account_status": "verified"
}

Response — 200 OK

{
  "request_id": "550e8400-e29b-41d4-a716-446655440004",
  "context": { ... }
}

Example

curl -X PATCH "https://channels.moveo.ai/v1/custom/YOUR_INTEGRATION_ID/sessions/SESSION_ID/context" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "email": "john.updated@example.com",
      "verified": true
    },
    "account_status": "verified",
    "tags": ["verified-user", "premium"]
  }'

---

Close session

Closes an existing session. This ends the session and triggers a session:closed webhook event.

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

Path parameters

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

Request body — None required.

Response — 200 OK

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

---

Context object

The context object is used when creating sessions, sending messages, and updating context. It supports the following fields:

Field	Type	Description
user	object	User profile information. See user object.
tags	array	Array of string tags to apply to the session.
channels	object	Channel-specific context data.
global	object	Global variables that persist across dialog execution.
custom_variable	any	Any additional custom context variables.

User object

Field	Type	Description
user_id	string	Internal user identifier.
display_name	string	User's display name.
avatar	string	URL to user's avatar image.
external_id	string	External system user ID.
contact_id	string	Contact management system ID.
email	string	User's email address.
phone	string	User's phone number.
language	string	User's preferred language (ISO 639-1 code).
timezone	string	User's timezone (IANA format, e.g., America/New_York).
gender	string	User's gender.
address	string	User's address.
location	object	User's location with city, country, region, latitude, longitude.
locales	array	Array of locale strings.
browser	string	User's browser information.
platform	string	User's platform (e.g., web, mobile).
device	string	User's device type.
ip	string	User's IP address.

Global object

Field	Type	Description
disclaimer_accepted	boolean	Whether user accepted disclaimer.
visitor_form_completed	boolean	Whether visitor form was completed.
client_url	string	Client's current URL.
ref	string	Referral parameter.
custom_variable	any	Any additional global variables.

---

Close conversation

Marks the current conversation as resolved. The session remains active and can receive new messages, which start a new conversation.

POST /v1/custom/:integration_id/sessions/:session_id/conversation/close

Path parameters

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

Request body — None required.

Response — 200 OK

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

---

Reopen conversation

Reopens a previously resolved conversation within the same session.

POST /v1/custom/:integration_id/sessions/:session_id/conversation/reopen

Path parameters

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

Request body — None required.

Response — 200 OK

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

---

Handover

Transfers the conversation to a human agent through Moveo's live chat system.

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

Path parameters

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

Request body — None required.

Response — 200 OK

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