Bulk Template Message API – Dokumentation

Mit dieser API können Sie Vorlagennachrichten über den WhatsApp-Kanal gleichzeitig an mehrere Empfänger senden.

Der Nachrichtenversand wird asynchron verarbeitet; die API-Anfrage liefert sofort eine bulkMessageId zurück, während die Nachrichten in eine Warteschlange gestellt und im Hintergrund verarbeitet werden.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js

Hauptfunktionen

Senden Sie Massen-Vorlagennachrichten an 1–5.000 Empfänger in einer einzigen Anfrage
Personalisierte Variablen für jeden Empfänger (HEADER, BODY, BUTTONS, CAROUSEL)
Gemeinsames defaultPayload für alle Empfänger mit dem Zusammenführen empfängerspezifischer payload-Daten (isMerge)
Geplanter Versand (scheduleAt)
Empfänger über username (Telefonnummer), userId oder sessionId angeben
Mehrere Nachrichten an denselben Benutzer in einer einzigen Massenanfrage senden
Optionale referenceId zum Abgleich von Datensätzen mit externen Systemen
Konversationen nach dem Senden automatisch einem Benutzer oder einer Arbeitsgruppe zuweisen (action)

warnung

Diese API kann nur Vorlagen senden, die von Meta genehmigt wurden.

Vorlagenname und Sprachcode müssen genau mit der im Meta Business Manager registrierten Vorlage übereinstimmen.

Anfrageparameter

Parameter der obersten Ebene

Parameter	Typ	Pflicht	Beschreibung
`channelUsername`	string	Ja	WhatsApp-Kanalnummer, von der die Nachricht gesendet wird (z. B. `"908506669933"`)
`connectorBrand`	string	Ja	Marke des Kanal-Connectors. Derzeit unterstützter Wert: `"whatsapp"`
`title`	string	Nein	Kampagnentitel. Wird im Dashboard angezeigt. Standardwert: `"-"`
`scheduleAt`	string (ISO 8601)	Nein	Geplantes Versanddatum mit Uhrzeit (z. B. `"2026-06-10T10:00:00.000Z"`). Wenn weggelassen, werden die Nachrichten sofort gesendet.
`defaultPayload`	object	Bedingt*	Standard-Vorlagen-Payload, der für alle Empfänger gilt. Erforderlich, wenn ein Empfänger kein eigenes `payload` angibt.
`recipients`	array	Ja	Empfängerliste. Mindestens 1, höchstens 5.000 Empfänger.
`action`	object	Nein	Aktion, die nach dem Senden auf die Konversation angewendet wird. `assign-to-user` oder `assign-to-workgroup`.

*Wenn jeder Empfänger ein eigenes payload angibt, ist defaultPayload optional.

Empfängerstruktur

Für jeden Empfänger muss genau eines von username, userId oder sessionId angegeben werden. Mehrere Kennungen können nicht gemeinsam verwendet werden, und fehlen alle, führt das zu einem Fehler.

Um mehrere Nachrichten an denselben Benutzer in einer einzigen Massenanfrage zu senden, fügen Sie dieselbe Kennung mehrfach zur Empfängerliste hinzu.

Feld	Typ	Beschreibung
`username`	string	Telefonnummer des Empfängers (z. B. `"905554443322"`). Existiert der Benutzer im System noch nicht, wird er automatisch angelegt.
`userId`	string	ID eines vorhandenen Benutzers im System.
`sessionId`	string	ID einer vorhandenen Konversationssitzung im System.
`referenceId`	string	Optionale Referenz-ID (max. 256 Zeichen) zum Abgleich mit Datensätzen externer Systeme (CRM, Bestellung, Ticket usw.). Muss, wenn angegeben, innerhalb der Massenanfrage eindeutig sein.
`payload`	object	Empfängerspezifischer Vorlagen-Payload (optional). Bei `isMerge: true` wird er mit `defaultPayload` zusammengeführt.
`isMerge`	boolean	Überschreibt das Zusammenführungsverhalten für diesen Empfänger (optional). Wenn weggelassen, wird `defaultPayload.isMerge` verwendet.

Aktionsstruktur

