Human Handoff

What it is

Native tool that lets the agent end its own attendance and hand the conversation off to a human. When triggered, two effects happen in sequence:

1. SquadOS fires an HTTP webhook to the URL you configured, with the conversation data.
2. The conversation has its AI disabled (ai_enabled = false) — the agent stops responding until someone reactivates it manually.

When to use

• Support attendance where the agent handles common questions but needs to hand off complex cases to a human.
• Sales with automated qualification followed by handoff to a human SDR.
• Conversations with signs of frustration, urgency, or serious complaint.
• Cases outside the agent’s scope that require human judgment.

Configuration

1. In the agent’s Tools tab, click + Add Tool.
2. Under NATIVE TOOLS, pick Human Handoff.
3. Fill in the webhook URL — must start with https:// (plain HTTP isn’t accepted) and be a full URL.
4. Click Save.

The URL receives a POST with the conversation payload every time the agent decides to hand off. Typically you point at:

• an endpoint in your CRM/helpdesk (Zendesk, Freshdesk, etc.);
• a Zapier / Make / n8n webhook that triggers a notification in Slack, email, or WhatsApp;
• your own backend that creates an internal ticket.

Webhook payload

The POST includes conversation context, agent data, reason informed by the model, and the last 10 messages. Use this payload to create a ticket or notify the right attendant.

How the agent invokes

The agent decides to call this tool when:

• the user explicitly asks to talk to a human;
• the conversation shows the AI isn’t resolving;
• the agent prompt guides handoff in specific situations (for example, “if the user wants to cancel the subscription, always hand off to a human”).

After the handoff, the AI stays completely silent on that conversation — any new user message gets no automatic reply.

Reactivate the AI

For the AI to respond again on the handed-off conversation:

• In the conversations panel under Conversations, open the conversation and turn the AI back on.
• Or via API, set conversations.ai_enabled = true.

Limitations and notes

• URL must be HTTPS. Plain HTTP isn’t accepted (the form validates and blocks save).
• Webhook has no automatic retry. If your URL fails, the event is lost — implement idempotency and logging on your side.
• No visible reply to the user by default. Configure the prompt for the agent to warn the user before handing off (“I’m going to hand you over to a human attendant now”).
• Works on any channel. Internal hub, WhatsApp, Telegram, web widget, public URL, API — all respect ai_enabled = false.