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:
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"))