WhatsApp Template API

Entwickler-API

Senden Sie genehmigte WhatsApp-Vorlagen aus Ihren eigenen Systemen mit einem API-Aufruf; die Konversation wird danach in MonoChat fortgesetzt.

• WhatsApp
• REST API
• Nur API

Aus dem MonoStore installierenAuf monochat.ai ansehen

Überblick

Mit WhatsApp Template API kann Ihr CRM, ERP, Ihr E-Commerce-Shop oder jedes beliebige Backend über MonoChat eine genehmigte WhatsApp-Vorlagennachricht an einen Kunden senden. Eine einzige Anfrage nennt die WhatsApp-Nummer, von der gesendet wird, die Telefonnummer des Kunden, die Vorlage und ihre Variablen.

Antwortet der Kunde, landet die Konversation wie jede andere in Ihrem MonoChat-Posteingang. Die App hat keine eigenen Seiten: Alles läuft über drei API-Endpunkte.

Highlights

• Ein API-Aufruf. Senden Sie eine Vorlage nach Name und Sprache, mit Variablen für Header, Body, Schaltflächen und Karussell, befüllt aus Ihren Daten.
• Direkt in den Chat. Jeder Versand liefert die ID der Konversation und einen direkten Link dorthin in MonoChat zurück.
• Neue Kunden willkommen. Ist die Telefonnummer noch kein Kunde, wird der Kunde mit dem von Ihnen gesendeten Namen angelegt.

Installation und Einrichtung

1. Verbinden Sie Ihre WhatsApp-Business-Nummer mit MonoChat und stellen Sie sicher, dass sie verifiziert ist und von Meta genehmigte Vorlagen hat.
2. Installieren Sie WhatsApp Template API unter Einstellungen › MonoStore › Apps oder öffnen Sie den Installationslink app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Ohne MonoChat-Konto können Sie sich über den Link zuerst registrieren; die App wird dann für Sie installiert.
3. Erstellen Sie unter Profil › API-Token ein API-Token. Das Token wird nur einmal angezeigt, kopieren Sie es also sofort.
4. Rufen Sie template/list.js auf, um Ihre genehmigten Vorlagen und deren Variablen zu sehen.
5. Rufen Sie template/send.js mit der Nummer des Kunden und den Variablenwerten auf, um Ihre erste Vorlage zu senden.

hinweis

• Jede Nachricht wird wie jede andere von MonoChat gesendete Vorlagennachricht abgerechnet.
• Medien-URLs müssen erreichbar bleiben, bis WhatsApp die Datei abgerufen hat.
• Senden Sie an Kunden, die zugestimmt haben, von Ihnen zu hören: WhatsApp kann Nummern einschränken, deren Nachrichten blockiert oder gemeldet werden.

Funktionen

Vorlagen auflisten

Die genehmigten Vorlagen einer WhatsApp-Nummer mit Sprache, Kategorie, Status und Variablen, damit Ihr System weiß, was es senden kann.

Vorlage senden

Nach Vorlagenname und Sprache, mit Variablen für Header, Body, Schaltflächen und Karussell. Ein fehlender Wert stoppt den Versand, sodass nichts halb Ausgefülltes beim Kunden ankommt.

Einem Mitarbeiter zuweisen

Geben Sie die E-Mail-Adresse eines Mitarbeiters an, und die Konversation wird auf seinen Namen eröffnet.

Medien-Header

Holen Sie sich kurzlebige Upload-Zugangsdaten, legen Sie ein Bild, Video oder Dokument im Speicher von MonoChat ab und verwenden Sie dessen URL als Header der Vorlage.

Link zur Konversation

Jeder Versand liefert die Session-ID, die Nachrichten-ID und einen Link zurück, der die Konversation in MonoChat öffnet.

Klare Fehlermeldungen

Ein fehlgeschlagener Aufruf sagt, was schiefgelaufen ist, zum Beispiel „Channel not found“ oder „Variable missing“.

Bevor Sie beginnen

