on_session_end()

Register a handler that fires when a call session ends. Use this to save call data, trigger post-call workflows, or log outcomes.

The BotSessionEnded event carries a termination_reason field that tells you why the session ended:

ValueMeaning
"user-hangup"The caller hung up.
"bot-hangup"The agent ended the call (e.g. via call.hangup()).
"bot-failure"The session ended due to an internal error.
"bot-transfer"The call was transferred to another destination.
"voicemail"The outbound call reached voicemail.

The event payload contains a dnc boolean field (defaulting to false). If the voice agent detects a verbal opt-out during the call, this field is set to true and the caller's phone number is automatically added to your organization's Do Not Call list.

DNC detection is exclusive to outbound campaigns (inbound calls are not supported). Opted-out numbers are added directly to your organization-wide DNC list rather than a campaign-specific list.

Signature

signature
@agent.on_session_end
def on_session_end(call: guava.Call, event: BotSessionEnded) -> None:
    ...
ParameterTypeDefaultDescription
callCall—The call object. Note: the call is already ended — do not issue commands on it.
eventBotSessionEnded—Contains `termination_reason` — one of `"user-hangup"`, `"bot-hangup"`, `"bot-failure"`, `"bot-transfer"`, `"voicemail"`. Also contains `dnc` (`bool` / `boolean`) — `false` by default, `true` when the caller verbally opted out (outbound campaigns only).

Return value: None

Example

controller.py
import logging
from guava.events import BotSessionEnded

logger = logging.getLogger(__name__)


@agent.on_session_end
def on_session_end(call: guava.Call, event: BotSessionEnded):
    logger.info("session ended: reason=%s", event.termination_reason)

    if event.dnc:
        # caller verbally opted out — number added to org DNC list
        logger.info("Contact opted out, added to DNC list.")

    if event.termination_reason == "user-hangup":
        # caller hung up — save any collected data
        ...
    elif event.termination_reason == "bot-transfer":
        # call was transferred to a human agent
        ...
→ Next: on_agent_speech()

Questions? hi@goguava.ai