Complete integration example

Complete integration example

A typical integration flow from session creation to receiving a bot response.

Step 1: Create a session

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": "chat-session-001",
    "channel_user_id": "user-12345",
    "channel_type": "chat",
    "context": {
      "user": {
        "display_name": "Alice Smith",
        "email": "alice@example.com",
        "language": "en"
      },
      "source_page": "pricing"
    }
  }'

Response:

{
  "request_id": "req-001",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "context": { ... }
}

Step 2: Send a user message

curl -X POST "https://channels.moveo.ai/v1/custom/YOUR_INTEGRATION_ID/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "What pricing plans do you offer?"
    }
  }'

Response:

{
  "request_id": "req-002"
}

Step 3: Receive bot response on your webhook

Moveo delivers the AI Agent's response to your webhook URL:

{
  "event_type": "message:brain_send",
  "request_id": "req-003",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_session_id": "chat-session-001",
  "channel_type": "chat",
  "account_id": "acc-123",
  "account_slug": "acme-co",
  "timestamp": 1789084800000,
  "output": {
    "responses": [
      {
        "type": "text",
        "text": "We offer three pricing plans: Starter, Professional, and Enterprise.",
        "options": [
          { "label": "See Starter", "text": "Tell me about the Starter plan" },
          {
            "label": "See Professional",
            "text": "Tell me about the Professional plan"
          },
          {
            "label": "See Enterprise",
            "text": "Tell me about the Enterprise plan"
          }
        ]
      }
    ]
  }
}

Step 4: Tag the conversation

Tags added during the conversation show up in reporting and can drive routing rules.

curl -X PUT "https://channels.moveo.ai/v1/custom/YOUR_INTEGRATION_ID/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/context/tags" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["pricing-question"]
  }'

Response:

{
  "tags": ["pricing-question"]
}

---

Best practices

• Verify webhook signatures — always validate the X-Moveo-Signature header before processing webhook events. See webhook security.
• Respond quickly to webhooks — process webhook events asynchronously. Return 200 OK within 8 seconds and handle the event in a background job. A delivery that times out is not retried.
• Never authorize on webhook headers — the signature covers the body only. Read account_id and session_id from the verified body, not from the X-Moveo-* headers.
• Store the session ID — after creating a session, store the session_id in your system for all subsequent API calls.
• Use context effectively — pass relevant user and session data in the context object to give the AI Agent more information for generating responses.
• Change tags with the tag endpoints — a PATCH to the context replaces the whole tags array, while add tags and remove tags merge into it.
• Handle session expiration — listen for session:expired events to clean up local session state.
• Stop on 410 — an integration-not-found response means the integration was deleted. Retrying will never succeed.

---

Next steps

• AI Agents — configure the agent that powers your integration.
• Environments — understand how integrations work with environments.
• Live chat — set up human agent handover for your custom integration.
• Context variables — learn how to use context variables in your AI Agent.