Framework Integration

The SDK is framework-agnostic. Here's how to use it with popular Python frameworks.

FastAPI

The cleanest integration — use JambonzResponse as a type hint:

from fastapi import FastAPI, Request
from jambonz import JambonzResponse, Say, Gather, Hangup, Input

app = FastAPI()

@app.post("/incoming-call")
def handle_call() -> JambonzResponse:
    return [
        Say(text="Hello! Say something."),
        Gather(input=[Input.SPEECH], action_hook="/speech"),
    ]

@app.post("/speech")
async def handle_speech(request: Request) -> JambonzResponse:
    body = await request.json()
    transcript = body.get("speech", {}).get("alternatives", [{}])[0].get("transcript", "")
    return [
        Say(text=f"You said: {transcript}. Goodbye!"),
        Hangup(),
    ]

Tip

With FastAPI, you don't need to construct JambonzResponse(...) explicitly. Just return a list of verbs with -> JambonzResponse type hint and FastAPI handles serialization.

You can also use response_model:

@app.post("/call", response_model=JambonzResponse)
def handle_call():
    return [Say(text="Hello"), Hangup()]

Flask

from flask import Flask, request
from jambonz import JambonzResponse, Say, Gather, Hangup, Input

app = Flask(__name__)

@app.post("/incoming-call")
def handle_call():
    response = JambonzResponse([
        Say(text="Hello! Say something."),
        Gather(input=[Input.SPEECH], action_hook="/speech"),
    ])
    return app.response_class(
        response.model_dump_json(),
        content_type="application/json",
    )

@app.post("/speech")
def handle_speech():
    body = request.get_json()
    transcript = body.get("speech", {}).get("alternatives", [{}])[0].get("transcript", "")
    response = JambonzResponse([
        Say(text=f"You said: {transcript}. Goodbye!"),
        Hangup(),
    ])
    return app.response_class(
        response.model_dump_json(),
        content_type="application/json",
    )

Django

from django.http import HttpResponse
from jambonz import JambonzResponse, Say, Gather, Hangup, Input
import json

def handle_call(request):
    response = JambonzResponse([
        Say(text="Hello! Say something."),
        Gather(input=[Input.SPEECH], action_hook="/speech"),
    ])
    return HttpResponse(
        response.model_dump_json(),
        content_type="application/json",
    )

def handle_speech(request):
    body = json.loads(request.body)
    transcript = body.get("speech", {}).get("alternatives", [{}])[0].get("transcript", "")
    response = JambonzResponse([
        Say(text=f"You said: {transcript}. Goodbye!"),
        Hangup(),
    ])
    return HttpResponse(
        response.model_dump_json(),
        content_type="application/json",
    )

Comparison

	FastAPI	Flask	Django
Return type	-> JambonzResponse (automatic)	response.model_dump_json()	response.model_dump_json()
Construct object	Not needed	JambonzResponse([...])	JambonzResponse([...])
Serialization	Automatic	Manual	Manual
Async	Native	Via quart	Via django.http.async