hand_off_conversation
Hand off the conversation to a human agent from within an action.
hand_off_conversation(context: dict, reason: str = None, phone_destination: str = None) -> dictHands 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.
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) |
phone_destination | str or None | Optional phone number to forward a live phone call to (E.164 format, e.g. +15551234567). Silently ignored outside the phone channel. |
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