Bot Control API¶

Control bot (AI agent) status on conversations — pause/resume automation from your mobile app or external system.

Authentication¶

All endpoints support two auth methods:

Method	Header	Example
API Key	`X-API-Key`	`X-API-Key: cg_your_api_key`
Bearer Token	`Authorization`	`Authorization: Bearer <supabase_jwt>`

1. Check Bot Status (via REST API Proxy)¶

The ai_agent_active field is included in every conversation response.

Get single conversation¶

GET /functions/v1/rest-api-proxy/conversations?id=<conversation_id>&select=id,ai_agent_active,status,contact_id,channel_account_id

Response:

[
 {
 "id": "conv-uuid",
 "ai_agent_active": true,
 "status": "open",
 "contact_id": "contact-uuid",
 "channel_account_id": "channel-uuid"
 }
]

Field	Type	Description
`ai_agent_active`	`boolean`	`true` = bot is handling, `false` = human is handling

List all bot-active conversations for a channel¶

GET /functions/v1/rest-api-proxy/conversations?channel_account_id=<channel_id>&ai_agent_active=true&select=id,ai_agent_active,contact_id,status,last_message_at&order=last_message_at.desc&limit=100

Filter by status¶

GET /functions/v1/rest-api-proxy/conversations?status=open&ai_agent_active=true&select=id,ai_agent_active,contact_id

2. Pause Bot (Human Takeover)¶

Pauses the bot on a specific conversation. Also deactivates any active bot flow sessions and triggers the Human Takeover Webhook if configured on the channel.

POST /functions/v1/bot-control

Headers:

Content-Type: application/json
X-API-Key: cg_your_api_key

Body:

{
 "conversation_id": "conv-uuid",
 "action": "pause"
}

Response:

{
 "success": true,
 "conversation_id": "conv-uuid",
 "bot_active": false,
 "action": "pause"
}

What happens on pause:¶

ai_agent_active is set to false
All active bot_sessions for this conversation are deactivated
The Human Takeover Webhook is triggered (if configured on the channel)

3. Resume Bot¶

Re-enables the bot on a conversation.

POST /functions/v1/bot-control

Body:

{
 "conversation_id": "conv-uuid",
 "action": "resume"
}

Response:

{
 "success": true,
 "conversation_id": "conv-uuid",
 "bot_active": true,
 "action": "resume"
}

4. Human Takeover Webhook Configuration¶

Configure per channel in Settings → Channels → Edit → Settings tab.

Field	Description
URL	The endpoint to call when bot is paused
Method	`POST`, `PUT`, or `PATCH`
Custom Headers	JSON object, e.g. `{"Authorization": "Bearer xxx"}`
Custom Body	JSON object merged with default payload

Default Webhook Payload¶

{
 "event": "human_takeover",
 "conversation_id": "conv-uuid",
 "channel_account_id": "channel-uuid",
 "channel_name": "My WhatsApp Channel",
 "agent": {
 "id": "agent-uuid",
 "name": "Jane Smith",
 "email": "jane@company.com"
 },
 "contact": {
 "id": "contact-uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"]
 },
 "timestamp": "2026-03-14T00:00:00.000Z"
}

Custom body fields are merged with the default payload (custom fields override defaults if keys overlap).

Error Responses¶

Status	Error	Description
400	`Required: conversation_id, action`	Missing required fields
400	`action must be "pause" or "resume"`	Invalid action value
401	`Missing authentication`	No API key or Bearer token
404	`Conversation not found`	Invalid ID or wrong organization

cURL Examples¶

Check bot status¶

curl -X GET \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/conversations?id=CONV_ID&select=id,ai_agent_active,status" \
 -H "X-API-Key: cg_your_api_key"

Pause bot¶

curl -X POST \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/bot-control" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key" \
 -d '{"conversation_id": "CONV_ID", "action": "pause"}'

Resume bot¶

curl -X POST \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/bot-control" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key" \
 -d '{"conversation_id": "CONV_ID", "action": "resume"}'