WhatsApp Template API

Developer-API

Verstuur goedgekeurde WhatsApp-templates vanuit uw eigen systemen met één API-aanroep; het gesprek gaat daarna verder in MonoChat.

• WhatsApp
• REST API
• Alleen API

Installeren vanuit MonoStoreBekijken op monochat.ai

Overzicht

Met WhatsApp Template API kunnen uw CRM, ERP, webshop of elke backend via MonoChat een goedgekeurd WhatsApp-templatebericht naar een klant sturen. Eén verzoek bevat het WhatsApp-nummer waarvan wordt verzonden, het telefoonnummer van de klant, de template en de variabelen ervan.

Wanneer de klant antwoordt, komt het gesprek zoals elk ander in uw MonoChat-inbox terecht. De app heeft geen eigen schermen: alles gebeurt via drie API-endpoints.

Highlights

• Eén API-aanroep. Verstuur een template op naam en taal, met header-, body-, knop- en carrouselvariabelen gevuld vanuit uw gegevens.
• Rechtstreeks naar de chat. Elke verzending geeft de id van het gesprek terug en een directe link ernaar in MonoChat.
• Nieuwe klanten welkom. Als het telefoonnummer nog geen klant is, wordt de klant aangemaakt met de naam die u meestuurt.

Installeren en instellen

1. Koppel uw WhatsApp Business-nummer aan MonoChat en zorg dat het is geverifieerd en door Meta goedgekeurde templates heeft.
2. Installeer WhatsApp Template API via Instellingen › MonoStore › Apps, of open de installatielink app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Heeft u nog geen MonoChat-account, dan kunt u zich via de link eerst registreren en wordt de app voor u geïnstalleerd.
3. Maak een API-token aan onder Profiel › API-tokens. Het token wordt maar één keer getoond, dus kopieer het meteen.
4. Roep template/list.js aan om uw goedgekeurde templates en hun variabelen te zien.
5. Roep template/send.js aan met het nummer van de klant en de waarden van de variabelen om uw eerste template te versturen.

notitie

• Elk bericht wordt gefactureerd zoals elk templatebericht dat vanuit MonoChat wordt verzonden.
• Media-URL’s moeten bereikbaar blijven totdat WhatsApp het bestand heeft opgehaald.
• Verstuur alleen naar klanten die ermee hebben ingestemd van u te horen: WhatsApp kan nummers beperken waarvan de berichten worden geblokkeerd of gerapporteerd.

Functies

Templates opvragen

De goedgekeurde templates van een WhatsApp-nummer, met taal, categorie, status en variabelen, zodat uw systeem weet wat het kan versturen.

Een template verzenden

Op templatenaam en taal, met header-, body-, knop- en carrouselvariabelen. Een ontbrekende waarde stopt de verzending, zodat er niets half ingevuld bij de klant aankomt.

Aan een medewerker toewijzen

Geef het e-mailadres van een medewerker op en het gesprek wordt op zijn of haar naam geopend.

Mediaheaders

Vraag kortlevende uploadgegevens op, plaats een afbeelding, video of document in de opslag van MonoChat en gebruik de URL ervan als header van de template.

Link naar het gesprek

Elke verzending geeft de sessie-id, de bericht-id en een link terug die het gesprek in MonoChat opent.

Duidelijke foutmeldingen

Een mislukte aanroep zegt wat er misging, bijvoorbeeld “Channel not found” of “Variable missing”.

Voordat u begint

• Uw WhatsApp Business-nummer is gekoppeld aan MonoChat en geverifieerd. Zie Kanalen.
• De templates die u wilt versturen, zijn door Meta goedgekeurd. Met templates schrijft u als eerste, of bereikt u een klant buiten het venster van 24 uur. Zie Sjabloonberichten.
• U heeft een API-token onder Profiel › API-tokens. Zie API-tokens.
• U kent uw tenant slug: het deel na /tenants/ in uw MonoChat-adres. In https://app.monochat.ai/tenants/mybusiness is de slug mybusiness.

API-referentie

De app heeft geen eigen schermen. Alles gebeurt via drie endpoints, elk een POST met een JSON-body:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	Wat het doet
template/list.js	Toont de templates van een van uw WhatsApp-nummers, met hun variabelen.
template/send.js	Verstuurt een template naar een klant en geeft een link naar het gesprek terug.
upload/get-token.js	Geeft kortlevende uploadgegevens voor een header met afbeelding, video of document.

Telefoonnummers worden altijd geschreven met landcode en zonder +, bijvoorbeeld 905334445566. Een geslaagde aanroep antwoordt met 200 en de gegevens van het endpoint onder result.

1. Templates opvragen

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Toont alle templates van het opgegeven WhatsApp Business-nummer: naam, taalcode, categorie, componenten (header, body, footer, knoppen), variabeletypen en goedkeuringsstatus.

