Live Operator Chat - API Documentation

Live Operator Chat is the human layer of the conversation platform. It consolidates every customer conversation into a single inbox regardless of where the conversation started. AI chatbot handoffs, inbound SMS threads, email reply chains, and direct live chat sessions all appear in one unified view, sorted by activity and tagged by their source channel. When a customer needs a human, the full message history is already there with no context switching and no lost threads.

When an operator replies, the message is automatically routed back through the correct channel. A reply to an SMS conversation goes out through your SMS sending number. An email thread reply sends through your email domain. Chatbot and live chat conversations deliver directly to the active web session. One inbox, one workflow, every channel handled correctly behind the scenes.

For AI chatbot conversations, human takeover is seamless. The moment an operator sends a message, the AI stops responding and the full conversation history is preserved. The operator can see everything the customer said and everything the AI replied, then continue the conversation naturally.

The inbox shows all active conversations across every channel. Each conversation is tagged with its source (chatbot, SMS, email, or live chat) so operators can see at a glance where each thread originated. Conversations are sorted by most recent activity, and unread message counts keep operators focused on threads that need attention.

Conversation status lifecycle:
Each conversation moves through a set of statuses that help operators organize their queue:
Open - a new conversation that has not been handled yet.
Waiting - the operator has seen it but is waiting for more information.
Active - the operator is actively working on this conversation.
Resolved - the conversation is complete, with a resolution timestamp recorded.

Operator assignment:
The first operator to reply to a conversation is automatically claimed as the owner. That assignment stays with the thread for its full lifecycle so there is clear accountability for every conversation.

The Operators page lists all team members who can respond to conversations. Each operator has a name that is shown to customers when they send messages. The operator's ID is used in API calls to identify who is sending a message.

Teams let you organize operators into groups for structured routing and accountability. Each team has a name used to identify the group in the admin panel.

Canned responses are pre-written message templates that operators can send with one click. Each response has a name, an optional tag for grouping, and the message text. Messages support dynamic macros that are automatically replaced with real values at send time.

Available macros:
{fname} - customer's first name
{lname} - customer's last name
{email} - customer's email address
{phone} - customer's phone number
{operator} - the name of the operator sending the message

The live chat window can be embedded on any website using a single URL. Visitors type messages and see real-time operator responses with typing indicators. The window handles creating new conversations, polling for new messages, and displaying the full message history automatically, with no API key required.

To resume an existing conversation, append the conversation ID to the URL:
https://api.aiappsapi.com/XXX/liveoperator/loadchat/CONVERSATION_ID

Embed the chat window in an iframe or link to it directly. The window uses the postmessage, chatpoll, and chattyping mode URLs automatically to handle all messaging without any additional setup.

App Command (API Call)
POST your request to https://api.aiappsapi.com with your API key and account ID in the POST body. The fields described in each section below go inside the jsonData POST field as a JSON-encoded string. Use this method when your server is making the call and you have your API credentials available.

Mode / Webhook (Direct URL)
POST directly to the endpoint URL shown in each section. The fields go in the POST body as standard form fields (the same fields you would include in an HTML form POST). Use this method for provider webhooks, website forms, or any third-party system that sends form data. No API key is required, the account ID is part of the URL.

Sends a message in a conversation. If an operatorID is provided, the message is sent as that operator. If no operatorID is provided, the message is sent as the visitor/customer. Creates a new conversation automatically when no convoID is provided. Supports canned responses with automatic macro replacement.

Returns unread messages for the caller's side and marks them as read. If operatorID is provided, returns unread visitor messages. If operatorID is omitted, returns unread operator messages. Also returns whether the other party is currently typing.

Sends a typing heartbeat so the other side sees a typing indicator on their next poll. Call this every 3-4 seconds while the user is composing a message. The indicator expires after 5 seconds.

Returns the full message history and user data for a conversation. Used for initial load when opening a chat. Returns up to 200 recent messages.

Updates the status of a conversation. Used by the admin inbox to track conversation state and organize operator queues. Setting status to resolved automatically records a resolution timestamp.

These mode URLs are used internally by the embeddable chat window. They do not require an API key. You generally do not need to call these directly, but they are documented here for reference if you are building a custom chat interface.