WhatsApp: Single-WABA Inbound + Human Handoff

pip install maximem-synap maximem-synap-openai-agents openai-agents heyoo fastapi uvicorn

uv add maximem-synap maximem-synap-openai-agents openai-agents heyoo fastapi uvicorn
# pip-compatible (existing venv): uv pip install maximem-synap maximem-synap-openai-agents openai-agents heyoo fastapi uvicorn

npm install @maximem/synap-js-sdk @maximem/synap-vercel-adk ai @ai-sdk/openai

# .env
SYNAP_API_KEY=...
OPENAI_API_KEY=...
WABA_PHONE_NUMBER_ID=...
WABA_ACCESS_TOKEN=...
WABA_WEBHOOK_VERIFY_TOKEN=...

# .env.local
SYNAP_API_KEY=...
OPENAI_API_KEY=...
WABA_PHONE_NUMBER_ID=...
WABA_ACCESS_TOKEN=...
WABA_WEBHOOK_VERIFY_TOKEN=...

# Set when AI hands off; cleared when human releases. Use Redis in production.
AI_HANDOFF: set[str] = set()

def is_handoff(phone: str) -> bool:
    return phone in AI_HANDOFF

def start_handoff(phone: str) -> None:
    AI_HANDOFF.add(phone)

def end_handoff(phone: str) -> None:
    AI_HANDOFF.discard(phone)

const AI_HANDOFF = new Set<string>();
const isHandoff = (phone: string) => AI_HANDOFF.has(phone);
const startHandoff = (phone: string) => AI_HANDOFF.add(phone);
const endHandoff = (phone: string) => AI_HANDOFF.delete(phone);

@function_tool
async def hand_off_to_human(phone: str, reason: str, summary: str) -> dict:
    """Bring a human into the thread. Reason: 'customer_asked' | 'frustration' | 'out_of_scope' | 'sensitive'."""
    start_handoff(phone)
    await sdk.memories.create(
        document=f"AI handed off to human. Reason: {reason}. Summary: {summary}",
        document_type="support-handoff",
        user_id=phone,
        customer_id=CUSTOMER_ID,
        metadata={"handoff_reason": reason},
    )
    await notify_human_console(phone, reason, summary)  # your Slack/console push
    return {"status": "handed_off"}

const handOffToHuman = tool({
  description: "Bring a human into the thread.",
  parameters: z.object({
    phone: z.string(),
    reason: z.enum(["customer_asked", "frustration", "out_of_scope", "sensitive"]),
    summary: z.string(),
  }),
  execute: async ({ phone, reason, summary }) => {
    startHandoff(phone);
    await synap.sdk.memories.create({
      document: `AI handed off to human. Reason: ${reason}. Summary: ${summary}`,
      documentType: "support-handoff",
      userId: phone,
      customerId: CUSTOMER_ID,
      metadata: { handoffReason: reason },
    });
    await notifyHumanConsole(phone, reason, summary);
    return { status: "handed_off" };
  },
});

from fastapi import FastAPI, Request, BackgroundTasks
from heyoo import WhatsApp

app = FastAPI()
wa = WhatsApp(token=os.environ["WABA_ACCESS_TOKEN"], phone_number_id=os.environ["WABA_PHONE_NUMBER_ID"])
CUSTOMER_ID = "your-business"

@app.post("/webhook/whatsapp")
async def webhook(request: Request, bg: BackgroundTasks):
    body = await request.json()
    msg = wa.get_message(body)
    phone = wa.get_mobile(body)
    if msg and phone:
        bg.add_task(handle_inbound, phone, msg)
    return {"ok": True}

async def handle_inbound(phone: str, text: str):
    # Always ingest the inbound, even during handoff
    await sdk.memories.create(
        document=f"Customer: {text}",
        document_type="ai-chat-conversation",
        user_id=phone,
        customer_id=CUSTOMER_ID,
        metadata={"channel": "whatsapp", "direction": "inbound"},
    )

    if is_handoff(phone):
        return  # human owns the thread; AI stays quiet

    reply = await run_ai(phone, text)
    wa.send_message(reply, phone)

    await sdk.memories.create(
        document=f"Agent: {reply}",
        document_type="ai-chat-conversation",
        user_id=phone,
        customer_id=CUSTOMER_ID,
        metadata={"channel": "whatsapp", "direction": "outbound", "tier": "ai"},
    )

