WhatsApp API FAQ

Installeer de SDK, pak een API-sleutel en roep het verzendendpoint aan met een vooraf goedgekeurde template. Bird biedt beheerde afzendernummers, dus er is geen nummerprovisioning nodig vóór uw eerste verzending.

Eén verzendendpoint dat een template of vrije inhoud accepteert, een vooraf goedgekeurde templatecatalogus, bezorg- en leesbevestigingsgebeurtenissen via de API en webhooks, een tijdlijn per bericht, inkomende berichten en media, geaggregeerde bezorgstatistieken en door Bird beheerde afzendernummers voor uw eerste verzending. Dezelfde API-sleutels en regionale hosts als Bird Email en SMS.

Het betekent dat Bird uw bericht heeft geaccepteerd en het asynchroon zal afleveren. De 202 is geen afleverbevestiging. Aflevering, leesbevestigingen en fouten komen later binnen als events die u kunt pollen of via webhooks kunt ontvangen.

Beide. Een template bereikt iedereen op elk moment, en daarom is het de enige manier om een gesprek te starten. Vrije inhoud bereikt een contact binnen het 24-uurs klantenservicevenster dat hun eigen bericht opent, en alleen vanaf een nummer dat uw workspace bezit. Bird houdt dat venster niet voor u bij, dus een vrije verzending buiten een venster wordt geaccepteerd en mislukt vervolgens met service_window_expired.

Ja. Een bericht van een contact komt binnen via de whatsapp.received-webhook, verschijnt in het WhatsApp-logboek in het dashboard en telt mee op het tabblad Inkomend van de Statistiekenpagina. Inkomende berichten bereiken u alleen op uw eigen nummers: door Bird beheerde nummers worden gedeeld tussen workspaces, dus een bericht dat naar zo'n nummer wordt gestuurd, wordt niet voor uw workspace geregistreerd.

Per bericht, op basis van de categorie van de template (authenticatie, utility of marketing) en het land van de ontvanger. De kosten worden in rekening gebracht wanneer Bird het bericht accepteert, niet wanneer de ontvanger het leest.

Een hoger tarief per bericht dat Meta in rekening brengt wanneer uw bedrijf zich buiten het land van de ontvanger bevindt en u authenticatietemplates verstuurt. U komt hiervoor in aanmerking nadat u meer dan 750.000 authenticatietemplate-berichten naar gebruikers in één land hebt verstuurd binnen een voortschrijdende periode van 30 dagen. Uw primaire bedrijfslocatie, ingesteld in Meta Business Manager, bepaalt welke verzendingen in aanmerking komen.

Gedeelde afzenders betalen altijd het internationale tarief voor authenticatietemplates, ongeacht uw volumedrempel. Alle WhatsApp-nummers worden momenteel door Bird beheerd, dus dit tarief geldt voor authenticatieverzendingen waarbij uw bedrijf zich buiten het land van de ontvanger bevindt.

De pagina's Gebruik en Uitgaven in het dashboard tonen uw WhatsApp-kosten. Het berichtenlogboek toont de categorie en kosten per individueel bericht zodra het is geprijsd.

Nee. Elk WhatsApp-bericht is een afzonderlijke API-aanroep naar POST /v1/whatsapp/messages met één ontvanger. Om naar meerdere ontvangers te versturen, loopt u over het verzendendpoint.

De rate group whatsapp_send is van toepassing op het verzendendpoint. Elke respons bevat een IETF RateLimit-header met het resterende quotum en de resettijd, dus stuur daarop in in plaats van op een hardgecodeerd getal. Betaalde abonnementen verhogen het basispercentage.

Ja, als vrije inhoud. Het verzendendpoint ondersteunt afbeelding, video, audio, sticker, document en locatie naast tekst. Net als bij elke vrije verzending is een open 24-uurs klantenservicevenster en een nummer dat uw workspace bezit vereist. Templateparameters blijven zelf tekstgebaseerd.

Een vooraf goedgekeurde berichtstructuur die via Meta bij WhatsApp is geregistreerd. Elke template heeft een naam, een of meer talen, een categorie (authenticatie, utility of marketing) en plaatsaanduidingsvariabelen die u bij verzending invult. Bird levert een beheerde catalogus die u direct kunt gebruiken, en u kunt uw eigen templates aanmaken zodra u een WhatsApp Business Account hebt gekoppeld.

Meta beoordeelt en keurt elke template goed, ongeacht of Bird deze heeft ingediend of u. Een template kan in het algemeen actief zijn, maar afzonderlijke talen kunnen een afgewezen of gepauzeerde status hebben. Controleer daarom de status per taal voordat u in die taal verzendt.

Authenticatie (eenmalige wachtwoorden en inlogflows), utility (orderupdates, accountmeldingen) en marketing (promoties en aanbiedingen). De categorie bepaalt welk afzendernummer Bird selecteert en hoe het bericht wordt geprijsd.

Stuur een components-array mee met body- en buttonparameters bij het verzenden. Parameters kunnen benoemd zijn (gekoppeld aan een sleutel zoals 'name') of positioneel (gekoppeld aan een index). Benoemde parameters zijn veiliger wanneer de variabelevolgorde van een template kan wijzigen.

Ja, op de Templatespagina in het dashboard, zodra uw workspace een eigen WhatsApp Business Account heeft gekoppeld. De builder ondersteunt momenteel platte tekst in één taal. Aanmaken via de publieke API is niet beschikbaar, maar het verzendendpoint accepteert elke template die uw workspace kan verzenden, beheerd of eigen.

Nee. Bird biedt beheerde afzendernummers. Authenticatietemplates worden verzonden vanaf een dedicated nummer, en utility- en marketingtemplates delen een notificatienummer. De pagina Numbers in het dashboard toont de nummers die beschikbaar zijn voor uw workspace.