• Ihre WhatsApp-Business-Nummer ist mit MonoChat verbunden und verifiziert. Siehe Kanäle.
• Die Vorlagen, die Sie senden möchten, sind von Meta genehmigt. Mit Vorlagen schreiben Sie zuerst oder erreichen einen Kunden außerhalb des 24-Stunden-Fensters. Siehe Vorlagennachrichten.
• Sie haben ein API-Token unter Profil › API-Token. Siehe API-Token.
• Sie kennen Ihren Tenant-Slug: den Teil nach /tenants/ in Ihrer MonoChat-Adresse. In https://app.monochat.ai/tenants/mybusiness ist der Slug mybusiness.

API-Referenz

Die App hat keine eigenen Seiten. Alles läuft über drei Endpunkte, jeweils ein POST mit einem JSON-Body:

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

Endpunkt	Was er tut
template/list.js	Listet die Vorlagen einer Ihrer WhatsApp-Nummern mit ihren Variablen auf.
template/send.js	Sendet eine Vorlage an einen Kunden und liefert einen Link zur Konversation zurück.
upload/get-token.js	Liefert kurzlebige Upload-Zugangsdaten für ein Header-Bild, -Video oder -Dokument.

Telefonnummern werden immer mit Ländervorwahl und ohne + geschrieben, zum Beispiel 905334445566. Ein erfolgreicher Aufruf antwortet mit 200 und den Daten des Endpunkts unter result.

1. Vorlagen auflisten

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

Listet jede Vorlage der angegebenen WhatsApp-Business-Nummer auf: Name, Sprachcode, Kategorie, Komponenten (Header, Body, Footer, Schaltflächen), Variablentypen und Genehmigungsstatus.

Feld	Pflicht	Beschreibung
phoneNumber	ja	Ihre WhatsApp-Business-Nummer in MonoChat, mit Ländervorwahl, ohne +.
options	nein	Seitenumbruch und Filter, zum Beispiel { "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"
}

Antwort (gekürzt):

{
  "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 }
    }
  }
}

So lesen Sie die Antwort:

• name: der Systemname, unter dem Sie die Vorlage senden.
• languageCode: die Sprache, in der sie gesendet wird.
• category: die WhatsApp-Kategorie (MARKETING, UTILITY, AUTHENTICATION).
• components: die Teile, aus denen die Vorlage aufgebaut ist.

Komponente	Inhalt	Beschreibung
HEADER	IMAGE, VIDEO, DOCUMENT oder Text	Bei Medien wird das format angegeben; Variablen erscheinen unter variables.
BODY	Text mit Variablen	Der Nachrichtentext mit Platzhaltern wie {{1}}, {{2}}.
FOOTER	Text	Hat meist keine Variablen.
BUTTONS	URL, Schnellantwort …	Schaltflächentexte und ihre Variablen, falls vorhanden.

Die obige Beispielvorlage braucht ein Bild für den Header und zwei Texte für den Body (Kundenname und Produktname). Der Footer ist fest („Teşekkürler“) und es gibt keine Schaltflächen.

2. Vorlage senden

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

Sendet eine genehmigte Vorlage an einen Kunden. Ist die Telefonnummer noch kein Kunde, wird der Kunde angelegt; die Konversation wird eröffnet (oder wiederverwendet) und die Vorlage darin gesendet.

Feld	Pflicht	Beschreibung
phoneNumber	ja	Die WhatsApp-Business-Nummer, von der gesendet wird. Sie muss mit MonoChat verbunden und verifiziert sein.
templateMessageName	ja	Der name der Vorlage, genau so, wie ihn die Liste zurückgibt.
languageCode	ja	Die Sprache der Vorlage, wie die Liste sie zurückgibt (zum Beispiel tr-TR).
customerPhoneNumber	ja	Die WhatsApp-Nummer des Kunden.
variables	wenn die Vorlage welche hat	Die Werte der Variablen der Vorlage (siehe unten).
customerFirstName, customerLastName	nein	Wird verwendet, wenn der Kunde in MonoChat neu ist.
agentEmailAddress	nein	Weist die Konversation dem Mitarbeiter mit dieser E-Mail-Adresse zu.

Variablen. Jedes Element des Arrays variables hat einen type und eine Liste von parameters, angegeben in der Reihenfolge der Platzhalter der Vorlage:

