Custom integration API

Overview

The custom integration connects any external system to your AI Agent through standard REST APIs and webhooks. Unlike platform-specific integrations (WhatsApp, Slack, etc.), this integration gives you full control over how messages flow between your system and Moveo.

This integration enables:

• Bidirectional communication via HTTP — send messages through the REST API, receive responses through webhooks.
• Session management — create, update, and close sessions programmatically.
• File handling — upload and download files through presigned URLs.
• Conversation control — hand over to human agents, close and reopen conversations.
• Security — API key authentication, IP allowlisting, and HMAC-SHA256 webhook signature verification.
• Event filtering — subscribe only to the webhook events you need.

---

Prerequisites

Before setting up the custom integration, ensure you have:

✅ Moveo account setup

• An active AI Agent configured.
• An environment selected for the integration.

✅ Technical requirements

• An HTTPS endpoint to receive webhook events.
• A server or application capable of making HTTP requests.
• Ability to verify HMAC-SHA256 signatures (recommended).

---

How it works

The custom integration operates through two communication channels:

1. Your system sends a request to the Moveo custom integration API to create a session.
2. Your system sends user messages through the API to the session.
3. Moveo processes the message through your AI Agent.
4. Moveo delivers the response to your webhook endpoint as an HTTP POST.
5. Your system verifies the signature and processes the response.
6. Session lifecycle continues — you can update context, hand over to agents, close conversations, or close the session through the API.

Your System                         Moveo
    │                                 │
    │── POST /sessions ──────────────>│  Create session
    │<── 201 { session_id } ──────────│
    │                                 │
    │── POST /sessions/:id/messages ─>│  Send user message
    │<── 202 Accepted ────────────────│
    │                                 │
    │                                 │── AI Agent processes
    │                                 │
    │<── POST webhook (brain_send) ───│  Bot response delivered
    │── 200 OK ──────────────────────>│
    │                                 │

---

Next steps

• Setup guide — create and configure a custom integration.
• API reference — endpoints reference for sessions, messages, conversations, and files.
• Outbound webhooks — receive bot responses and events.
• Complete example — end-to-end integration walkthrough.