> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goguava.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# on_escalate()

> Handle requests to escalate to a human

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.

<Tabs>
  <Tab title="Python">
    The `EscalateEvent` is a pydantic model imported from `guava.events`:

    ```python theme={null}
    from guava.events import EscalateEvent

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

    <Warning>
      **Interaction with `on_action_request`:** If you implement the [`on_action_request`](/sdk-reference/on-action-request-execute) 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.
    </Warning>
  </Tab>

  <Tab title="TypeScript">
    The `EscalateEvent` has the following shape:

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

    <Warning>
      **Interaction with `onActionRequest`:** If you implement the [`onActionRequest`](/sdk-reference/on-action-request-execute) 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.
    </Warning>
  </Tab>
</Tabs>

## Signature

<Tabs>
  <Tab title="Python">
    ```python signature theme={null}
    @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`
  </Tab>

  <Tab title="TypeScript">
    ```typescript signature theme={null}
    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>`
  </Tab>
</Tabs>

## Example

<Tabs>
  <Tab title="Python">
    ```python controller.py theme={null}
    from guava.events import EscalateEvent

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

  <Tab title="TypeScript">
    ```typescript controller.ts theme={null}
    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");
    });
    ```
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.