on_agent_dtmf()

Register a handler that fires whenever the agent presses DTMF digits on the keypad.

This callback covers both ways the agent's digits get pressed:

  • Agentic — the agent decided to press the digits itself, which it can do once you have called call.set_agent_dtmf(enabled=True) (e.g. to work through an IVR menu on a call it placed).
  • Developer-requested — you asked for the digits explicitly with call.send_dtmf(...).

The two are distinguished by requested_by, so a single handler can log every tone the agent sends.

Agent keypresses only: for digits pressed by the person on the other end of the call, use on_caller_dtmf instead.

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

from guava.events import AgentDTMFSentEvent

class AgentDTMFSentEvent(BaseEvent):
    event_type: Literal["agent-dtmf"] = "agent-dtmf"
    digits: list[Literal["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#", "A", "B", "C", "D"]]
    requested_by: Literal["agent", "developer"] = "agent"

Digits are reported, not confirmed: the event fires when the agent sends the tones, which is the same moment the digits are handed to the carrier. It is not an acknowledgement that the far end registered them.

Signature

signature
@agent.on_agent_dtmf
def on_agent_dtmf(call: guava.Call, event: AgentDTMFSentEvent) -> None:
    ...
ParameterTypeDefaultDescription
callCall—The active call object.
eventAgentDTMFSentEvent—Contains `digits` (list of strings): the keys the agent pressed, in order; and `requested_by` (string): `'agent'` if the agent chose to press them, `'developer'` if they came from `send_dtmf()`.

Return value: None

Example

controller.py
import logging

from guava.events import AgentDTMFSentEvent

@agent.on_call_start
def on_call_start(call: guava.Call):
    # Let the agent press digits on its own to work through IVR menus.
    call.set_agent_dtmf(enabled=True)

@agent.on_agent_dtmf
def on_agent_dtmf(call: guava.Call, event: AgentDTMFSentEvent):
    logging.info(
        "Agent pressed %s (requested by %s)",
        "".join(event.digits),
        event.requested_by,
    )
→ Next: on_session_end()

Questions? hi@goguava.ai