Veld	Verplicht	Beschrijving
phoneNumber	ja	Uw WhatsApp Business-nummer in MonoChat, met landcode, zonder +.
options	nee	Paginering en filters, bijvoorbeeld { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Antwoord (ingekort):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Zo leest u het:

• name: de systeemnaam waarmee u de template verstuurt.
• languageCode: de taal waarin u hem verstuurt.
• category: de WhatsApp-categorie (MARKETING, UTILITY, AUTHENTICATION).
• components: de onderdelen waaruit de template is opgebouwd.

Component	Inhoud	Beschrijving
HEADER	IMAGE, VIDEO, DOCUMENT of tekst	Bij media wordt de format opgegeven; variabelen staan onder variables.
BODY	Tekst met variabelen	De berichttekst, met plaatshouders zoals {{1}}, {{2}}.
FOOTER	Tekst	Heeft meestal geen variabelen.
BUTTONS	URL, snelle reactie…	Knopteksten en hun variabelen, indien aanwezig.

De voorbeeldtemplate hierboven heeft één afbeelding nodig voor de header en twee teksten voor de body (naam van de klant en naam van het product). De footer is vast (“Teşekkürler”) en er zijn geen knoppen.

2. Een template verzenden

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Verstuurt een goedgekeurde template naar een klant. Als het telefoonnummer nog geen klant is, wordt de klant aangemaakt; het gesprek wordt geopend (of hergebruikt) en de template wordt daarin verstuurd.

Veld	Verplicht	Beschrijving
phoneNumber	ja	Het WhatsApp Business-nummer waarvan wordt verzonden. Het moet aan MonoChat zijn gekoppeld en geverifieerd.
templateMessageName	ja	De name van de template, precies zoals de lijst hem teruggeeft.
languageCode	ja	De taal van de template, zoals de lijst die teruggeeft (bijvoorbeeld tr-TR).
customerPhoneNumber	ja	Het WhatsApp-nummer van de klant.
variables	als de template er heeft	De waarden van de variabelen van de template (zie hieronder).
customerFirstName, customerLastName	nee	Wordt gebruikt als de klant nieuw is in MonoChat.
agentEmailAddress	nee	Wijst het gesprek toe aan de medewerker met dit e-mailadres.

Variabelen. Elk item van de array variables heeft een type en een lijst parameters, in de volgorde van de plaatshouders van de template:

type	parameters
HEADER	De tekstvariabele van de header, of de openbare URL van de afbeelding, video of het document in de header.
BODY	De {{1}}, {{2}}, … van de body, op volgorde.
BUTTONS	Eén waarde voor elke knop met een variabele (bijvoorbeeld het dynamische deel van een URL-knop of een couponcode), in de volgorde van de knoppen.
CAROUSEL	In plaats van parameters een array cards met één item per carrouselkaart, elk met eigen components.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Een ontbrekende waarde stopt de verzending met Variable missing, zodat er niets half ingevuld bij de klant aankomt. FOOTER heeft zelden variabelen.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Antwoord:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url: opent het gesprek in MonoChat, voor mensen die zijn ingelogd en het mogen zien.
• sessionId: de id van het gesprek.
• messageId: de id van het bericht in MonoChat. De bezorg- en leesstatus verschijnen in de chat zoals bij elk ander bericht.

Media in templates. WhatsApp downloadt de media voor de header van de URL die u opgeeft, dus de URL moet geldig en openbaar bereikbaar zijn. Links waarvoor u moet inloggen werken niet. Als u het bestand met upload/get-token.js hebt geüpload, gebruikt u de URL van het bestand die u uit dat antwoord opbouwt.

3. Media voor een header uploaden

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Wanneer de header van een template een afbeelding, video of document is, heeft het bestand een openbaar adres nodig waarvan WhatsApp het kan downloaden. Dit endpoint geeft u kortlevende toestemming om het bestand in de opslag van MonoChat te plaatsen.

Veld	Verplicht	Beschrijving
fileName	ja	De bestandsnaam met extensie, bijvoorbeeld product.jpg of promo.pdf.

Bestanden worden altijd opgeslagen in de map chat-assets van uw workspace; oudere voorbeelden die een veld key meesturen blijven werken, de waarde is niet nodig.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

Het antwoord vertelt u waar u het bestand moet plaatsen en geeft de gegevens om dat te doen:

Veld	Beschrijving
bucket, region, path	Waar het bestand naartoe gaat.
temporaryCredentials	Gegevens die alleen voor uploaden gelden, voor dat ene pad, 15 minuten geldig.
baseUrl	Het openbare adres van de opslag. De URL van het bestand is baseUrl + / + path.

Upload het bestand direct met een S3-client en deze gegevens, en geef de URL ervan daarna als parameter HEADER mee wanneer u de template verstuurt. Zeer grote bestanden of formaten die WhatsApp niet ondersteunt (het accepteert gangbare afbeeldings-, video- en pdf-formaten) mislukken.

Voorbeeld: een template met een afbeelding in de header

Stel dat u een goedgekeurde template new_product_announcement heeft met een afbeelding in de header en twee variabelen in de body (naam van de klant en naam van het product), en u wilt die naar een klant versturen.

1. Vraag de templates op. Roep template/list.js aan met uw WhatsApp-nummer en zoek new_product_announcement. De componenten tonen één IMAGE-variabele in de header en twee TEXT-variabelen in de body.
2. Upload de afbeelding. Roep upload/get-token.js aan met { "fileName": "urun.jpg" }, upload het bestand met de teruggegeven gegevens en bouw de URL ervan op uit baseUrl en path.
3. Verstuur de template. Roep template/send.js aan met de URL van het bestand als parameter HEADER en ["Ayşe", "XYZ Telefon"] als parameters BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Had de template knopvariabelen, dan voegt u op dezelfde manier een item BUTTONS toe.
4. Open de chat. De url in het antwoord opent het gesprek; wanneer de klant antwoordt, gaat het verder in uw MonoChat-inbox.

Fouten

Een mislukte aanroep antwoordt met een foutstatus en een bericht dat zegt wat er misging. Log deze berichten in uw systeem en toon uw gebruikers waar nodig een begrijpelijke melding.

Bericht	Oorzaak
phoneNumber field is required	template/list.js is aangeroepen zonder phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Een verplicht veld van template/send.js ontbreekt.
Channel not found	Het phoneNumber is geen WhatsApp-nummer van uw workspace.
Channel is not verified	Het WhatsApp-nummer is gekoppeld maar niet geverifieerd.
Template message not found	Er is geen goedgekeurde template met die naam en taal op het nummer. Controleer de spelling en languageCode.
Template message is not approved	De template bestaat maar is niet door Meta goedgekeurd.
Variable missing: …	variables komt niet overeen met de template, bijvoorbeeld de template heeft twee waarden voor de body nodig en u stuurde er één.
Agent user not found	Er is geen medewerker met het e-mailadres in agentEmailAddress.
Customer Channel not found	De WhatsApp-identiteit van de klant kon niet worden aangemaakt of gevonden.

HTTP-statuscodes die u kunt zien:

• 401 Unauthorized: de header Authorization: Bearer <API_TOKEN> ontbreekt, of het token is onjuist of verlopen. Gebruik een geldig token uit uw account.
• 403 Forbidden: het token heeft geen toegang tot deze workspace of app, bijvoorbeeld door een onjuiste tenant slug.
• 404 Not Found: het endpointadres is onjuist. Controleer het volledige pad /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: een onverwacht probleem in MonoChat of bij de WhatsApp-provider, of een weigering aan WhatsApp-zijde (het nummer staat niet op WhatsApp, de klant heeft u geblokkeerd, kwaliteits- of snelheidslimieten). Probeer het later opnieuw en neem contact op met MonoChat-support als het aanhoudt.

Schermafbeeldingen

Een goedgekeurde WhatsApp-template vanuit een CRM-, ERP- of webshopsysteem versturen met één API-aanroep via MonoChatDe lijst met goedgekeurde WhatsApp-templates met hun variabelenEen template naar een nieuw nummer versturen maakt automatisch de klant aanEén template in meerdere talen verstuurdTemplates met afbeelding-, video-, document- en pdf-headers

Veelgestelde vragen

Heeft WhatsApp Template API een gebruikersinterface?

Nee. Het is een app met alleen een API en drie endpoints: templates weergeven, een template versturen en uploadgegevens voor mediaheaders opvragen.

Wat heb ik nodig voordat ik het kan gebruiken?

Een WhatsApp Business-nummer dat aan MonoChat is gekoppeld en geverifieerd, templates die door Meta zijn goedgekeurd en een API-token onder Profiel › API-tokens.

Wat gebeurt er als de klant antwoordt?

Het gesprek komt zoals elk ander in uw MonoChat-inbox terecht. Elke verzending geeft ook een directe link naar het gesprek terug, en u kunt het per e-mail aan een medewerker toewijzen.

Kan ik versturen naar een nummer dat nog geen klant is?

Ja. Als het telefoonnummer nog geen klant is, wordt de klant aangemaakt met de naam die u meestuurt.

Wat kosten templateberichten?

Elk bericht wordt gefactureerd zoals elk templatebericht dat vanuit MonoChat wordt verzonden. Meta rekent voor templates een prijs per categorie en per land van de ontvanger; gebruik de kostencalculator voor WhatsApp-bulkberichten om een verzending in te schatten.

Gerelateerd

• Session Link
• Bulk Template Message API
• Sjabloonberichten
• MonoStore-apps