WhatsApp-sjablonen & Business API

Tesoro CRM maakt gebruik van de WhatsApp Business API via Twilio om WhatsApp-berichten te versturen en ontvangen. Dit artikel gaat dieper in op de technische werking: hoe sjablonen (templates) functioneren, waarom ze nodig zijn en hoe het 24-uurs gespreksvenster van WhatsApp van invloed is op uw communicatie.

Basisartikel eerst lezen?

Dit artikel bouwt voort op de basisinformatie uit het WhatsApp en SMS-artikel. Als u nog niet bekend bent met het versturen van WhatsApp-berichten in Tesoro CRM, lees dan eerst het WhatsApp en SMS-artikel.

---

WhatsApp Business via Twilio

Hoe de integratie werkt

Tesoro CRM communiceert niet rechtstreeks met WhatsApp. In plaats daarvan verloopt alle WhatsApp-communicatie via Twilio als tussenliggende provider:

1. Tesoro CRM stuurt een verzoek naar de Twilio API met het bericht en het telefoonnummer van de ontvanger.
2. Twilio stuurt het bericht door naar de WhatsApp Business API met het whatsapp:-prefix voor zowel het afzender- als ontvangernummer.
3. WhatsApp bezorgt het bericht aan de ontvanger.
4. Statusupdates (afgeleverd, gelezen, mislukt) worden via Twilio-webhooks automatisch teruggemeld aan Tesoro CRM.
5. Inkomende berichten worden via dezelfde webhook-route ontvangen en in realtime via Pusher-notificaties naar alle teamleden gestuurd.

Vereiste accounts en registraties

Onderdeel	Beschrijving
Twilio-account	Een actief Twilio-account met tegoed. Twilio fungeert als de provider die de verbinding met WhatsApp beheert.
WhatsApp Business-profiel	Uw bedrijf moet een goedgekeurd WhatsApp Business-profiel hebben, geregistreerd via Twilio bij Meta.
Geregistreerd WhatsApp-nummer	Een telefoonnummer dat specifiek is goedgekeurd voor gebruik met de WhatsApp Business API via Twilio. Dit nummer wordt geconfigureerd in Tesoro CRM onder Settings > My Company > Call Settings.
Twilio SID en Token	De API-credentials van uw Twilio-account. Deze worden door uw systeembeheerder geconfigureerd op serverniveau.

Twilio is momenteel de enige ondersteunde provider

Tesoro CRM ondersteunt op dit moment uitsluitend Twilio als WhatsApp-provider. De architectuur is voorbereid op toekomstige uitbreidingen met andere providers, maar momenteel is Twilio de enige optie.

---

Berichtensjablonen (WhatsApp Templates)

Wat zijn WhatsApp-sjablonen?

WhatsApp-sjablonen — ook bekend als HSM-berichten (Highly Structured Messages) — zijn vooraf gedefinieerde berichtformaten die u kunt gebruiken om een gesprek met een contact te starten. WhatsApp/Meta vereist dat het eerste uitgaande bericht naar een contact altijd een goedgekeurd sjabloon gebruikt.

In Tesoro CRM bestaat elk sjabloon uit twee velden:

Veld	Beschrijving	Vereisten
Title	De naam van het sjabloon, zodat u het gemakkelijk kunt herkennen bij selectie.	Verplicht, 3-100 tekens
Description	De daadwerkelijke berichtinhoud die naar het contact wordt verstuurd.	Verplicht, 3-100 tekens

Sjablonen bekijken

Sjablonen worden automatisch geladen wanneer u de WhatsApp-tab opent op een contact-, deal- of leadrecord. De beschikbare sjablonen worden opgehaald via de API-route /whatsapp/template en zijn zichtbaar voor alle gebruikers met de rol Admin of Employee.

Een sjabloonbericht versturen

1. Open een contact, deal, lead of relatie en ga naar de WhatsApp-tab.

2. Als er nog geen gespreksgeschiedenis is, wordt u gevraagd een sjabloon te selecteren om het gesprek te starten.

3. Kies het gewenste sjabloon uit de dropdownlijst. De lijst toont de titel van elk sjabloon.

4. Klik op Get Started. Het systeem verstuurt de beschrijving (description) van het sjabloon als berichttekst naar het telefoonnummer van het contact.

5. Het bericht wordt geregistreerd met de bezorgstatus, het Twilio-berichtkenmerk (SID) en de richting (uitgaand).

Sjablooninhoud = description-veld

Let op: wanneer u een sjabloonbericht verstuurt, wordt de inhoud van het description-veld als berichttekst verzonden, niet de titel. De titel dient alleen ter herkenning bij het selecteren van het sjabloon.

---

Sjabloon-goedkeuringsproces

Hoe sjablonen worden goedgekeurd

WhatsApp-sjablonen moeten voldoen aan het goedkeuringsbeleid van Meta (het moederbedrijf van WhatsApp). Het goedkeuringsproces verloopt als volgt:

