hand_off_conversation

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

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

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.

Parameters

Name	Type	Description
`context`	`dict`	The context object passed to your action
`reason`	`str or None`	Optional reason for the handoff (max 500 characters)

Returns

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

Behavior

Once handed off, the bot will not respond to further messages in this conversation.
If the conversation is already handed off, the operation succeeds without changes.
Skipped in test/mock environments.

Examples

Hand off when an API call reveals a complex case

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

Hand off with context about what was attempted

def execute_action(context):
    try:
        result = process_cancellation(context["args"]["orderId"])
        return result
    except Exception as e:
        hand_off_conversation(
            context,
            f"Automatic cancellation failed: {str(e)}"
        )
        return {"handedOff": True, "error": str(e)}