Feld	Typ	Beschreibung
`action.key`	string	`"assign-to-user"` weist die Konversation einem bestimmten Mitarbeiter zu; `"assign-to-workgroup"` weist sie einer Arbeitsgruppe zu.
`action.value`	string	ID des Ziel-Benutzers oder der Ziel-Arbeitsgruppe.

Struktur des Vorlagen-Payloads

defaultPayload und das empfängerspezifische payload haben dieselbe Struktur. Für Vorlagennachrichten muss type: "template" angegeben werden.

{
  "type": "template",
  "template": {
    "templateName": "order_confirmation",
    "languageCode": "tr-TR",
    "variables": []
  },
  "isMerge": true
}

Feld	Typ	Pflicht	Beschreibung
`type`	string	Ja	Payload-Typ. Für Vorlagennachrichten: `"template"`
`template.templateName`	string	Ja*	In Meta registrierter Vorlagenname. In Empfänger-Payloads optional, wenn `isMerge: true` verwendet wird (wird vom Standard geerbt).
`template.languageCode`	string	Nein	Sprachcode der Vorlage (z. B. `"tr"`, `"en"`, `"tr-TR"`, `"en-US"`). Muss genau mit der in Meta registrierten Sprache übereinstimmen.
`template.variables`	array	Nein	Liste der Variablen, die auf die Vorlagenkomponenten angewendet werden. Details unten.
`isMerge`	boolean	Nein	`true`: Der Empfänger-Payload wird tief mit `defaultPayload` zusammengeführt. `false` oder weggelassen: Der Empfänger-Payload ersetzt `defaultPayload` vollständig.

isMerge-Verhalten

Wenn defaultPayload.isMerge: true gilt und der Empfänger ein eigenes payload angibt, wird eine tiefe Zusammenführung angewendet.
Bei der tiefen Zusammenführung kann der Empfänger nur variables angeben; templateName und languageCode werden vom Standard-Payload geerbt.
Das Feld isMerge des Empfängers überschreibt defaultPayload.isMerge.
Gibt ein Empfänger kein payload an, wird immer defaultPayload verwendet.

Variablenstruktur

Jedes Element im Array variables entspricht einer Vorlagenkomponente. Ein Komponententyp (type) darf im Array nur einmal vorkommen.

type	Beschreibung	parameters	cards
`"HEADER"`	Header-Komponente der Vorlage. Textvariable oder Medien-URL (Bild, Video, Dokument)	Ja	—
`"BODY"`	Textvariablen im Body der Vorlage	Ja	—
`"BUTTONS"`	Variablen für dynamische URL-Suffixe von Schaltflächen	Ja	—
`"CAROUSEL"`	Kartenkomponenten für Karussell-Vorlagen	—	Ja

Parameterformate

Das Feld parameters kann in drei verschiedenen Formaten angegeben werden:

// Format 1: Array (indexbasiert) — für Platzhalter wie {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]

// Format 2: Objekt (numerische Schlüssel) — alternative Darstellung für {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }

// Format 3: Objekt (benannte Schlüssel) — für Platzhalter wie {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }

Welches Format soll ich verwenden?

Wenn Ihre Meta-Vorlage Platzhalter wie {{1}}, {{2}} verwendet, nutzen Sie entweder das Array-Format oder das Objektformat mit numerischen Schlüsseln.
Wenn Ihre Vorlage benannte Platzhalter wie {{firstName}} oder {{orderTotal}} verwendet, nutzen Sie das Objektformat mit benannten Schlüsseln.
Bei Arrays kommt es auf die Reihenfolge an: Das erste Element entspricht {{1}}, das zweite {{2}} und so weiter.

HEADER-Komponente

Verwenden Sie die Komponente HEADER, wenn der Header der Vorlage Medien (Bild, Video, Dokument) oder dynamischen Text enthält.

// Medien-Header (Bild-URL)
{
  "type": "HEADER",
  "parameters": ["https://example.com/product-image.jpg"]
}

// Textvariable im Header
{
  "type": "HEADER",
  "parameters": ["Special Campaign"]
}

BODY-Komponente

Wird für dynamische Textvariablen im Body der Vorlage verwendet.

