Zet een OpenAI Agents SDK-agent op WhatsApp

Hoe wordt een WhatsApp-bericht een agent-run?

Via een route in je eigen applicatie die Meta aanroept. Stel de webhook-URL van het nummer erop in, met een lang willekeurig geheim in het pad. De route beantwoordt de verificatie-GET van Meta door hub.challenge als platte tekst terug te geven. Elke POST accepteert hij, hij antwoordt direct met 200 en zet het werk in een wachtrij. Meta probeert trage antwoorden namelijk opnieuw, en dan draai je de agent twee keer.

Een worker leest daarna de afzender en de tekst uit de payload en roept Runner.run aan. Geef een sessie mee met het nummer van de afzender als id: de SDK bewaart het gesprek onder dat id. Het volgende bericht van dezelfde klant gaat dus verder waar het vorige ophield, en twee klanten delen nooit een geschiedenis. SQLiteSession is genoeg om te beginnen. Voor meerdere workers levert de SDK ook Redis- en SQLAlchemy-sessies mee.

Het geheim in de URL is hier de authenticatie. Meta ondertekent leveringen met het app secret van de Tech Provider, dus de klant kan de handtekening in de header niet valideren.

import os, httpx
from agents import Agent, Runner, SQLiteSession

agent = Agent(name="Front desk", instructions="Answer briefly and politely.")
URL = f"https://graph.facebook.com/v25.0/{os.environ['PHONE_NUMBER_ID']}/messages"

async def handle(sender: str, text: str) -> None:
    session = SQLiteSession(sender, "whatsapp.db")
    result = await Runner.run(agent, text, session=session)
    async with httpx.AsyncClient() as http:
        await http.post(
            URL,
            headers={"Authorization": f"Bearer {os.environ['WA_TOKEN']}"},
            json={"messaging_product": "whatsapp", "to": sender,
                  "type": "text", "text": {"body": result.final_output}},
        )

Waarom verstuurt je code het antwoord en niet de agent?

Omdat de ene regel die je nooit mag breken een tijdsregel is, en code dwingt die beter af dan een prompt. Meta opent een klantenservicevenster van 24 uur zodra een klant schrijft. Binnen dat venster komt vrije tekst door. Daarbuiten lukt dat alleen met een goedgekeurd template, en vrije tekst komt terug met foutcode 131047.

Een worker die het zojuist binnengekomen bericht beantwoordt, zit altijd binnen het venster. result.final_output als tekst versturen is dus veilig door ontwerp. Werk dat later gebeurt, zoals een opvolging de volgende ochtend of een herinnering, loopt via een apart pad dat een template verstuurt en nooit vrije tekst.

De agent mag wel tools hebben. Geef hem function tools om iets op te zoeken, zoals een bestelling of een boeking, en laat het versturen via WhatsApp bij de worker. Zo blijft het toegangstoken ook buiten bereik van alles wat het model met willekeurige argumenten kan aanroepen.

Kan de agent de EasyCoexistence MCP-server gebruiken?

Ja, via MCPServerStreamableHttp, met wat meer setup dan een header. De SDK accepteert een Authorization-header of een httpx.Auth in params["auth"]. De EasyCoexistence MCP-server geeft na een aanmelding in de browser eigen OAuth-tokens uit, met dynamic client registration en PKCE, dus een statische sleutel bestaat niet. De MCP Python SDK levert OAuthClientProvider mee, een HTTP-auth-handler die die flow met PKCE en token-vernieuwing uitvoert, en die komt in params["auth"].

Het loont als de agent zelf moet beslissen: de gezondheid van een nummer controleren, de status van een template lezen, of kiezen tussen send_message en send_template op basis van de regels in de toolbeschrijvingen. Voor een receptie die alleen antwoordt, is de worker hierboven korter en gaat er minder mis.

In beide gevallen blijft de webhook nodig. MCP is verzoek en antwoord, en een bericht van een klant kan de agent alleen bereiken via de route die Meta aanroept.

Veelgemaakte fouten

• De agent draaien voordat je 200 aan Meta teruggeeft. Een traag antwoord wordt opnieuw geprobeerd, en de klant krijgt twee antwoorden.
• Eén sessie voor alle klanten gebruiken. Koppel de sessie aan het nummer van de afzender, anders lopen de geschiedenissen door elkaar.
• Een uitgestelde opvolging vrije tekst laten versturen. Na 24 uur mislukt dat met foutcode 131047. Verstuur dan een template.

Veelgestelde vragen

Lees verder