on_escalate()

Register a handler that fires when the call needs to be escalated to a human agent.

This callback can be triggered in two ways:

  • By the caller — the person on the call explicitly asks to speak to a human (e.g. "Can you connect me to a human agent, please?").
  • By the bot — the agent determines it is unable to service the call properly.

The EscalateEvent is a pydantic model imported from guava.events:

from guava.events import EscalateEvent

class EscalateEvent(BaseEvent):
    event_type: Literal["escalate"] = "escalate"
    requested_by: Literal["human", "agent"] = "human"

Interaction with on_action_request: If you implement the on_action_request callback, on_escalate will not detect escalation requests made by the human caller — you become responsible for handling those via on_action_request. on_escalate will still fire for escalations initiated by the bot.

Signature

signature
@agent.on_escalate
def on_escalate(call: guava.Call, event: EscalateEvent) -> None:
    ...
ParameterTypeDefaultDescription
callCall—The active call object.
eventEscalateEvent—Contains `requested_by` (string): `'human'` if the caller requested escalation, `'agent'` if the bot initiated it.

Return value: None

Example

controller.py
from guava.events import EscalateEvent

@agent.on_escalate
def on_escalate(call: guava.Call, event: EscalateEvent):
    call.transfer(destination="+15556667777")
→ Next: set_task()

Questions? hi@goguava.ai