1. Sjabloon aanmaken — Sjablonen worden aangemaakt in uw Twilio-account of via de Meta Business Manager. Hierin definieert u de berichttekst, de categorie (marketing, transactioneel of authenticatie) en eventuele variabelen.

2. Beoordeling door Meta — Meta beoordeelt het sjabloon op naleving van het WhatsApp Business-beleid. Dit kan enkele minuten tot meerdere dagen duren.

3. Goedkeuring of afwijzing — U ontvangt een melding in uw Twilio-dashboard of Meta Business Manager over de status van het sjabloon.

4. Registratie in Tesoro CRM — Zodra het sjabloon is goedgekeurd, wordt het in Tesoro CRM beschikbaar gesteld via de sjablonenlijst. Sjablonen worden opgeslagen in de database met een titel en beschrijving.

Veelvoorkomende redenen voor afwijzing

Reden	Toelichting
Misleidende inhoud	Het sjabloon bevat onjuiste of misleidende informatie.
Ontbrekende opt-out	Er is geen mogelijkheid voor de ontvanger om zich af te melden.
Verboden inhoud	Het sjabloon bevat inhoud die in strijd is met het WhatsApp-beleid (bijv. gokken, alcohol).
Onjuiste opmaak	Variabelen of opmaak voldoen niet aan de technische vereisten.

Niet-goedgekeurde sjablonen worden geweigerd

Als u een sjabloon probeert te gebruiken dat niet (meer) is goedgekeurd door Meta, zal het bericht worden geweigerd door de WhatsApp Business API. Controleer altijd de sjabloonstatus in uw Twilio-dashboard voordat u het in Tesoro CRM gebruikt.

---

Vrije berichten vs. sjablonen

Tesoro CRM ondersteunt twee manieren om WhatsApp-berichten te versturen, elk met een eigen API-endpoint:

Sjabloonberichten

• Endpoint: send-whatsapp-message-by-template-id
• Wanneer: Het eerste bericht naar een contact, of wanneer het 24-uurs gespreksvenster is verlopen.
• Hoe: U selecteert een sjabloon uit de lijst. Het systeem verstuurt de sjablooninhoud (description) als berichttekst.
• Bijlagen: Niet ondersteund bij sjabloonberichten.

Vrije berichten (freeform)

• Endpoint: send-whatsapp-message
• Wanneer: Nadat het contact heeft geantwoord en het 24-uurs gespreksvenster actief is.
• Hoe: U typt een vrij bericht (maximaal 1.600 tekens) en verstuurt het.
• Bijlagen: U kunt tot 10 bestanden bijvoegen (maximaal 1,5 MB per bestand). Ondersteunde typen zijn documenten, afbeeldingen, audio, video en archieven.

Kenmerk	Sjabloonbericht	Vrij bericht
Eerste bericht	Ja (verplicht)	Nee
Berichtinhoud	Vooraf gedefinieerd (sjabloonbeschrijving)	Vrij in te vullen
Maximale lengte	100 tekens (sjabloonlimiet)	1.600 tekens
Bestandsbijlagen	Niet ondersteund	Tot 10 bestanden (1,5 MB per stuk)
Goedkeuring vereist	Ja (via Meta)	Nee

---

Het 24-uurs gespreksvenster

Hoe het werkt

WhatsApp hanteert een 24-uurs gespreksvenster om spam te voorkomen en gebruikers te beschermen. Dit werkt als volgt:

1. U verstuurt een sjabloonbericht naar een contact — dit opent een nieuw gesprek.
2. Het contact antwoordt — hiermee wordt het 24-uurs venster geopend.
3. Gedurende 24 uur na het laatste antwoord van het contact kunt u vrije berichten versturen zonder sjabloon.
4. Na 24 uur zonder antwoord van het contact sluit het venster en moet u opnieuw een sjabloonbericht versturen om het gesprek te hervatten.

Tijdlijn:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  U stuurt         Contact        Vrije berichten     Venster
  sjabloon ──────► antwoordt ────► toegestaan ────────► sluit
                   ▲                                    (24u)
                   │
                   └─ 24-uurs venster start hier
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Dit is een WhatsApp-vereiste, geen Tesoro-beperking

Het 24-uurs gespreksvenster is een beleidsvereiste van WhatsApp/Meta. Tesoro CRM kan dit niet omzeilen. Als het venster is verlopen, moet u een nieuw sjabloonbericht versturen om het gesprek te hervatten.

Wat als het venster verlopen is?

Wanneer u een vrij bericht probeert te sturen terwijl het 24-uurs venster is verlopen, zal het bericht worden geweigerd door de WhatsApp Business API. In dat geval:

1. Ga terug naar de sjabloonselectie.
2. Selecteer een goedgekeurd sjabloon.
3. Verstuur het sjabloonbericht om het gesprek te heropenen.
4. Wacht tot het contact antwoordt voordat u vrije berichten stuurt.

---

Mediaberichten

Bestanden versturen

Bij vrije berichten (niet bij sjabloonberichten) kunt u mediabestanden meesturen. Het systeem verwerkt bestanden en tekstberichten als afzonderlijke berichten:

