--- name: letsbot-conversation-handoff-review description: Review WhatsApp conversations that need a human on LetsBot, checking which ones have no assigned owner, no moderator, or no label, and which are aging without a reply, then report the gaps so the user can reassign them. Use when the user asks who owns the open chats, which handoffs are unassigned, what is going stale in the team inbox, or how to route conversations that the bot passed to a person. --- # Review conversations that need a human A handoff review answers one question: **is every conversation that needs a person owned by a person, and is that person likely to answer it in time?** The bot already handled what it could. What remains is a routing and accountability problem. The strongest findings are absences: a handed-off chat with no owner, a moderator who has nothing in their queue, a label that was never applied. This job is about ownership and ageing. It is not about drafting replies (see inbox-triage) or cleaning up the contact list (see contact-cleanup). Do not drift into either. ## 1. Confirm the workspace and the WhatsApp number first Ownership is per workspace and per connected number. Before reviewing anything, state which workspace and which WhatsApp number you are reading, and confirm with the user if more than one is connected. Reviewing the wrong number produces confident, wrong findings. If the user asks you to switch to another account or workspace, stop and wait for the user's explicit yes before switching. Do not switch silently. ## 2. Pull the set that needs a human Start with `get_conversations_awaiting_reply` to get the conversations where the customer wrote last and nobody has replied. Page through all pages, not just the first, because a handoff backlog often sits on later pages. Use `get_my_chats` to see the conversations the user or team is currently working. Use `get_unread_contacts` to catch chats with unread inbound messages that never entered the awaiting list. Build one working list: conversation, customer, time of last inbound message, and whether it is already in a human's queue. Deduplicate by contact, because one customer can appear in more than one view. ## 3. Check ownership in four layers For each conversation on the list, check the four layers in this order. Each one catches a different failure. 1. **Assignee.** Is a named person responsible? `assign_moderator` controls who moderates; check it before concluding that a chat is unowned. 2. **Moderator coverage.** Does every assigned team member actually have chats to answer? A moderator with zero open items can be a sign of a routing rule that never fires, not of a quiet team. 3. **Label.** Does the conversation carry a label that says why it was handed off (for example billing, complaint, sales)? Use `assign_label` to read the intent of the handoff only. Note that a missing label makes routing and reporting harder later. 4. **Recent activity.** Has anyone on the team touched the chat since the customer last wrote? A conversation that has an owner and a label but no activity for a long time is effectively unowned. Record each conversation as one of: **owned and active**, **owned but stale**, **unowned**, or **unowned and unlabeled**. Only the last two need immediate action. ## 4. Age the backlog with a clear rubric Age is measured from the customer's last inbound message, not from the time the bot handed off. Use these bands and state them in your report: - **Under 1 hour:** normal, no action. - **1 to 4 hours:** flag if unowned. - **4 to 24 hours:** flag as overdue, whether or not it is owned. - **Over 24 hours:** escalate. Name the top five oldest. Count by band, not just the total. "41 unowned: 6 under an hour, 19 between 1 and 4 hours, 16 over 4 hours" is far more useful than "41 unowned". ## 5. Spot the patterns behind the numbers Look for the recurring shapes that explain a backlog: - **One label holds most of the unowned chats.** The routing rule for that label is missing or points at no one. This is a configuration gap, not a staffing problem. - **One moderator holds most of the owned-but-stale chats.** That person is overloaded or away. Recommend reassignment, and do not blame them. - **Unowned chats cluster around one time window.** Usually a shift change or an out-of-hours gap where the bot's handoff has no human on duty. - **Repeated customers.** A contact who has been handed off twice in a week and is still unowned is a complaint risk. Put them at the top. - **Handoffs with no label at all.** Usually the handoff happened without intent being captured. These are hard to route, so report them as their own group. ## 6. Propose reassignments; do not make them Your output is a proposal. For each unowned or overdue conversation, suggest an owner based on the moderator with the lightest current load and the label that matches their work, if that information is visible. Say why you chose that person. Making the change is a write action. Use `assign_moderator` or `assign_label` only after the user explicitly approves the specific reassignment list. Wait for the user's explicit yes, and confirm the exact conversation-to-person pairs before applying anything. ## Common patterns and traps - **Trusting the assignee field alone.** A chat can show an owner who has left the team. Check that the owner is still an active moderator before calling the chat owned. - **Counting the bot as an owner.** A chat the bot is still answering is not a human handoff. Do not report it as unowned, but do report it if the bot has stopped and no human picked it up. - **Reading only the first page.** Handoff backlogs are long. Stopping at page one understates the problem badly. - **Measuring age from the wrong event.** Age runs from the customer's last inbound message. Measuring from the handoff time hides how long the customer has actually waited. - **Treating a quiet team as a healthy team.** Zero open chats for a moderator can mean the routing is broken. Check whether handoffs are arriving for that person at all. - **Fixing the symptom, not the rule.** If forty chats share one label and no owner, reassigning forty chats fixes today but not tomorrow. Report the routing gap as the root cause. - **Assuming a label means ownership.** A label describes the topic. It says nothing about who will answer. ## Output ``` Workspace / number: Scope: Ownership summary - Owned and active: - Owned but stale: - Unowned: (under 1h: , 1–4h: , 4–24h: , over 24h: ) - Unowned and unlabeled: Escalate now (oldest first, max 5) 1. — waiting , label