type	parameters
HEADER	Die Textvariable des Headers oder die öffentliche URL des Header-Bilds, -Videos oder -Dokuments.
BODY	Die {{1}}, {{2}}, … des Bodys in der Reihenfolge.
BUTTONS	Ein Wert für jede Schaltfläche, die eine Variable hat (zum Beispiel der dynamische Teil einer URL-Schaltfläche oder ein Gutscheincode), in der Reihenfolge der Schaltflächen.
CAROUSEL	Statt parameters ein Array cards mit einem Eintrag pro Karussellkarte, jeweils mit eigenen components.

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

Ein fehlender Wert stoppt den Versand mit Variable missing, sodass nichts halb Ausgefülltes beim Kunden ankommt. FOOTER hat selten Variablen.

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"] }
  ]
}

Antwort:

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

• url: öffnet die Konversation in MonoChat, für angemeldete Personen, die sie sehen dürfen.
• sessionId: die ID der Konversation.
• messageId: die ID der Nachricht in MonoChat. Zustell- und Lesestatus erscheinen im Chat wie bei jeder anderen Nachricht.

Medien in Vorlagen. WhatsApp lädt Header-Medien von der URL herunter, die Sie angeben; die URL muss daher gültig und öffentlich erreichbar sein. Links, die eine Anmeldung erfordern, funktionieren nicht. Wenn Sie die Datei mit upload/get-token.js hochgeladen haben, verwenden Sie die aus dieser Antwort gebildete URL der Datei.

3. Medien für einen Header hochladen

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

Ist der Header einer Vorlage ein Bild, Video oder Dokument, braucht die Datei eine öffentliche Adresse, von der WhatsApp sie herunterladen kann. Dieser Endpunkt gibt Ihnen eine kurzlebige Berechtigung, die Datei im Speicher von MonoChat abzulegen.

Feld	Pflicht	Beschreibung
fileName	ja	Der Dateiname mit Endung, zum Beispiel product.jpg oder promo.pdf.

Dateien werden immer im Ordner chat-assets Ihres Workspace gespeichert; ältere Beispiele, die ein Feld key senden, funktionieren weiterhin, der Wert wird nicht benötigt.

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

{
  "fileName": "product.jpg"
}

Die Antwort sagt Ihnen, wohin die Datei gehört, und liefert die Zugangsdaten dafür:

Feld	Beschreibung
bucket, region, path	Wohin die Datei kommt.
temporaryCredentials	Nur-Upload-Zugangsdaten für genau diesen Pfad, 15 Minuten gültig.
baseUrl	Die öffentliche Adresse des Speichers. Die URL der Datei ist baseUrl + / + path.

Laden Sie die Datei sofort mit einem beliebigen S3-Client mit diesen Zugangsdaten hoch und übergeben Sie ihre URL dann beim Senden der Vorlage als HEADER-Parameter. Sehr große Dateien oder von WhatsApp nicht unterstützte Formate (es akzeptiert gängige Bild-, Video- und PDF-Formate) schlagen fehl.

Beispiel: eine Vorlage mit Bild-Header

Angenommen, Sie haben eine genehmigte Vorlage new_product_announcement mit einem Bild-Header und zwei Body-Variablen (Kundenname und Produktname) und möchten sie an einen Kunden senden.

1. Vorlagen auflisten. Rufen Sie template/list.js mit Ihrer WhatsApp-Nummer auf und suchen Sie new_product_announcement. Ihre Komponenten zeigen eine IMAGE-Variable im Header und zwei TEXT-Variablen im Body.
2. Bild hochladen. Rufen Sie upload/get-token.js mit { "fileName": "urun.jpg" } auf, laden Sie die Datei mit den zurückgegebenen Zugangsdaten hoch und bilden Sie ihre URL aus baseUrl und path.
3. Vorlage senden. Rufen Sie template/send.js mit der URL der Datei als HEADER-Parameter und ["Ayşe", "XYZ Telefon"] als BODY-Parameter auf ({{1}} → Ayşe, {{2}} → XYZ Telefon). Hätte die Vorlage Schaltflächenvariablen, würden Sie auf dieselbe Weise ein BUTTONS-Element hinzufügen.
4. Chat öffnen. Die url der Antwort öffnet die Konversation; wenn der Kunde antwortet, wird sie in Ihrem MonoChat-Posteingang fortgesetzt.

