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.

Python
TypeScript

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.

The EscalateEvent has the following shape:

type EscalateEvent = {
  event_type: "escalate";
  requested_by: "human" | "agent"; // default: "human"
};

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

Signature

Python
TypeScript

signature

@agent.on_escalate
def on_escalate(call: guava.Call, event: EscalateEvent) -> None:
    ...

Parameter	Type	Description
`call`	`Call`	The active call object.
`event`	`EscalateEvent`	Contains `requested_by` (string): `'human'` if the caller requested escalation, `'agent'` if the bot initiated it.

Return value: None

signature

agent.onEscalate((call: guava.Call, event: EscalateEvent) => Promise<void>);

Parameter	Type	Description
`call`	`Call`	The active call object.
`event`	`EscalateEvent`	Contains `requested_by` (string): `'human'` if the caller requested escalation, `'agent'` if the bot initiated it.

Return value: Promise<void>

Example

Python
TypeScript

controller.py

from guava.events import EscalateEvent

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

controller.ts

import * as guava from "@guava-ai/guava-sdk";
import { EscalateEvent } from "@guava-ai/guava-sdk/events";

agent.onEscalate(async (call: guava.Call, event: EscalateEvent) => {
  await call.transfer("+15556667777");
});

Getting started

Agent SDK

CLI reference

WebRTC

SIP calling

Phone numbers

Deployments

Compliance

Release notes

Signature

Example

​Signature

​Example

Signature

Example