// Array-Format — wenn die Vorlage {{1}}, {{2}}, {{3}} verwendet
{
  "type": "BODY",
  "parameters": ["John", "ORD-12345", "150.00 USD"]
}

// Benanntes Format — wenn die Vorlage {{name}}, {{orderAmount}} verwendet
{
  "type": "BODY",
  "parameters": {
    "name": "John",
    "orderAmount": "150.00 USD"
  }
}

BUTTONS-Komponente

Wird für Schaltflächen mit dynamischen URL-Suffixen verwendet. Enthält die Vorlage mehrere URL-Schaltflächen, werden nur Schaltflächen mit Variablen fortlaufend indiziert (Schaltflächen ohne Variablen und FLOW-Schaltflächen werden ignoriert).

// Variable für den Suffix einer einzelnen URL-Schaltfläche
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345"]
}

// Variablen für mehrere URL-Schaltflächen-Suffixe (erste URL-Schaltfläche, zweite URL-Schaltfläche)
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345", "cancel/ORD-12345"]
}

CAROUSEL-Komponente

Bei Karussell-Vorlagen werden die Komponentenvariablen für jede Karte separat definiert.

{
  "type": "CAROUSEL",
  "cards": [
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card1.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product A", "99.00 USD"]
        }
      ]
    },
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card2.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product B", "149.00 USD"]
        }
      ]
    }
  ]
}

warnung

Die Länge des Arrays cards muss genau der Anzahl der in der Vorlage definierten Karten entsprechen.

Beispiele

1. Einfache Vorlage – keine Variablen, gleicher Inhalt für alle Empfänger

Dies ist der einfachste Weg, eine statische Vorlage ohne Variablen an mehrere Empfänger zu senden.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }, { "username": "905554443303" }]
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [
    { "username": "905554443301" },
    { "username": "905554443302" },
    { "username": "905554443303" }
  ]
}'

tipp

Über username angegebene Empfänger werden automatisch angelegt, wenn sie im System noch nicht existieren
Alle Empfänger verwenden dasselbe defaultPayload; empfängerspezifische Daten sind nicht erforderlich
Wenn isMerge nicht angegeben ist, verwendet jeder Empfänger direkt das defaultPayload

2. Vorlage mit gemeinsamen Body-Variablen

Dieselbe Vorlage wird mit identischen Variablenwerten an alle Empfänger gesendet. Die Vorlage enthält Platzhalter wie {{1}} und {{2}}.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Summer Campaign",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "promo_notification",
      "languageCode": "tr-TR",
      "variables": [
        {
          "type": "BODY",
          "parameters": ["30%", "July 31, 2026"]
        }
      ]
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }]
}

tipp

In diesem Beispiel könnte der Body der Vorlage etwa lauten: „Genießen Sie in unserer Kampagne {{1}} Rabatt! Angebot gültig bis {{2}}.“
parameters[0] ersetzt {{1}}, während parameters[1] {{2}} ersetzt

3. Personalisierte Vorlage – Variablen pro Empfänger mit isMerge

Für jeden Empfänger werden unterschiedliche Variablenwerte verwendet. Setzen Sie isMerge: true im defaultPayload, müssen Empfänger nur variables angeben; templateName und languageCode werden vom Standard-Payload geerbt.

In diesem Beispiel enthält die Vorlage sowohl einen Medien-Header als auch personalisierte Body-Variablen.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Personal Order Notification",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "order_confirmation",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-a.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Ahmet", "ORD-001", "150.00 TRY"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-b.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Fatma", "ORD-002", "289.00 TRY"]
            }
          ]
        }
      }
    }
  ]
}

tipp

Dank isMerge: true muss templateName nicht in jedem Empfänger-Payload wiederholt werden
Das Array variables jedes Empfängers ist vollständig unabhängig
Die Medien-URL des Headers muss öffentlich erreichbar sein
Wird type im Empfänger-Payload weggelassen, wird defaultPayload.type geerbt

4. Variable einer URL-Schaltfläche

