Skip to content

Application Hooks Reference

Application hooks provide extension points to intercept, customize, or override engine behavior without modifying the core SDK.

To register hooks, point to your hooks module in chakra.toml:

[app]
hooks = "myapp.hooks"

All hook functions are optional and can be implemented either synchronously or asynchronously (async def).


Hooks Summary Matrix

Hook Signature Description
resolve_caller(identities: list[str], room_name: str) -> str \| None Extract a carrier-specific caller number (e.g. SIP / IdeaMart MSISDNs)
caller_context(shared_state: dict) -> list[str] Extra per-call context lines for the model (season, registered district, etc.)
greeting_instruction(shared_state: dict, memory: dict \| None, default: str) -> str Custom greeting instruction (memory is the caller_memory row)
admit_caller(shared_state: dict) -> str \| None Gate access before greeting (return None to admit, or prompt string to reject)
session_metadata(metadata: dict, shared_state: dict) -> dict \| None Web sessions: read custom application fields from room metadata
on_call_start(shared_state: dict) -> None Invoked at session start for custom analytics
on_call_end(shared_state: dict, summary: dict) -> None Invoked at session end with token counts, session type, and estimated cost
extra_schema() -> list[str] Additive SQL statements run on startup for your own application tables
memory_fallback_summary(shared_state: dict, caller_turns: list[str]) -> str \| None The summary stored when the call ends without an explicit save
build_system_prompt(instructions: dict, skills: list, language: str, shared_state: dict) -> str Completely overrides the engine's system prompt layout
knowledge_chunk(text: str, chunk: dict, shared_state: dict) -> str Rewrite a retrieved knowledge-base passage before the model sees it
event_instruction(text: str, kind: str, shared_state: dict) -> str Rewrite lines the agent says for engine events (silence, call limits)
tool_result(result: str, name: str, shared_state: dict) -> str Rewrite what a built-in tool returns to the model
admin_routers() -> list[APIRouter] Attach custom FastAPI HTTP routes to the admin API

Detailed Hook Examples

1. admit_caller(shared_state: dict) -> str | None

async def admit_caller(shared_state: dict) -> str | None:
    user = shared_state.get("user_context", {})
    if user.get("is_blocked"):
        return "Your account is currently suspended. Please contact customer support."
    return None

2. caller_context(shared_state: dict) -> list[str]

from datetime import date

def caller_context(shared_state: dict) -> list[str]:
    season = "Maha" if date.today().month in (9, 10, 11, 12, 1, 2) else "Yala"
    district = shared_state.get("district", "Western Province")
    return [
        f"Caller's registered district: {district}",
        f"The current cultivation season is {season}."
    ]

3. extra_schema() -> list[str]

def extra_schema() -> list[str]:
    return [
        """
        CREATE TABLE IF NOT EXISTS issue_reports (
            id SERIAL PRIMARY KEY,
            session_id UUID,
            phone TEXT,
            details TEXT,
            created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
        );
        """
    ]

4. on_call_end(shared_state: dict, summary: dict) -> None

async def on_call_end(shared_state: dict, summary: dict) -> None:
    # summary carries: session_type, model, input_tokens, cached_tokens, output_tokens, estimated_cost
    logger.info("Call %s ended with estimated cost: $%s", shared_state.get("session_id"), summary.get("estimated_cost"))

5. session_metadata(metadata: dict, shared_state: dict) -> dict | None

def session_metadata(metadata: dict, shared_state: dict) -> dict | None:
    # Extract custom fields sent by web or mobile app
    chakra_data = metadata.get("chakra", {})
    user_context = chakra_data.get("context", {})
    return {"user_tier": user_context.get("tier", "standard")}