// app/api/webhook/whatsapp/route.ts
export const runtime = "nodejs";

export async function POST(req: Request) {
  const body = await req.json();
  const { phone, text } = parseWaInbound(body);
  if (phone && text) {
    handleInbound(phone, text).catch(console.error); // fire-and-forget
  }
  return Response.json({ ok: true });
}

async function handleInbound(phone: string, text: string) {
  await synap.sdk.memories.create({
    document: `Customer: ${text}`,
    documentType: "ai-chat-conversation",
    userId: phone,
    customerId: CUSTOMER_ID,
    metadata: { channel: "whatsapp", direction: "inbound" },
  });

  if (isHandoff(phone)) return;

  const reply = await runAi(phone, text);
  await sendWaMessage(phone, reply);

  await synap.sdk.memories.create({
    document: `Agent: ${reply}`,
    documentType: "ai-chat-conversation",
    userId: phone,
    customerId: CUSTOMER_ID,
    metadata: { channel: "whatsapp", direction: "outbound", tier: "ai" },
  });
}

SYSTEM = """You are a WhatsApp business agent.

- Be concise. WhatsApp users want short replies.
- Recall the customer's history and prior preferences from memory.
- Hand off to a human when: the customer explicitly asks, they're frustrated, the issue is sensitive
  (financial, medical, legal), or you've tried twice without resolution. Use hand_off_to_human.
- Don't promise anything you can't deliver via tools."""

async def run_ai(phone: str, text: str) -> str:
    synap_search = create_search_tool(sdk=sdk, user_id=phone, customer_id=CUSTOMER_ID)
    synap_store  = create_store_tool(sdk=sdk, user_id=phone, customer_id=CUSTOMER_ID)

    agent = Agent(
        name="wa_agent",
        instructions=SYSTEM,
        tools=[
            FunctionTool(synap_search, name_override="synap_search"),
            FunctionTool(synap_store,  name_override="synap_store"),
            hand_off_to_human,
            # ...your business tools
        ],
    )
    result = await Runner.run(agent, input=text)
    return result.final_output

const SYSTEM = `You are a WhatsApp business agent.

- Be concise. WhatsApp users want short replies.
- Recall the customer's history and prior preferences from memory.
- Hand off when: the customer asks, they're frustrated, the issue is sensitive, or you've tried twice.
- Don't promise anything you can't deliver via tools.`;

async function runAi(phone: string, text: string): Promise<string> {
  const model = synap.wrap(openai("gpt-4o"), {
    userId: phone,
    customerId: CUSTOMER_ID,
    conversationId: phone, // one rolling conversation per phone
  });

  const { text: reply } = await generateText({
    model,
    system: SYSTEM,
    prompt: text,
    tools: { hand_off_to_human: handOffToHuman /* + your business tools */ },
  });
  return reply;
}

async def human_reply(phone: str, text: str):
    wa.send_message(text, phone)
    await sdk.memories.create(
        document=f"Human agent: {text}",
        document_type="ai-chat-conversation",
        user_id=phone,
        customer_id=CUSTOMER_ID,
        metadata={"channel": "whatsapp", "direction": "outbound", "tier": "human"},
    )

async def human_release(phone: str):
    end_handoff(phone)
    await sdk.memories.create(
        document="Human released thread back to AI.",
        document_type="support-handoff",
        user_id=phone,
        customer_id=CUSTOMER_ID,
        metadata={"handoff_event": "released"},
    )

export async function humanReply(phone: string, text: string) {
  await sendWaMessage(phone, text);
  await synap.sdk.memories.create({
    document: `Human agent: ${text}`,
    documentType: "ai-chat-conversation",
    userId: phone,
    customerId: CUSTOMER_ID,
    metadata: { channel: "whatsapp", direction: "outbound", tier: "human" },
  });
}

export async function humanRelease(phone: string) {
  endHandoff(phone);
  await synap.sdk.memories.create({
    document: "Human released thread back to AI.",
    documentType: "support-handoff",
    userId: phone,
    customerId: CUSTOMER_ID,
    metadata: { handoffEvent: "released" },
  });
}