Verwenden Sie die Komponente BUTTONS, wenn die Vorlage eine Schaltfläche mit dynamischem URL-Suffix enthält, zum Beispiel eine Sendungsnummer, die an die Basis-URL https://example.com/track/ angehängt wird.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Shipment Tracking Notification",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "shipment_tracking",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Ahmet", "TK-98765"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-98765"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Recep", "TK-12345"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-12345"]
            }
          ]
        }
      }
    }
  ]
}

tipp

BUTTONS-Parameter werden anhand der Reihenfolge der Schaltflächen zugeordnet, die Variablen enthalten
FLOW-Schaltflächen und Schaltflächen ohne Variablen werden ignoriert; die Indizierung gilt nur für dynamische URL-Schaltflächen
Lautet die URL der Schaltfläche in der Vorlage https://example.com/track/{{1}}, ersetzt parameters[0] den Platzhalter {{1}}

5. Geplanter Versand

Planen Sie den Versand einer Nachricht zu einem zukünftigen Datum und einer zukünftigen Uhrzeit. scheduleAt muss als UTC-Zeitstempel nach ISO 8601 angegeben werden.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Morning Campaign Message",
  "scheduleAt": "2026-06-10T07:00:00.000Z",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "morning_campaign",
      "languageCode": "en-US"
    },
    "isMerge": true
  },
  "action": {
    "key": "assign-to-workgroup",
    "value": "WORKGROUP_ID"
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Ahmet", "discountRate": "25" }
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Zeynep", "discountRate": "40" }
            }
          ]
        }
      }
    }
  ]
}

tipp

scheduleAt muss in der Zeitzone UTC angegeben werden (z. B. für 10:00 Uhr türkischer Zeit 07:00:00.000Z verwenden)
Dieses Beispiel verwendet das Format mit benannten Parametern; die Vorlage sollte Platzhalter wie {{name}} und {{discountRate}} enthalten
Mit action werden Konversationen, die durch den Nachrichtenversand entstehen, automatisch der angegebenen Arbeitsgruppe zugewiesen

Antwort

Eine erfolgreiche Anfrage liefert eine bulkMessageId zurück, mit der sich der Versandvorgang verfolgen lässt:

{
  "bulkMessageId": "abc123xyz789"
}

Fehlerantworten

Status	Beschreibung
`Channel not found`	Es wurde kein verifizierter Kanal gefunden, der zu `channelUsername` und `connectorBrand` passt
`Channel is not verified`	Der passende Kanal existiert, wurde aber noch nicht verifiziert
`invalidRequest`	Für einen Empfänger wurden mehrere Kennungen angegeben oder ein erforderlicher Payload fehlt
`channelNotFound`	Es wurde kein aktiver Kanal gefunden, der zur angegebenen `channelId` passt
`schema-error`	Ein Feld im Anfrage-Body hat die Schemaprüfung nicht bestanden (fehlendes Pflichtfeld, falscher Typ oder nicht unterstützter Wert)

Mit der zurückgegebenen bulkMessageId lassen sich über die folgenden Endpunkte Versandstatistiken abfragen und der Versandvorgang stoppen.

Stats – Versandstatistiken

Ruft den aktuellen Versandstatus einer Massennachricht ab. Liefert die Anzahl ausstehender, erfolgreicher, fehlgeschlagener und abgebrochener Datensätze.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stats.js

Anfrageparameter

Parameter	Typ	Pflicht	Beschreibung
`bulkMessageId`	string	Ja	ID der zu verfolgenden Massennachricht (von `createBulkPerRecipient` zurückgegeben)

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Antwort

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "title": "Campaign Title",
    "channelUsername": "908506669933",
    "connectorBrand": "whatsapp",
    "connectorSlug": "whatsapp-cloud",
    "payload": {
      "recipientCount": 100,
      "defaultPayloadType": "template",
      "jobId": "job_abc123"
    },
    "schedule": {
      "date": "2026-06-10T07:00:00.000Z",
      "type": "later"
    },
    "createdAt": "2026-06-08T10:00:00.000Z",
    "updatedAt": "2026-06-08T10:30:00.000Z"
  },
  "stats": {
    "pending": 45,
    "success": 42,
    "failed": 3,
    "cancelled": 10,
    "total": 100
  }
}

Stats-Felder

