AI Control & Human Handoff

Overview

Every chat in Happ has an AI control toggle. When AI is on, the assistant automatically responds. When AI is off, the chat waits for a human operator. This gives you full control over when AI handles conversations and when humans step in.

Toggling AI Mode

From the Dashboard

1. Open any chat in Chats
2. Click the AI toggle button
3. AI switches on or off immediately

Via API

PATCH /api/chats/{chatId}
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "isUnderAiControl": false
}

See the full API reference at api.happ.tools/reference.

From Mobile App

Open any chat and use the AI control toggle.

How AI Control Works

When AI is disabled, the aiDisableReason field indicates why:

Human Handoff (Transfer to Operator)

The AI can automatically transfer a conversation to a human when it determines it can't help.

How It Works

1. The built-in turnOffAiMode tool is always available to your assistant
2. When the AI decides human help is needed, it calls this tool
3. isUnderAiControl is set to false
4. The chat appears in the dashboard as needing human attention
5. A CHAT_MODE_CHANGED WebSocket event notifies all connected clients in real-time

Getting Notified

To get instant notifications when AI hands off a conversation:

1. Set up Telegram Push Notifications
2. When the AI disables itself, your team's Telegram group receives a notification
3. A team member can respond from the dashboard or mobile app

Guiding the AI to Hand Off

Include instructions in your assistant's prompt:

If the customer asks to speak to a human, or if you cannot resolve
their issue after 2 attempts, use the turnOffAiMode tool to transfer
the conversation to a human operator. Tell the customer that a team
member will respond shortly.

Auto-Resume AI

After AI hands off a conversation (via turnOffAiMode), the system automatically re-enables AI after approximately 10 minutes of inactivity.

How It Works

1. A cron job runs every minute
2. It finds messages older than 10 minutes that haven't been archived
3. These messages are moved to a context archive (assigned a contextId)
4. If the chat was auto-disabled (reason = auto), AI mode is re-enabled
5. The conversation gets a fresh context — the AI starts a new interaction without the old messages

Why This Exists

This prevents conversations from being "stuck" in manual mode. If a human doesn't respond, the AI picks back up with a clean slate.

Manually Disabled Chats

If AI was disabled manually (reason = manual), auto-resume does NOT apply. The human must explicitly re-enable AI.

Conversation Context Window

The AI doesn't see the entire chat history forever. Messages older than 10 minutes are archived and excluded from the AI's context.

What This Means

• The AI "remembers" only the recent conversation (last ~10 minutes of messages)
• Older messages are preserved in the database but not sent to the AI model
• This keeps the AI focused and prevents token overflow for long conversations

Practical Impact

• Short conversations (under 10 min): The AI sees everything
• Long conversations: The AI may not remember details from earlier in the chat
• Returning customers: If a customer comes back after a pause, the AI treats it as a fresh conversation

Transferring Between Assistants

You can transfer a chat to a different assistant:

PATCH /api/chats/{chatId}
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "assistantId": "new-assistant-uuid"
}

The new assistant continues the conversation from the latest message. All message history is preserved.

Message Debouncing

When a customer sends multiple messages quickly (e.g., in a Telegram chat), Happ batches them:

• 4-second debounce: Waits 4 seconds after each message for more
• 7-second maximum: After 7 seconds, processes what's been received
• Only the last message in a burst triggers the AI response

This prevents redundant AI calls and ensures the assistant sees the customer's full thought before responding.

WebSocket Events

Real-time events are broadcast when AI mode changes:

{
  "type": "CHAT_MODE_CHANGED",
  "payload": {
    "chatId": "uuid",
    "isUnderAiControl": false,
    "aiDisableReason": "auto"
  }
}

Connect to wss://api.happ.tools/ws for real-time updates.