Human Takeover

Overview

When a human (concierge, support agent, account manager) needs to handle a WhatsApp conversation directly, you can pause the AI agent for that specific phone number. The agent stops processing inbound messages until the pause expires or is manually resumed. This is a per-conversation pause — other conversations continue to be handled by the agent normally.

How it works

Inbound message → Debounce → Pause check → Agent routing
                                 ↓
                          Paused? → Skip (no agent run)

A pause is created (manually via API, on outbound message, or by agent proposal)
Any inbound message from that phone number is skipped — no agent run is triggered
The pause auto-expires after a configurable duration (default: 30 minutes)
Every manual outbound message resets the timer — the agent stays paused as long as the human is actively responding
The pause can be resumed early via API

Creating a pause

Via API

pause = client.conversation_pauses(account_id).create(
  phone_number: "+33612345678",
  duration_minutes: 60  # optional, defaults to account setting
)

curl -X POST https://whatsrb.com/api/v1/business_accounts/:id/conversation_pauses \
  -H "Authorization: Bearer wrb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+33612345678", "duration_minutes": 60 }'

Via outbound message

When you send a message through the API (dashboard, SDK, or direct API call), WhatsRB automatically creates or extends a pause for that phone number. This means the agent stays silent while a human is actively responding. Only messages with triggered_by: "api" trigger this behavior. Auto-replies from agents (triggered_by: "auto_reply") do not pause the conversation.

Via agent proposal

An agent can propose a human takeover by including a system.conversation.pause action in its output:

{
  "actions": [
    {
      "type": "system.conversation.pause",
      "payload": { "reason": "Customer is upset, needs human support" }
    }
  ]
}

WhatsRB intercepts this action, creates the pause, and removes it from the webhook payload — your backend never sees it. It’s a system action.

system.conversation.pause and system.noop.skip are automatically available to all agents — they don’t need to be in allowed_actions. All system.* actions are internal and never appear in webhooks.

Checking pause status

status = client.conversation_pauses(account_id).check(
  phone_number: "+33612345678"
)

status["paused"]           # => true
status["pause"]["id"]      # => 42
status["pause"]["reason"]  # => "manual"
status["pause"]["remaining_minutes"] # => 22

Resuming a pause

client.conversation_pauses(account_id).resume(pause_id)

curl -X DELETE https://whatsrb.com/api/v1/business_accounts/:id/conversation_pauses/:pause_id \
  -H "Authorization: Bearer wrb_live_xxx"

Configuring the default duration

Each business account has a human_takeover_duration setting (in minutes, default: 30):

client.business_accounts.update(account_id, {
  business_account: { human_takeover_duration: 60 }
})

Listing active pauses

# Active pauses only (default)
pauses = client.conversation_pauses(account_id).list

# Include expired/resumed pauses
pauses = client.conversation_pauses(account_id).list(include_expired: true)

Webhook events

Two new events are fired:

Event	Trigger
`conversation.paused`	A pause is created (any reason)
`conversation.resumed`	A pause is manually resumed

Pauses that expire naturally do not fire conversation.resumed — the agent simply starts processing inbound messages again on the next one.

`conversation.paused` payload

{
  "event": "conversation.paused",
  "data": {
    "id": 42,
    "phone_number": "33612345678",
    "reason": "manual",
    "expires_at": "2026-03-06T17:30:00Z",
    "remaining_minutes": 30
  },
  "timestamp": "2026-03-06T17:00:00Z"
}

Behavior summary

Scenario	Behavior
Pause already active for same phone	Timer is extended (no duplicate pause)
Phone format `+33` vs `33`	Both formats are matched automatically
Pause expires during debounce	Agent resumes on next inbound message
Manual outbound during active pause	Timer is reset to full duration
Agent auto-reply during active pause	Timer is not reset
Resume then human sends again	A new pause is created on outbound

Human takeover is per-conversation (phone number), not per-agent. When a pause is active, all agents are paused for that number.

Getting Started

Core Concepts

Widget

Agent & Workflows

Overview

How it works

Creating a pause

Via API

Via outbound message

Via agent proposal

Checking pause status

Resuming a pause

Configuring the default duration

Listing active pauses

Webhook events

`conversation.paused` payload

Behavior summary

​Overview

​How it works

​Creating a pause

​Via API

​Via outbound message

​Via agent proposal

​Checking pause status

​Resuming a pause

​Configuring the default duration

​Listing active pauses

​Webhook events

​conversation.paused payload

​Behavior summary

Overview

How it works

Creating a pause

Via API

Via outbound message

Via agent proposal

Checking pause status

Resuming a pause

Configuring the default duration

Listing active pauses

Webhook events

`conversation.paused` payload

Behavior summary