Feld	Typ	Beschreibung
`stats.pending`	number	Anzahl der Datensätze, die noch in der Warteschlange warten
`stats.success`	number	Anzahl der Datensätze, die erfolgreich für den Versand verarbeitet wurden
`stats.failed`	number	Anzahl der Datensätze, bei denen ein Zustellfehler aufgetreten ist
`stats.cancelled`	number	Anzahl der abgebrochenen Datensätze
`stats.total`	number	Gesamtzahl der Datensätze (`pending + success + failed + cancelled`)

hinweis

stats.success zeigt an, dass die Nachricht vom System erfolgreich übergeben wurde. Es ist keine Garantie dafür, dass Meta die Nachricht an den Empfänger zugestellt hat. Spätere Statusaktualisierungen von Meta (wie delivered, read oder failed) wirken sich nicht auf diesen Zähler aus und werden hier nicht abgebildet.

Stats und Message Stats im Vergleich

Endpunkt stats: zeigt den Status des Versandauftrags (pending, success, failed, cancelled)
Endpunkt message-stats: zeigt den tatsächlichen Nachrichtenstatus (pending, sending, sent, delivered, read, error usw.)
Ein Auftrag kann erfolgreich sein, obwohl die Nachricht noch nicht zugestellt oder gelesen wurde

Referenz-ID

Die referenceId ist ein optionales Feld, mit dem Sie Versanddatensätze zu Nachverfolgungszwecken einer ID aus Ihrem eigenen System zuordnen können (z. B. Bestellnummer, Ticket-ID).

Wenn angegeben, muss sie innerhalb der Massenanfrage eindeutig sein (max. 256 Zeichen).

Wichtig

Für die Nutzung nicht erforderlich
Darf innerhalb derselben Massennachricht nicht doppelt vorkommen
Kann in verschiedenen Massennachrichten erneut verwendet werden

Message Stats – WhatsApp-Nachrichtenstatus

Ruft die Statistiken zum Nachrichtenstatus einer Massennachricht ab. Anders als der Endpunkt stats zeigt dieser für jeden Datensatz den tatsächlichen message.status statt des Auftragsstatus.

Mögliche Nachrichtenstatus: pending, sending, sent, delivered, read, deleted, warning, error, unknown, not-sended

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/message-stats.js

Anfrageparameter

Parameter	Typ	Pflicht	Beschreibung
`bulkMessageId`	string	Ja	ID der abzufragenden Massennachricht

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/message-stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Antwort

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "type": "perRecipient",
    "title": "Campaign Title"
  },
  "messageStats": {
    "pending": 5,
    "sending": 2,
    "sent": 10,
    "delivered": 45,
    "read": 30,
    "deleted": 2,
    "warning": 1,
    "error": 3,
    "unknown": 0,
    "not-sended": 2,
    "no-message": 10,
    "total": 120
  }
}

Message-Stats-Felder

Feld	Typ	Beschreibung
`pending`	number	Noch nicht gesendete Nachrichten
`sending`	number	Nachrichten, die gerade gesendet werden
`sent`	number	An WhatsApp übergebene, noch nicht zugestellte Nachrichten
`delivered`	number	Auf dem Telefon des Empfängers zugestellte Nachrichten
`read`	number	Vom Empfänger gelesene Nachrichten
`deleted`	number	Gelöschte Nachrichten
`warning`	number	Nachrichten mit Warnungen
`error`	number	Nachrichten mit Fehlern
`unknown`	number	Nachrichten mit unbekanntem Status
`not-sended`	number	Nachrichten, die nicht gesendet werden konnten
`no-message`	number	Datensätze, zu denen es noch keine Nachricht gibt (noch in der Warteschlange)
`total`	number	Gesamtzahl der Datensätze

Nutzungstipps

Eine hohe Anzahl bei no-message zeigt an, dass der Versand noch läuft
Die Anzahl bei delivered zeigt die erfolgreiche Zustellung von Nachrichten
Die Anzahl bei read lässt sich nutzen, um die Interaktion mit einer Kampagne zu messen
Sie können diesen Endpunkt regelmäßig abfragen, um den Versand in Echtzeit zu verfolgen

