Human handoff
Handoff is how a conversation moves from the agent to a person on your team and back. The agent can ask for a person when a customer needs one; anyone on your team can also step into any conversation at any time. While a person is answering, the agent stays silent.
How it works
How a customer asks for a person
There is no button for the customer to press. The customer just says it in their own words, on any channel: "Can I talk to a human?", "I want to speak to someone", "Bir yetkiliyle görüşmek istiyorum". The agent recognises it and asks your team to join.
The agent does this with a built-in tool called request_human. It is added to every agent that has handoff turned on, and the agent is told:
- to use it only in the situations you describe in When to ask for a person,
- never to use it just because it lacks information or a tool to answer (it should say plainly what it can't do and help with what it can),
- after asking, to tell the customer briefly that someone will join, and to keep helping until they do.
Setting it up
Handoff is part of the agent's settings. Open the agent, go to Instructions, and find the Handoff section.
| Setting | What it does | Default |
|---|---|---|
| Let the agent bring in a person | Turns the request_human tool on or off. Off, the agent never flags a conversation; your team can still take over any conversation from the Inbox. | On |
| When to ask for a person | Plain-language rule for when the agent should ask. Up to 1,000 characters. | "The customer asks to talk to a person." |
Like every agent setting, these changes take effect for customers when you publish.
Writing a good rule
Keep the rule short and concrete. Name the situations, not the feelings.
The customer asks to talk to a person, wants to cancel a paid order,
reports a medical emergency, or asks about a refund over $200.
For a dental clinic:
The patient asks for a person, describes severe pain or swelling,
or wants to change a treatment plan.
Handoff is for conversations with customers. It is never offered when the agent runs an automation task, or when it answers a question from another agent in a team.
How the conversation is flagged
When the agent asks for a person:
- The conversation's handoff state becomes "requested", with the agent's reason (up to 200 characters). If it was resolved, it opens again.
- An event appears in the thread: Handoff requested: reason · the AI keeps helping until someone takes over.
- The conversation shows under Needs you in the Inbox, with a dot and the reason on its row. The Needs you count and the sidebar badge go up.
- For a real customer conversation, the Peki event Conversation handed off fires. See Notifications.
The agent asks only once per conversation. If it tries again while the request is open, or while someone has already taken over, nothing changes.
Test panel conversations are flagged in the same way, so you can try the whole flow before you publish. They never fire the Peki event.
Taking over
Anyone with the Operator role or higher can take over a conversation, whether the agent asked for a person or not.
- Open the conversation in the Inbox.
- Press Take over.
- Write your reply in Write to the customer…. Press Return to send, Shift + Return for a new line. Replies can be up to 4,000 characters.
- To send files, use the paperclip or drop files onto the conversation. Up to 5 files per reply. See Files and attachments.
What happens when you take over:
- The conversation moves to Taken over, with "taken over by your name" on its row, and the thread shows your name took over.
- A reply the agent was still writing is dropped. It never reaches the customer.
- From now on the agent doesn't answer. New customer messages are saved and shown in the thread, and wait for you.
- Only one person can have a conversation at a time. If a colleague took it a moment before you, you see "name has already taken over". Teammates see "name is replying in this conversation." instead of a composer.
Live reply: how your message reaches the customer
Your reply goes out on the conversation's own channel:
| Channel | What the customer sees |
|---|---|
| Website chat | Your message in the chat window, with your first name and Team under it. It appears the next time the widget checks for messages, within a few seconds. |
| Telegram | Your message from the bot, right away. Markdown formatting is converted for Telegram; long messages are split. Files go as photos or documents. |
| API | A message with the role team and your name, in the session's messages. See API overview. |
| Test panel | Your message in the test conversation. |
Your reply is never rewritten by the agent or checked by Guardrails. What you write is what the customer gets.
You don't need to wait for a handoff request. If you see in the Inbox that a conversation is going the wrong way, take it over. The agent stops mid-reply.
Giving it back
When you are done, choose one:
| Action | When to use it | What happens |
|---|---|---|
| Hand back to AI | The customer may have more questions the agent can handle. | The handoff is cleared. The thread shows your name handed back to the AI. The agent answers the customer's next message. It doesn't reply to messages that arrived while you had the conversation. |
| Resolve | The customer's issue is settled. | The conversation is closed. On the website chat and Telegram, the customer's next message starts a new conversation, answered by the agent. On Telegram the customer is asked for 👍/👎 if the agent wrote the last message. |
Both buttons are in the conversation header. Resolve is there whether or not someone has taken over.
What you settled with the customer still counts: after a team reply, the agent's record filling runs on the conversation, so details you agreed on can complete the customer's records. See Records.
Business hours
Handoff doesn't switch itself off outside your opening hours: the agent can ask for a person at any time, and the conversation waits under Needs you until someone takes over. What changes with business hours is what the agent knows and says.
- With Current date and time on (in Instructions, under Context), the agent knows the date, the time and whether your business is open or closed right now, in your workspace timezone.
- You can add an instruction block that applies only Outside business hours, telling the agent what to promise. For example: "Outside business hours, if you ask for a person, tell the customer the team will reply after 09:00 on the next working day."
- Set your opening hours in Settings → Business hours. Until they are set, the agent isn't told whether you are open, and blocks with an hours condition are never sent.
See Business hours and Instructions. In the Test panel, set Hours to Open or Closed to try both cases at any time of day.
Notifications
Peki has no email or push notification for handoffs. You know a conversation needs you through:
- The sidebar badge next to Inbox, which counts conversations under Needs you plus pending approvals. It updates every few seconds wherever you are in Peki.
- The Needs you tab, with its own count.
- An automation of your own. The Conversation handed off Peki event can start an automation, for example one that sends a message to your team's Telegram chat with the customer's name and the reason. See Triggers and Automations.
Troubleshooting
| Problem | What to do |
|---|---|
| The agent hands off too often | Make When to ask for a person narrower. Remove catch-alls like "or you cannot help". Check with Why? in the Inbox which tool the agent called. |
| The agent never hands off | Check that Let the agent bring in a person is on and that you published. Try the exact customer wording in the Test panel. |
| The customer keeps getting AI replies after I took over | Check the conversation shows under Taken over with your name. Replies already sent before you took over stay in the thread. |
| I can't write in the conversation | You need the Operator role or higher, and you must take it over first. If a colleague has it, ask them to hand it back. |
| After Hand back to AI, the agent ignored what the customer wrote meanwhile | The agent answers only new messages after the hand back. Reply yourself before handing back, or let the customer write again. |