• Elk bestand wordt als een apart WhatsApp-bericht verstuurd via Twilio met de mediaUrl-parameter.
• De berichttekst wordt als een apart bericht verstuurd.
• Bestanden worden opgeslagen in het Tesoro CRM-bestandssysteem en gekoppeld aan het WhatsApp-berichtrecord.

Ondersteunde bestandstypen en limieten

Type	Voorbeelden
Documenten	PDF, Word, Excel
Afbeeldingen	JPEG, PNG, GIF, WebP
Audio	MP3, OGG
Video	MP4
Archieven	ZIP, RAR

Limieten:

• Maximaal 10 bestanden per bericht
• Maximaal 1,5 MB per bestand

Bestanden ontvangen

Wanneer een contact een bestand stuurt via WhatsApp, wordt dit automatisch:

1. Gedetecteerd via het NumMedia-veld in de Twilio-webhook.
2. Gedownload vanaf de Twilio media-URL.
3. Opgeslagen in het Tesoro CRM-bestandssysteem met de juiste bestandsextensie (afgeleid van het MIME-type).
4. Gekoppeld aan het WhatsApp-berichtrecord en het bijbehorende contactrecord.

---

Bezorgstatus en realtime updates

Statustracking

Elk WhatsApp-bericht in Tesoro CRM heeft een bezorgstatus die automatisch wordt bijgewerkt via Twilio-webhooks. Mogelijke statussen zijn:

Status	Beschrijving
queued	Het bericht staat in de wachtrij bij Twilio.
sent	Het bericht is verstuurd naar WhatsApp.
delivered	Het bericht is afgeleverd op het apparaat van de ontvanger.
read	De ontvanger heeft het bericht gelezen.
failed	Het bericht kon niet worden bezorgd.

Realtime notificaties

Tesoro CRM maakt gebruik van Pusher om realtime updates te versturen naar alle teamleden:

• Inkomend bericht — Wanneer een contact een WhatsApp-bericht stuurt, ontvangen alle gebruikers van het bedrijf direct een notificatie.
• Statusupdate — Wanneer de bezorgstatus van een bericht verandert (bijv. van “sent” naar “delivered”), wordt dit in realtime bijgewerkt in de chatweergave.

---

Kosten

WhatsApp Business-berichten via Twilio brengen kosten met zich mee. De tarieven zijn afhankelijk van meerdere factoren:

Kostencomponent	Toelichting
Twilio-berichttarief	Twilio rekent een bedrag per verstuurd en ontvangen bericht. Tarieven varieren per land.
WhatsApp-gesprekstarief	Meta rekent een tarief per gespreksvenster (24 uur). Er zijn verschillende tarieven voor door het bedrijf gestarte gesprekken (sjabloonberichten) en door de gebruiker gestarte gesprekken (antwoorden).
Sjablooncategorie	Marketing-sjablonen zijn doorgaans duurder dan transactionele of authenticatie-sjablonen.
Mediaberichten	Berichten met bijlagen kunnen extra kosten met zich meebrengen, afhankelijk van het bestandsformaat en de grootte.

Kosten beheren

Raadpleeg de Twilio WhatsApp-tarieven voor actuele prijsinformatie. Houd er rekening mee dat tarieven regelmatig worden bijgewerkt door zowel Twilio als Meta.

---

Rechten en toegang

De volgende rechten zijn van toepassing op WhatsApp-functionaliteit in Tesoro CRM:

Actie	Toegestane rollen
WhatsApp-berichten versturen (vrij)	Admin, Employee
WhatsApp-berichten versturen (sjabloon)	Admin, Employee
WhatsApp-berichten lezen	Admin, Employee
WhatsApp-sjablonen bekijken	Admin, Employee

---

Probleemoplossing

Veelvoorkomende problemen met sjablonen

• Sjabloon wordt niet weergegeven — Controleer of het sjabloon correct is aangemaakt en goedgekeurd in uw Twilio-dashboard. Sjablonen moeten zowel een titel als een beschrijving hebben (elk 3-100 tekens).
• “The selected template doesn’t match our records” — Het geselecteerde sjabloon-ID bestaat niet in de database. Dit kan voorkomen als het sjabloon is verwijderd.
• Bericht geweigerd na 24 uur — Het gespreksvenster is verlopen. Verstuur een nieuw sjabloonbericht om het gesprek te hervatten.
• Bijlagen niet mogelijk bij sjabloon — Sjabloonberichten ondersteunen geen bestandsbijlagen. Gebruik een vrij bericht nadat het gespreksvenster is geopend.
• “Company with Twilio WhatsApp number attached not found” — Het WhatsApp-nummer in de Twilio-webhook komt niet overeen met een bedrijf in Tesoro CRM. Controleer de nummerconfiguratie in Settings > My Company > Call Settings.

---

Volgende stappen

WhatsApp en SMS Leer de basisprincipes van het versturen en ontvangen van WhatsApp-berichten en SMS in Tesoro CRM.

Telefoongesprekken Plan, voer en registreer telefoongesprekken rechtstreeks vanuit Tesoro CRM via Twilio-integratie.