> ## 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_caller_speech()

> Receive every utterance spoken by the caller

<Tabs>
  <Tab title="Python">
    <Warning>
      **Rarely needed.** This callback fires for every utterance spoken by the caller. Most implementations will not need it and should instead rely on higher-level callbacks like [`on_question`](/sdk-reference/on-question) or [`on_task_complete`](/sdk-reference/on-task-complete). It is most useful for implementing call surveillance or real-time transcription logging.
    </Warning>
  </Tab>

  <Tab title="TypeScript">
    <Warning>
      **Rarely needed.** This callback fires for every utterance spoken by the caller. Most implementations will not need it and should instead rely on higher-level callbacks like [`onQuestion`](/sdk-reference/on-question) or [`onTaskComplete`](/sdk-reference/on-task-complete). It is most useful for implementing call surveillance or real-time transcription logging.
    </Warning>
  </Tab>
</Tabs>

Register a handler to receive a callback whenever caller speech is detected. The event contains what the caller said and an `utterance_id` that distinguishes new utterances from updates to existing ones.

As transcription progresses, you may receive multiple events with the same `utterance_id`. Usually these updates append new words, but there can be slight corrections to previously transcribed words. For example:

* `"Hi."` — `utterance_id='0'`
* `"I am going to the store"` — `utterance_id='1'`
* `"I'm going to the store and"` — `utterance_id='1'` (update to the same utterance)

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

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

    class CallerSpeechEvent(BaseEvent):
        event_type: Literal["caller-speech"] = "caller-speech"
        utterance: str
        utterance_id: Optional[str] = None
    ```
  </Tab>

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

    ```typescript theme={null}
    type CallerSpeechEvent = {
      event_type: "caller-speech";
      utterance: string;
      utterance_id?: string;
    };
    ```
  </Tab>
</Tabs>

## Signature

<Tabs>
  <Tab title="Python">
    ```python signature theme={null}
    @agent.on_caller_speech
    def on_caller_speech(call: guava.Call, event: CallerSpeechEvent) -> None:
        ...
    ```

    | Parameter | Type | Description |
    | - | - | - |
    | `call` | `Call` | The active call object. |
    | `event` | `CallerSpeechEvent` | Contains `utterance` (string) and `utterance_id` (optional string) fields. |

    **Return value:** `None`
  </Tab>

  <Tab title="TypeScript">
    ```typescript signature theme={null}
    agent.onCallerSpeech((call: guava.Call, event: CallerSpeechEvent) => void);
    ```

    | Parameter | Type | Description |
    | - | - | - |
    | `call` | `Call` | The active call object. |
    | `event` | `CallerSpeechEvent` | Contains `utterance` (string) and `utterance_id` (optional string) fields. |

    **Return value:** `void`
  </Tab>
</Tabs>

## Example

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

    logger = logging.getLogger(__name__)


    @agent.on_caller_speech
    def on_caller_speech(call: guava.Call, event: CallerSpeechEvent):
        logger.info("caller speech event: %s", event)

    # Output:
    # [INFO  13:30:43] caller speech event: sequence=None event_type='caller-speech'
    #   utterance='Hi Grace.' utterance_id='19d92d6c68b'
    # [INFO  13:30:45] caller speech event: sequence=None event_type='caller-speech'
    #   utterance='Hi Grace. I am looking' utterance_id='19d92d6c68b'
    # [INFO  13:30:46] caller speech event: sequence=None event_type='caller-speech'
    #   utterance='Hi Grace. I am looking to make a reservation' utterance_id='19d92d6c68b'
    # [INFO  13:30:49] caller speech event: sequence=None event_type='caller-speech'
    #   utterance="It's for me" utterance_id='19d92d6deec'
    # [INFO  13:30:50] caller speech event: sequence=None event_type='caller-speech'
    #   utterance="It is for me and a couple friends." utterance_id='19d92d6deec'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript controller.ts theme={null}
    import * as guava from "@guava-ai/guava-sdk";
    import { CallerSpeechEvent } from "@guava-ai/guava-sdk/events";

    agent.onCallerSpeech((_call: guava.Call, event: CallerSpeechEvent) => {
      console.log("caller speech event:", JSON.stringify(event));
    });
    ```
  </Tab>
</Tabs>


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