Fehler

Ein fehlgeschlagener Aufruf antwortet mit einem Fehlerstatus und einer Meldung, die sagt, was schiefgelaufen ist. Protokollieren Sie diese Meldungen in Ihrem System und zeigen Sie Ihren Nutzern bei Bedarf eine verständliche Meldung an.

Meldung	Ursache
phoneNumber field is required	template/list.js wurde ohne phoneNumber aufgerufen.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Ein Pflichtfeld von template/send.js fehlt.
Channel not found	Die phoneNumber ist keine WhatsApp-Nummer Ihres Workspace.
Channel is not verified	Die WhatsApp-Nummer ist verbunden, aber nicht verifiziert.
Template message not found	Auf der Nummer gibt es keine genehmigte Vorlage mit diesem Namen und dieser Sprache. Prüfen Sie die Schreibweise und den languageCode.
Template message is not approved	Die Vorlage existiert, ist aber nicht von Meta genehmigt.
Variable missing: …	variables passt nicht zur Vorlage, zum Beispiel braucht die Vorlage zwei Body-Werte und Sie haben einen gesendet.
Agent user not found	Es gibt keinen Mitarbeiter mit der E-Mail-Adresse in agentEmailAddress.
Customer Channel not found	Die WhatsApp-Identität des Kunden konnte nicht angelegt oder gefunden werden.

HTTP-Statuscodes, die Sie sehen können:

• 401 Unauthorized: Der Header Authorization: Bearer <API_TOKEN> fehlt, oder das Token ist falsch oder abgelaufen. Verwenden Sie ein gültiges Token aus Ihrem Konto.
• 403 Forbidden: Das Token hat keinen Zugriff auf diesen Workspace oder diese App, zum Beispiel wegen eines falschen Tenant-Slugs.
• 404 Not Found: Die Endpunkt-Adresse ist falsch. Prüfen Sie den vollständigen Pfad /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: ein unerwartetes Problem in MonoChat oder beim WhatsApp-Anbieter oder eine Ablehnung seitens WhatsApp (die Nummer ist nicht auf WhatsApp, der Kunde hat Sie blockiert, Qualitäts- oder Ratenlimits). Versuchen Sie es später erneut und wenden Sie sich an den MonoChat-Support, wenn das Problem bestehen bleibt.

Screenshots

Eine genehmigte WhatsApp-Vorlage aus einem CRM-, ERP- oder E-Commerce-System mit einem API-Aufruf über MonoChat sendenDie Liste der genehmigten WhatsApp-Vorlagen mit ihren VariablenBeim Senden einer Vorlage an eine neue Nummer wird der Kunde automatisch angelegtEine Vorlage, in mehreren Sprachen gesendetVorlagen mit Bild-, Video-, Dokument- und PDF-Headern

FAQ

Hat WhatsApp Template API eine Benutzeroberfläche?

Nein. Es ist eine reine API-App mit drei Endpunkten: Vorlagen auflisten, eine Vorlage senden und Upload-Zugangsdaten für Medien-Header abrufen.

Was brauche ich, bevor ich sie nutzen kann?

Eine mit MonoChat verbundene und verifizierte WhatsApp-Business-Nummer, von Meta genehmigte Vorlagen und ein API-Token unter Profil › API-Token.

Was passiert, wenn der Kunde antwortet?

Die Konversation landet wie jede andere in Ihrem MonoChat-Posteingang. Jeder Versand liefert außerdem einen direkten Link zur Konversation zurück, und Sie können sie per E-Mail einem Mitarbeiter zuweisen.

Kann ich an eine Nummer senden, die noch kein Kunde ist?

Ja. Ist die Telefonnummer noch kein Kunde, wird der Kunde mit dem von Ihnen gesendeten Namen angelegt.

Was kosten Vorlagennachrichten?

Jede Nachricht wird wie jede andere von MonoChat gesendete Vorlagennachricht abgerechnet. Meta berechnet Vorlagen nach Kategorie und Land des Empfängers; nutzen Sie den WhatsApp-Massenversand-Kostenrechner, um einen Versand abzuschätzen.

Verwandte Themen

• Session Link
• Bulk Template Message API
• Vorlagennachrichten
• MonoStore-Apps