Options-Struktur – Seitenumbruch, Filterung und Sortierung

Der Parameter options, der in den Endpunkten list und list-with-messages verwendet wird, bietet eine einheitliche Struktur für Seitenumbruch, Filterung und Sortierung.

Options-Felder

Feld	Typ	Pflicht	Beschreibung
`pagination`	object	Nein	Einstellungen für den Seitenumbruch
`filtering`	object	Nein	Filterkriterien
`sorting`	object	Nein	Sortiereinstellungen (z. B. `{"createdAt": -1}`)

Struktur des Seitenumbruchs

Feld	Typ	Standard	Beschreibung
`currentPage`	number	1	Abzurufende Seitennummer
`pageItems`	number	50	Anzahl der Datensätze pro Seite (Maximum: 50)

Filterstruktur

Die Filterung erfolgt im MongoDB-Abfrageformat. Sie können nach Datensatzfeldern filtern. Im Endpunkt list-with-messages können Sie außerdem nach Nachrichtenfeldern filtern (z. B. message.status).

// Nach Datensatzstatus filtern
{
  "options": {
    "filtering": {
      "status": "success"
    }
  }
}

// Nach referenceId filtern
{
  "options": {
    "filtering": {
      "referenceId": "ORDER-12345"
    }
  }
}

// Nach Nachrichtenstatus filtern (nur list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// Nach mehreren Status mit $in filtern (MongoDB-Operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// Bestimmte Status mit $nin ausschließen (MongoDB-Operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

Sortierstruktur

Die Sortierung erfolgt im MongoDB-Sortierformat. 1 bedeutet aufsteigend, -1 absteigend.

// Nach Erstellungsdatum absteigend sortieren (neueste zuerst)
{
  "options": {
    "sorting": {
      "createdAt": -1
    }
  }
}

// Nach mehreren Feldern sortieren
{
  "options": {
    "sorting": {
      "status": 1,
      "createdAt": -1
    }
  }
}

Beispiel für die kombinierte Verwendung

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 2,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    },
    "sorting": {
      "createdAt": -1
    }
  }
}

Dieses Beispiel sortiert zugestellte Nachrichten von neu nach alt.

Praktische Tipps

Kombinieren Sie filtering und pagination für gezielte Abfragen
Die Antwort enthält options.pagination.totalCount und options.pagination.totalPages zur Navigation
Der Filter message.status funktioniert nur im Endpunkt list-with-messages

Records – Datensatzdetails und Auflistung

Listet alle Versanddatensätze einer Massennachricht auf. Jeder Datensatz steht für eine einzelne an einen Empfänger gesendete Nachricht.

List – Datensatzliste

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message-records/list.js

Anfrageparameter

Parameter	Typ	Pflicht	Beschreibung
`bulkMessageId`	string	Ja	ID der aufzulistenden Massennachricht
`options`	object	Nein	Optionen für Seitenumbruch, Filterung und Sortierung. Details unter Options-Struktur.

Anfrage – Grundlegende Verwendung

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

Anfrage – Nach bestimmtem Status filtern

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "status": "success"
    }
  }
}

Listet nur erfolgreiche Versanddatensätze auf (record.status = "success").

Antwort

{
  "bulkMessageRecords": [
    {
      "_id": "record_1",
      "bulkMessageId": "abc123xyz789",
      "slug": "my-workspace",
      "userId": "user_123",
      "sessionId": "session_456",
      "messageId": "msg_789",
      "referenceId": "ORDER-12345",
      "status": "success",
      "createdAt": "2026-06-10T10:00:00.000Z"
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {}
  }
}

List With Messages – Liste mit Nachrichtendetails

Bietet dieselben Funktionen wie der Endpunkt list (Seitenumbruch, Filterung, Sortierung). Der einzige Unterschied: Hat ein Datensatz eine messageId, wird auch das zugehörige message-Objekt zurückgegeben. So sehen Sie den Nachrichtenstatus (delivered, read, error usw.) und den Payload in einer einzigen Abfrage.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message-records/list-with-messages.js

Anfrage – Grundlegende Verwendung

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

Anfrage – Nach Nachrichtenstatus filtern

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    }
  }
}

