hand_off_conversation

hand_off_conversation(context: dict, reason: str = None, phone_destination: str = None) -> dict

Hands off the conversation to a human agent. Once handed off, the bot stops responding and a human takes over.

Call this from inside a custom Python action when you want to hand a conversation to a human based on your own logic — for example, after an API call reveals a complex case. This is the programmatic equivalent of the built-in transferConversation action — use it when the handoff decision depends on logic inside your action rather than the workflow instructions.

For the wider picture — what a handoff triggers, how conversations are routed to teams, and the common custom escalation patterns — see Human Escalation.

Parameters

Returns

dict — {"success": bool, "message": str}

Example

def execute_action(context):
    order = fetch_order(context["args"]["orderId"])

    if order.get("hasFraudFlag"):
        hand_off_conversation(context, "Order flagged for fraud review")
        return {"handedOff": True, "reason": "fraud_flag"}

    return order