Human Intervention

Human intervention is direct handling of an external conversation while AI is disabled. Use it when the customer asks for a person, the agent cannot resolve the case, or the decision requires human judgment.

This flow is available in Conversations (/admin/conversations) for service that came through an inbox, such as WhatsApp, Telegram, Instagram, a public page, the widget, or API. Internal Hub conversations cannot be replied to through the customer-service panel.

Your role needs conversation-management permission to claim, transfer, or complete a conversation. It also needs reply permission and access to the conversation’s inbox to send a response.

Find the correct conversation

The views separate ownership from pending work:

• Unassigned contains human conversations that nobody has claimed.
• To reply contains only conversations assigned to you where the customer sent the most recent message.
• Mine contains every conversation assigned to you, whether it is waiting for your reply or the customer’s.

If an agent transfers to the general queue, look under Unassigned. If it transfers to a specific person, the conversation appears in that person’s Mine view and also in To reply while the customer is waiting.

Claim a conversation

1. Open Conversations and select an active external conversation.
2. If it is unassigned, choose Claim in the header or the Conversation actions menu.
3. In Claim conversation?, confirm with Claim conversation.

The operation assigns the conversation to you and disables AI in the same transaction. The Reply tab becomes available when AI is disabled, the conversation is not snoozed, and its channel allows free-form text.

You can also write directly in an unassigned conversation: on send, SquadOS tries to assign it to you before delivering the message. Explicitly claiming it is still useful for showing the team that you started working before you type.

If someone else claims it first, your message is not sent. The dialog identifies the current assignee and offers Claim and send. Use it only if you intend to take the work from that person; Cancel restores the text to the composer.

Reply to the customer

In the Reply tab, the strip above the field confirms the channel, customer, and, when it adds context, the destination inbox. A human reply is persisted as an attendant message and delivered through the original channel. It consumes no AI credits.

You can type, use audio dictation, or insert a Quick reply. On official WhatsApp, once the 24-hour window closes, free-form text is blocked: choose Send template and use an approved template. If SquadOS says the message was saved but could not be delivered to the external channel, do not assume that the customer received it; check the channel before trying again.

Do not use attachments in human intervention yet

The attachment button may appear, but the current runtime does not forward the file to the intervention request. Send text or dictation and use the channel’s app for an essential file until this inconsistency is fixed.

An internal note is not a reply

The Internal note tab stores a separate note that only the team can see. It is not sent to the customer or included in the history used by AI. Use it to record context before a transfer. See Internal Notes.

When the agent calls a person

The Transfer Conversation tool lets you configure transfer reasons and resolve each destination by time: general queue, a specific person, or another agent. Legacy human-handoff and agent-transfer tools remain compatible with this unified tool.

When the destination is human, AI is disabled. Confirm the assignee shown in the conversation: if assigning the configured person fails, the current behavior may complete the handoff while leaving the conversation unassigned.

A handoff URL can be configured for external integrations. SquadOS then sends the context to that endpoint before disabling AI. After a timeout or connection failure, do not retry automatically: the destination may have received the first request even though SquadOS could not confirm it.

Automatic pause for looping conversations

Anti-bot protection can also disable AI when it detects repetition or abnormal volume. The message that triggered the cut remains in the history.

After the first cut, AI may resume automatically only when a new message arrives after the configured silence period. No timer turns it back on by itself. From the second cut onward, only a person can reactivate it. If someone claims, transfers, completes, or manually changes AI handling, automatic resume for that cut is canceled.

Transfer the service

Open Conversation actions → Transfer. The dialog offers:

• AI Agent: select an active agent allowed for the inbox. Turn on Send a message immediately for it to reply now and, if needed, write an internal instruction. When off, the agent waits for the customer’s next message.
• Person: choose another attendant and optionally add an internal note.
• Queue: removes the assignee and returns the conversation to Unassigned; it also accepts an internal note.

Transferring to an agent enables AI, clears the human assignee, and switches to the selected agent. An immediate reply runs the model and tools and may consume credits. If the interface reports a failure, first inspect the agent, assignee, timeline, and latest message: some later failures can occur after state or a reply was already stored. Do not repeat an immediate transfer before reconciling those effects.

Complete and reopen

Choose Complete conversation and select what the next reopening should do:

• AI: AI resumes when reopened if an active agent is available.
• Human handling: the conversation returns to human service when reopened.

While completed, the conversation stays in Completed and AI remains disabled in both modes. If you choose AI with no available agent, SquadOS preserves human handling and reports the adjustment.

Reopen restores the selected mode. A new customer message can also reopen the conversation; a human reply to a completed conversation assigns it to the attendant who sent it when that person has valid inbox access.

Checklist before leaving

• Confirm that the customer actually received the reply on the external channel.
• Leave an internal note when another person or agent needs context.
• Verify the assignee after every human handoff.
• Reconcile state before repeating a send or transfer that reported failure.
• Complete the service and deliberately choose who should handle the next reopening. See Conversation States.