Ja, en door er een te koppelen kunt u verzenden als uw eigen merk: uw eigen templates, vrije inhoud binnen een open klantenservicevenster en inkomende berichten. Door Bird beheerde nummers worden gedeeld tussen workspaces en gebruiken alleen beheerde templates, dus beschouw ze als het pad zonder setup voor een eerste verzending, niet als de eindsituatie.

Voor een beheerde template, op basis van de categorie: authenticatie gebruikt een speciaal afzendernummer, terwijl utility en marketing een notificatienummer delen. Al het andere benoemt zijn eigen afzender in het from-veld, wat een nummer moet zijn dat uw workspace bezit, en een template die u zelf hebt aangemaakt moet op hetzelfde WhatsApp Business Account staan als dat nummer.

Stuur een POST naar /v1/whatsapp/messages met het E.164-telefoonnummer van de ontvanger, een template-slug en waarden voor de variabelen van het template. Bird valideert het verzoek, retourneert 202 met een bericht-ID en bezorgt asynchroon.

Stuur een Idempotency-Key header mee en een herhaald verzoek retourneert het oorspronkelijke resultaat in plaats van het bericht dubbel te versturen. Zonder deze header wordt een herpoging als een nieuw bericht behandeld en ontvangt de ontvanger een duplicaat.

Ja. Tags zijn maximaal 20 gestructureerde labels waarop u kunt filteren en groeperen in het berichtenlogboek en de statistieken. Metadata is willekeurige JSON (maximaal 2 KB) die wordt meegestuurd bij het bericht en de bijbehorende events, handig om verzendingen te koppelen aan uw eigen systemen.

Elke statuswijziging triggert een webhook-event: accepted, sent, delivered, read, failed of rejected. U kunt ook de eventtijdlijn van het bericht opvragen via de API. Een delivered-status betekent dat WhatsApp heeft bevestigd dat het apparaat van de ontvanger het bericht heeft ontvangen.

Zes levenscyclusevents: whatsapp.accepted (Bird heeft het in de wachtrij geplaatst), whatsapp.sent (ingediend bij WhatsApp), whatsapp.delivered (het apparaat van de ontvanger heeft het ontvangen), whatsapp.read (de ontvanger heeft het geopend), whatsapp.failed (WhatsApp heeft het geweigerd na indiening) en whatsapp.rejected (Bird heeft het geweigerd vóór indiening, geen kosten).

Nee. Een read-event betekent dat de ontvanger het bericht heeft geopend, maar de berichtstatus blijft op delivered staan. Read wordt apart gerapporteerd als een tijdstempel en een whatsapp.read-event, niet als een statuswijziging.

Rejected betekent dat Bird het bericht heeft geweigerd voordat het bij WhatsApp werd ingediend, dus er worden geen kosten in rekening gebracht. Failed betekent dat Bird het heeft ingediend, maar WhatsApp de aflevering heeft geweigerd. Beide bevatten een error-object met een code, beschrijving en Meta-foutcode indien van toepassing.

Op twee manieren: haal de tijdlijn op voor een specifiek bericht met GET /v1/whatsapp/messages/{id}/events, of abonneer een webhook-endpoint op whatsapp.*-eventtypes en ontvang ze in realtime. De pagina Messages in het dashboard toont ook de event-tijdlijn per bericht.

Op de pagina Metrics in de WhatsApp-dashboard-app. Daar ziet u het afleverpercentage, het faalpercentage, het geaccepteerde volume en de afleverlatentie (verwerking en end-to-end) van alles wat uw workspace verstuurt.

Op afzendernummer, op template, op templatecategorie en op tag. Een faalpercentage dat er in totaal prima uitziet, blijkt vaak te worden veroorzaakt door één template of één tag die de meeste fouten genereert.

Twee: verwerkingslatentie (aan de kant van Bird, van acceptatie tot verzending) en totale latentie (end-to-end, van acceptatie tot ontvangstbevestiging). Beide worden gerapporteerd op p50, p95 en p99.

Nog niet voor geaggregeerde statistieken. U kunt uw eigen aggregaties opbouwen vanuit webhook-events of vanuit de berichtenlijst-API, die de status en de event-tijdlijn per bericht bevat.

WhatsApp biedt end-to-end-versleuteling voor berichten tussen de afzender en het apparaat van de ontvanger. Uw API-aanroep naar Bird verloopt via HTTPS, en webhook-events die Bird naar u verstuurt zijn HMAC-ondertekend.

Elk event is HMAC-ondertekend. Verifieer de handtekening met het geheim van uw endpoint voordat u actie onderneemt op de payload, en roteer dat geheim via het dashboard wanneer nodig.

In de regio waar uw organisatie gehost is, ofwel us1 of eu1. Uw API-sleutel bevat dit in het prefix (bk_us1_, bk_eu1_), waardoor de SDK's en CLI automatisch het juiste endpoint kiezen zonder dat u er een hoeft te configureren.

Alleen waarvoor u deze hebt afgebakend. Een sleutel bevat een lijst met scopes, elk met lees- of schrijfrechten, zodat een sleutel die WhatsApp-berichten verstuurt niet uw nummers kan beheren of een ander kanaal kan uitlezen. Sleutels ondersteunen ook IP-allowlists en veilige rotatie met een configureerbare overgangsperiode.

Certificeringen en beveiligingsdocumentatie vindt u op trust.bird.com. De gegevensverwerkingsovereenkomst, privacyverklaring en het beleid voor aanvaardbaar gebruik staan op bird.com/legal. Voor een leveranciersvragenlijst kunt u terecht bij uw Bird-accountteam.