Dieses Beispiel ruft nur Nachrichten mit dem Status „delivered“ ab.

Anfrage – Fehlgeschlagene Nachrichten auflisten

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "error"
    }
  }
}

Dient dazu, Nachrichten zu prüfen, bei denen Zustellfehler aufgetreten sind.

Antwort

{
  "bulkMessageRecords": [
    {
      "_id": "record_1",
      "bulkMessageId": "abc123xyz789",
      "userId": "user_123",
      "messageId": "msg_789",
      "referenceId": "ORDER-12345",
      "status": "success",
      "message": {
        "_id": "msg_789",
        "status": "delivered",
        "payload": {
          "type": "template",
          "template": {
            "templateName": "order_notification"
          }
        },
        "createdAt": "2026-06-10T10:01:00.000Z",
        "deliveredAt": "2026-06-10T10:01:05.000Z"
      }
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {}
  }
}

Datensatzfelder

Feld	Typ	Beschreibung
`_id`	string	Datensatz-ID
`bulkMessageId`	string	ID der Massennachricht, zu der dieser Datensatz gehört
`userId`	string	Benutzer-ID des Empfängers
`sessionId`	string	ID der Konversationssitzung
`messageId`	string	ID der gesendeten Nachricht (null, wenn noch nicht gesendet)
`referenceId`	string	Optionale Referenz-ID (falls angegeben)
`status`	string	Datensatzstatus: `pending`, `success`, `failed`, `cancelled`
`message`	object	Nachrichtendetails (nur bei list-with-messages)

Vergleich: list und list-with-messages

Merkmal	list	list-with-messages
Seitenumbruch	Ja	Ja
Filterung	Ja (nur Datensatzfelder)	Ja (Datensatz- und Nachrichtenfelder)
Nachrichtenobjekt	Nein	Ja (wenn messageId vorhanden ist)
Leistung	Schnell	Mittel (führt JOIN aus)
Filter message.status	Nicht verfügbar	Verfügbar

Anwendungsszenarien

list: alle Datensätze schnell auflisten, nach referenceId filtern, Datensatzstatus prüfen
list-with-messages: WhatsApp-Nachrichtenstatus (delivered, read) ansehen, Nachrichten-Payloads prüfen
Filterbeispiele:
{"status": "failed"} — fehlgeschlagene Versanddatensätze
{"referenceId": "ORDER-123"} — bestimmte Referenz-ID
{"message.status": "delivered"} — zugestellte Nachrichten (nur list-with-messages)
{"message.status": "read"} — gelesene Nachrichten (nur list-with-messages)
{"message.status": "error"} — Nachrichten mit Fehlern (nur list-with-messages)
{"message.status": {"$in": ["delivered", "read"]}} — Nachrichten, die zugestellt oder gelesen wurden (nur list-with-messages)
{"message.status": {"$nin": ["error", "not-sended"]}} — Nachrichten ohne Fehler und nicht gesendete (nur list-with-messages)
{"status": {"$in": ["success", "pending"]}} — Datensätze, die erfolgreich oder ausstehend sind

Hinweise zu Leistung und Nutzung

Der Endpunkt list ist schneller; bevorzugen Sie ihn für allgemeine Statusprüfungen
Verwenden Sie list-with-messages, wenn Nachrichtendetails benötigt werden
Die maximale Anzahl Datensätze pro Seite (pageItems) beträgt 50; ohne Angabe gilt 50
Der Filter message.status funktioniert nur in list-with-messages
Datensätze mit messageId null haben message-Objekte mit dem Wert null

Stop – Versand abbrechen

Stoppt einen laufenden Massenversand. Der Auftrag in der Warteschlange wird abgebrochen, und alle Datensätze mit dem Status pending wechseln zu cancelled. Datensätze, die bereits als success oder failed verarbeitet wurden, sind nicht betroffen.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stop.js

warnung

Diese Aktion kann nicht rückgängig gemacht werden. Ein gestoppter Versand kann nicht fortgesetzt werden.

Anfrageparameter

Parameter	Typ	Pflicht	Beschreibung
`bulkMessageId`	string	Ja	ID der zu stoppenden Massennachricht

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stop.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Antwort

Bei einer erfolgreichen Anfrage ist der Antwort-Body leer. Ein HTTP-Status 200 zeigt an, dass der Vorgang erfolgreich abgeschlossen wurde.

{}

tipp

Es können nur Massennachrichten gestoppt werden, die über diese API erstellt wurden
Nach dem Stoppen eines Versands können Sie mit dem Endpunkt stats die Anzahl der abgebrochenen Datensätze prüfen
Wird die Massennachricht nicht gefunden, gibt die API den Fehler bulkMessageNotFound zurück

Hauptfunktionen​

Anfrageparameter​

Parameter der obersten Ebene​

Empfängerstruktur​

Aktionsstruktur​

Struktur des Vorlagen-Payloads​

Variablenstruktur​

Parameterformate​

HEADER-Komponente​

BODY-Komponente​

BUTTONS-Komponente​

CAROUSEL-Komponente​

Beispiele​

1. Einfache Vorlage – keine Variablen, gleicher Inhalt für alle Empfänger​

2. Vorlage mit gemeinsamen Body-Variablen​

3. Personalisierte Vorlage – Variablen pro Empfänger mit isMerge​

4. Variable einer URL-Schaltfläche​

5. Geplanter Versand​

Antwort​

Fehlerantworten​

Stats – Versandstatistiken​

Anfrageparameter​

Antwort​

Stats-Felder​

Referenz-ID​

Message Stats – WhatsApp-Nachrichtenstatus​

Anfrageparameter​

Antwort​

Message-Stats-Felder​

Options-Struktur – Seitenumbruch, Filterung und Sortierung​

Options-Felder​

Struktur des Seitenumbruchs​

Filterstruktur​

Sortierstruktur​

Beispiel für die kombinierte Verwendung​

Records – Datensatzdetails und Auflistung​

List – Datensatzliste​

Anfrageparameter​

Anfrage – Grundlegende Verwendung​

Anfrage – Nach bestimmtem Status filtern​

Antwort​

List With Messages – Liste mit Nachrichtendetails​

Anfrage – Grundlegende Verwendung​

Anfrage – Nach Nachrichtenstatus filtern​

Anfrage – Fehlgeschlagene Nachrichten auflisten​

Antwort​

Datensatzfelder​

Vergleich: list und list-with-messages​

Stop – Versand abbrechen​

Anfrageparameter​

Antwort​

Hauptfunktionen

Anfrageparameter

Parameter der obersten Ebene

Empfängerstruktur

Aktionsstruktur

Struktur des Vorlagen-Payloads

Variablenstruktur

Parameterformate

HEADER-Komponente

BODY-Komponente

BUTTONS-Komponente

CAROUSEL-Komponente

Beispiele

1. Einfache Vorlage – keine Variablen, gleicher Inhalt für alle Empfänger

2. Vorlage mit gemeinsamen Body-Variablen

3. Personalisierte Vorlage – Variablen pro Empfänger mit isMerge

4. Variable einer URL-Schaltfläche

5. Geplanter Versand

Antwort

Fehlerantworten

Stats – Versandstatistiken

Anfrageparameter

Antwort

Stats-Felder

Referenz-ID

Message Stats – WhatsApp-Nachrichtenstatus

Anfrageparameter

Antwort

Message-Stats-Felder

Options-Struktur – Seitenumbruch, Filterung und Sortierung

Options-Felder

Struktur des Seitenumbruchs

Filterstruktur

Sortierstruktur

Beispiel für die kombinierte Verwendung

Records – Datensatzdetails und Auflistung

List – Datensatzliste

Anfrageparameter

Anfrage – Grundlegende Verwendung

Anfrage – Nach bestimmtem Status filtern

Antwort

List With Messages – Liste mit Nachrichtendetails

Anfrage – Grundlegende Verwendung

Anfrage – Nach Nachrichtenstatus filtern

Anfrage – Fehlgeschlagene Nachrichten auflisten

Antwort

Datensatzfelder

Vergleich: list und list-with-messages

Stop – Versand abbrechen

Anfrageparameter

Antwort