Documentatie Bulk Template Message API — v2

Met deze API kunt u templateberichten tegelijk naar meerdere ontvangers sturen via het WhatsApp-kanaal.

De bezorging van berichten wordt asynchroon verwerkt; het API-verzoek geeft direct een bulkOperationId terug, terwijl de berichten in de wachtrij worden gezet en op de achtergrond worden verwerkt.

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

Antwoordformaat

Elk endpoint in dit document is een custom function. De body van het HTTP-antwoord bevat de eigen velden van de functie (_id, title, pathString…) en het eigenlijke antwoord van het endpoint onder result. De antwoordvoorbeelden in dit document tonen de inhoud van result:

{
  "_id": "function_id",
  "title": "Show",
  "pathString": "/bulk-message-api-app/api/v2/bulk-operation/show.js",
  "result": {
    "bulkOperation": { "_id": "abc123xyz789", "status": "running" }
  }
}

Overstappen van v1

v2 draait naast v1, zodat u kunt overstappen wanneer het u uitkomt. De endpoints van v1 (/api/bulk-message/…, /api/bulk-message-records/…) worden uitgefaseerd; nieuwe integraties moeten v2 gebruiken.

Zet de endpointpaden over naar v2: …/api/bulk-message/… wordt …/api/v2/bulk-operation/…, en …/api/bulk-message-records/… wordt …/api/v2/bulk-operation-items/…. De verzoekbody van send verandert niet; één verzoek accepteert nu maximaal 100.000 ontvangers in plaats van 5.000.
Stuur in verzoeken bulkOperationId in plaats van bulkMessageId.
Vervang stats.js door show.js.
Lees de antwoorden met de nieuwe veldnamen uit de tabel hieronder.

De endpoints van v2 kennen alleen bulkbewerkingen die met de send van v2 zijn aangemaakt. Wilt u een bulkbericht volgen dat vóór de overstap met v1 is aangemaakt, gebruik daarvoor dan de endpoints van v1.

Endpoints

v1	v2	Wat verandert er in het antwoord
`bulk-message/send.js`	`v2/bulk-operation/send.js`	`{ bulkMessageId }` wordt `{ bulkOperationId }`
`bulk-message/stats.js`	`v2/bulk-operation/show.js`	`{ bulkMessage, stats }` wordt `{ bulkOperation }`
`bulk-message/message-stats.js`	`v2/bulk-operation/message-stats.js`	De tellers staan in de root in plaats van onder `messageStats`
`bulk-message/stop.js`	`v2/bulk-operation/stop.js`	Niets
`bulk-message-records/list.js`	`v2/bulk-operation-items/list.js`	`bulkMessageRecords` wordt `bulkOperationItems`
`bulk-message-records/list-with-messages.js`	`v2/bulk-operation-items/list-with-messages.js`	Hetzelfde als `list`, en elk item bevat ook `session`

Veldnamen

v1	v2
`stats.success`	`bulkOperation.progress.succeeded`
`stats.pending`, `stats.failed`, `stats.cancelled`, `stats.total`	`bulkOperation.progress.pending`, `.failed`, `.cancelled`, `.total`
—	`bulkOperation.progress.unknown`, `bulkOperation.status`, `bulkOperation.result.outcome`
`bulkMessage` (bulkbericht)	`bulkOperation` (bulkbewerking)
`bulkMessageRecord` (record)	`bulkOperationItem` (item)
`bulkMessageId` in verzoeken, in het antwoord van `send` en op records	`bulkOperationId`
`username` / `userId` / `sessionId` van het record, zoals verstuurd	`payload.username` / `payload.userId` / `payload.sessionId`
`referenceId` van het record	`payload.referenceId`
`payload` van het record (de templatepayload van de ontvanger)	`payload.payload`
`userId`, `sessionId`, `messageId` van het record na verzending	`result.userId`, `result.sessionId`, `result.messageId`
recordstatus `success`	`succeeded`
`errorMessage` van het record bij mislukte records	`error.message`, naast `error.code` en `error.retryable`
—	`position` (de index van de ontvanger in `recipients`)
filter `{"status": "success"}`	`{"status": "succeeded"}`
filter `{"referenceId": "…"}`	`{"payload.referenceId": "…"}`
fouten van `send` `schema-error`, `invalidRequest`	`zod-schema-error`, met het pad van het ongeldige veld in de melding

Belangrijkste functies

Verstuur bulktemplateberichten naar 1–100.000 ontvangers in één verzoek
Gepersonaliseerde variabelen per ontvanger (HEADER, BODY, BUTTONS, CAROUSEL)
Gedeelde defaultPayload voor alle ontvangers, met samenvoegen van de ontvangerspecifieke payload (isMerge)
Geplande bezorging (scheduleAt)
Geef ontvangers op met username (telefoonnummer), userId of sessionId
Verstuur meerdere berichten naar dezelfde gebruiker in één bulkverzoek
Optionele referenceId om records te koppelen aan externe systemen
Wijs gesprekken na het verzenden automatisch toe aan een gebruiker of werkgroep (action)

waarschuwing

Met deze API kunt u alleen templates versturen die door Meta zijn goedgekeurd.

De templatenaam en taalcode moeten exact overeenkomen met de template die in Meta Business Manager is geregistreerd.

Verzoekparameters

Parameters op het hoogste niveau

Parameter	Type	Verplicht	Beschrijving
`channelUsername`	string	Ja	WhatsApp-kanaalnummer waarmee het bericht wordt verstuurd (bijv. `"908506669933"`)
`connectorBrand`	string	Ja	Merk van de kanaalconnector. Momenteel ondersteunde waarde: `"whatsapp"`
`title`	string	Nee	Titel van de campagne. Wordt weergegeven in het dashboard. Standaard: `"-"`
`scheduleAt`	string (ISO 8601)	Nee	Geplande datum en tijd van bezorging (bijv. `"2026-06-10T10:00:00.000Z"`). Als dit ontbreekt, worden de berichten direct verstuurd.
`defaultPayload`	object	Voorwaardelijk*	Standaard templatepayload die voor alle ontvangers geldt. Verplicht als een ontvanger geen eigen `payload` opgeeft.
`recipients`	array	Ja	Lijst met ontvangers. Minimaal 1, maximaal 100.000 ontvangers.
`action`	object	Nee	Actie die na het verzenden op het gesprek wordt toegepast. `assign-to-user` of `assign-to-workgroup`.

*Als elke ontvanger een eigen payload opgeeft, is defaultPayload optioneel.

Structuur van een ontvanger

Voor elke ontvanger moet precies één van username, userId of sessionId worden opgegeven. Meerdere identificatoren tegelijk zijn niet toegestaan, en als u er geen opgeeft, volgt een fout.

Om meerdere berichten naar dezelfde gebruiker te sturen in één bulkverzoek, voegt u dezelfde identificator meerdere keren toe aan de ontvangerslijst.

Veld	Type	Beschrijving
`username`	string	Telefoonnummer van de ontvanger (bijv. `"905554443322"`). Als de gebruiker niet in het systeem bestaat, wordt die automatisch aangemaakt.
`userId`	string	Id van een bestaande gebruiker in het systeem.
`sessionId`	string	Id van een bestaande gespreksessie in het systeem.
`referenceId`	string	Optionele referentie-id (max. 256 tekens) om te koppelen aan records in externe systemen (CRM, bestelling, ticket, enz.). Moet uniek zijn binnen de bulk als die wordt opgegeven.
`payload`	object	Ontvangerspecifieke templatepayload (optioneel). Bij `isMerge: true` wordt die samengevoegd met `defaultPayload`.
`isMerge`	boolean	Overschrijft het samenvoeggedrag voor deze ontvanger (optioneel). Als dit ontbreekt, wordt `defaultPayload.isMerge` gebruikt.

Structuur van een actie

Veld	Type	Beschrijving
`action.key`	string	`"assign-to-user"` wijst het gesprek toe aan een specifieke medewerker; `"assign-to-workgroup"` wijst het toe aan een werkgroep.
`action.value`	string	Id van de doelgebruiker of werkgroep.

Structuur van de templatepayload

defaultPayload en de ontvangerspecifieke payload hebben dezelfde structuur. Voor templateberichten moet type: "template" worden opgegeven.

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

Veld	Type	Verplicht	Beschrijving
`type`	string	Ja	Type payload. Voor templateberichten: `"template"`
`template.templateName`	string	Ja*	Templatenaam zoals geregistreerd in Meta. Optioneel in ontvangerpayloads wanneer `isMerge: true` wordt gebruikt (wordt van de standaard overgenomen).
`template.languageCode`	string	Nee	Taalcode van de template (bijv. `"tr"`, `"en"`, `"tr-TR"`, `"en-US"`). Moet exact overeenkomen met de taal die in Meta is geregistreerd.
`template.variables`	array	Nee	Lijst met variabelen die op de templatecomponenten worden toegepast. Hieronder beschreven.
`isMerge`	boolean	Nee	`true`: de ontvangerpayload wordt diep samengevoegd met `defaultPayload`. `false` of weggelaten: de ontvangerpayload vervangt `defaultPayload` volledig.

Gedrag van isMerge

Als defaultPayload.isMerge: true is en de ontvanger een eigen payload opgeeft, wordt een diepe samenvoeging toegepast.
Bij een diepe samenvoeging kan de ontvanger alleen variables opgeven; templateName en languageCode worden overgenomen van de standaardpayload.
Het veld isMerge van de ontvanger overschrijft defaultPayload.isMerge.
Als een ontvanger geen payload opgeeft, wordt altijd defaultPayload gebruikt.

Structuur van variabelen

Elk item in de array variables komt overeen met een templatecomponent. Een componenttype (type) mag maar één keer in de array voorkomen.

type	Beschrijving	parameters	cards
`"HEADER"`	Headercomponent van de template. Tekstvariabele of media-URL (afbeelding, video, document)	Ja	—
`"BODY"`	Tekstvariabelen van de body van de template	Ja	—
`"BUTTONS"`	Variabelen voor dynamische URL-achtervoegsels van knoppen	Ja	—
`"CAROUSEL"`	Kaartcomponenten voor carrouseltemplates	—	Ja

Parameterformaten

Het veld parameters kan in drie verschillende formaten worden opgegeven:

// Format 1: Array (index-based) — for placeholders like {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]

// Format 2: Object (numeric keys) — alternative representation for {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }

// Format 3: Object (named keys) — for placeholders like {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }

Welk formaat moet ik gebruiken?

Als uw Meta-template plaatshouders zoals {{1}}, {{2}} gebruikt, gebruikt u het arrayformaat of het object met numerieke sleutels.
Als uw template benoemde plaatshouders zoals {{firstName}} of {{orderTotal}} gebruikt, gebruikt u het object met benoemde sleutels.
Bij arrays is de volgorde van belang: het eerste element hoort bij {{1}}, het tweede bij {{2}}, enzovoort.

HEADER-component

Gebruik de component HEADER wanneer de header van de template media (afbeelding, video, document) of dynamische tekst bevat.

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

// Text header variable
{
  "type": "HEADER",
  "parameters": ["Special Campaign"]
}

BODY-component

Wordt gebruikt voor dynamische tekstvariabelen in de body van de template.

// Array format — when the template uses {{1}}, {{2}}, {{3}}
{
  "type": "BODY",
  "parameters": ["John", "ORD-12345", "150.00 USD"]
}

// Named format — when the template uses {{name}}, {{orderAmount}}
{
  "type": "BODY",
  "parameters": {
    "name": "John",
    "orderAmount": "150.00 USD"
  }
}

BUTTONS-component

Wordt gebruikt voor knoppen met dynamische URL-achtervoegsels. Als de template meerdere URL-knoppen bevat, worden alleen knoppen met variabelen opeenvolgend genummerd (knoppen zonder variabelen of FLOW-knoppen worden genegeerd).

// Single URL button suffix variable
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345"]
}

// Multiple URL button suffix variables (first URL button, second URL button)
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345", "cancel/ORD-12345"]
}

CAROUSEL-component

Bij carrouseltemplates worden de componentvariabelen voor elke kaart apart gedefinieerd.

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

waarschuwing

De lengte van de array cards moet exact overeenkomen met het aantal kaarten dat in de template is gedefinieerd.

Voorbeelden

1. Eenvoudige template — geen variabelen, dezelfde inhoud voor alle ontvangers

Dit is de eenvoudigste manier om een statische template zonder variabelen naar meerdere ontvangers te sturen.

{
  "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/v2/bulk-operation/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" }
  ]
}'

tip

Ontvangers die via username worden opgegeven, worden automatisch aangemaakt als ze nog niet in het systeem bestaan
Alle ontvangers gebruiken dezelfde defaultPayload; ontvangerspecifieke gegevens zijn niet nodig
Als isMerge niet is opgegeven, gebruikt elke ontvanger rechtstreeks de defaultPayload

2. Template met gedeelde bodyvariabelen

Dezelfde template wordt naar alle ontvangers gestuurd met identieke variabelewaarden. De template bevat plaatshouders zoals {{1}} en {{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" }]
}

tip

In dit voorbeeld kan de body van de template een tekst bevatten zoals: "Profiteer van {{1}} korting in onze campagne! Aanbieding geldig tot {{2}}."
parameters[0] vervangt {{1}}, terwijl parameters[1] {{2}} vervangt

3. Gepersonaliseerde template — variabelen per ontvanger met isMerge

Voor elke ontvanger worden andere variabelewaarden gebruikt. Door isMerge: true in de defaultPayload in te stellen, hoeven ontvangers alleen variables op te geven; templateName en languageCode worden overgenomen van de standaardpayload.

In dit voorbeeld bevat de template zowel een mediaheader als gepersonaliseerde bodyvariabelen.

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

tip

Dankzij isMerge: true hoeft templateName niet in elke ontvangerpayload te worden herhaald
De array variables van elke ontvanger is volledig onafhankelijk
De media-URL van de header moet openbaar toegankelijk zijn
Als type in de ontvangerpayload ontbreekt, wordt defaultPayload.type overgenomen

4. Variabele voor URL-knop

Gebruik de component BUTTONS wanneer de template een knop met een dynamisch URL-achtervoegsel bevat. Bijvoorbeeld een trackingnummer dat aan de basis-URL https://example.com/track/ wordt toegevoegd.

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

tip

Parameters van BUTTONS worden gekoppeld op basis van de volgorde van de knoppen die variabelen bevatten
FLOW-knoppen en knoppen zonder variabelen worden genegeerd; de nummering geldt alleen voor dynamische URL-knoppen
Als de URL van de templateknop https://example.com/track/{{1}} is, vervangt parameters[0] {{1}}

5. Geplande bezorging

Plan een bericht in dat op een toekomstige datum en tijd wordt verstuurd. scheduleAt moet worden opgegeven als ISO 8601-tijdstempel in UTC.

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

tip

scheduleAt moet in de UTC-tijdzone worden opgegeven (bijv. voor 10:00 uur Turkse tijd gebruikt u 07:00:00.000Z)
Dit voorbeeld gebruikt het formaat met benoemde parameters; de template moet plaatshouders bevatten zoals {{name}} en {{discountRate}}
Met action worden gesprekken die door het verzenden van het bericht ontstaan, automatisch toegewezen aan de opgegeven werkgroep

Antwoord

Een geslaagd verzoek geeft een bulkOperationId terug, waarmee u het bezorgproces kunt volgen:

{
  "bulkOperationId": "abc123xyz789"
}

Foutantwoorden

Status	Beschrijving
`recipients field is required`	Het veld `recipients` is niet meegestuurd
`Channel not found`	Er is geen geverifieerd kanaal gevonden dat overeenkomt met `channelUsername` en `connectorBrand`
`Channel is not verified`	Het gevonden kanaal bestaat maar is nog niet geverifieerd
`zod-schema-error`	Een veld in de verzoekbody voldeed niet aan de schemavalidatie (ontbrekend verplicht veld, onjuist type, niet-ondersteunde waarde, meer dan één identificator bij een ontvanger of een ontbrekende `payload`). De melding noemt het veld, bijv. `recipients.0.referenceId: referenceId must be unique`

Met de teruggegeven bulkOperationId kunt u via de onderstaande endpoints bezorgstatistieken opvragen en het bezorgproces stoppen.

Show — status en statistieken van de bulkbewerking

Vraagt de bulkbewerking op met de huidige status en de bezorgtellers van de items, onder de sleutel bulkOperation.

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

Verzoekparameters

Parameter	Type	Verplicht	Beschrijving
`bulkOperationId`	string	Ja	Id van de bulkbewerking die u wilt volgen (teruggegeven door `send`)

{
  "bulkOperationId": "abc123xyz789"
}

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

Antwoord

{
  "bulkOperation": {
    "_id": "abc123xyz789",
    "type": "send-bulk-message",
    "slug": "my-workspace",
    "userId": "agent_user_id",
    "payload": {
      "title": "Campaign Title",
      "channelUsername": "908506669933",
      "connectorBrand": "whatsapp",
      "connectorSlug": "om2WabVegaCloud",
      "defaultLanguageCode": "tr-TR",
      "sentUser": { "firstname": "John", "lastname": "Doe" },
      "defaultPayload": {
        "type": "template",
        "template": { "templateName": "order_confirmation", "languageCode": "tr-TR" },
        "isMerge": true
      },
      "source": { "type": "recipients", "bulkOperationInputGroupId": "group_id" }
    },
    "status": "running",
    "result": { "outcome": "unknown", "hasErrors": false },
    "progress": {
      "total": 100,
      "pending": 45,
      "succeeded": 42,
      "failed": 3,
      "cancelled": 10,
      "unknown": 0
    },
    "scheduleAt": "2026-06-10T07:00:00.000Z",
    "createdAt": "2026-06-08T10:00:00.000Z",
    "updatedAt": "2026-06-10T07:00:30.000Z",
    "startedAt": "2026-06-10T07:00:05.000Z"
  }
}

Velden van Show

De velden staan onder bulkOperation.

Veld	Type	Beschrijving
`status`	string	Status van de bulkbewerking: `preparing`, `scheduled`, `pending`, `running`, `stopping`, `stopped`, `completed`, `failed`
`progress.total`	number	Totaal aantal items
`progress.pending`	number	Items die nog in de wachtrij staan
`progress.succeeded`	number	Items die succesvol voor bezorging zijn verwerkt
`progress.failed`	number	Items waarbij een bezorgfout is opgetreden
`progress.cancelled`	number	Items die door `stop` zijn geannuleerd
`progress.unknown`	number	Items waarvan het resultaat niet kon worden bepaald
`result.outcome`	string	Eindresultaat zodra de bulkbewerking klaar is: `success`, `partial`, `all-failed`, `cancelled`, `unknown`
`result.hasErrors`	boolean	`true` als ten minste één item is mislukt
`scheduleAt`	string	Geplande bezorgtijd (alleen bij geplande bulkbewerkingen)
`startedAt`, `completedAt`	string	Wanneer de bezorging is begonnen en geëindigd

notitie

progress.succeeded geeft aan dat het bericht door het systeem succesvol is overgedragen. Het is geen garantie dat Meta het bericht bij de ontvanger heeft bezorgd. Latere statusupdates van Meta (zoals delivered, read of failed) hebben geen invloed op deze teller en worden hier niet weergegeven.

Show versus Message Stats

Endpoint show: toont de bezorgstatus van de items (pending, succeeded, failed, cancelled, unknown)
Endpoint message-stats: toont de werkelijke berichtstatus (pending, sending, sent, delivered, read, error, enz.)
Een item kan succeeded zijn terwijl het bericht nog niet is bezorgd of gelezen

Referentie-id

De referenceId is een optioneel veld waarmee u bezorgitems kunt koppelen aan een id uit uw eigen systeem om ze te volgen (bijv. ordernummer, ticket-id). Het wordt bij elk item teruggegeven als payload.referenceId.

Als u het opgeeft, moet het uniek zijn binnen de bulk (max. 256 tekens).

Belangrijk

Niet verplicht om te gebruiken
Mag niet dubbel worden gebruikt binnen dezelfde bulkbewerking
Kan wel opnieuw worden gebruikt in andere bulkbewerkingen

Message Stats — WhatsApp-berichtstatus

Vraagt de berichtstatusstatistieken van een bulkbewerking op. In tegenstelling tot het endpoint show toont dit de werkelijke message.status van de verstuurde berichten in plaats van de itemstatus.

Mogelijke berichtstatussen: 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/v2/bulk-operation/message-stats.js

Verzoekparameters

Parameter	Type	Verplicht	Beschrijving
`bulkOperationId`	string	Ja	Id van de bulkbewerking die u wilt opvragen

{
  "bulkOperationId": "abc123xyz789"
}

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

Antwoord

{
  "pending": 5,
  "sending": 2,
  "sent": 10,
  "delivered": 45,
  "read": 30,
  "deleted": 2,
  "warning": 1,
  "error": 3,
  "unknown": 0,
  "not-sended": 2,
  "no-message": 20,
  "total": 120
}

Velden van Message Stats

Veld	Type	Beschrijving
`pending`	number	Berichten die nog niet zijn verstuurd
`sending`	number	Berichten die op dit moment worden verstuurd
`sent`	number	Berichten die aan WhatsApp zijn overgedragen maar nog niet zijn bezorgd
`delivered`	number	Berichten die op de telefoon van de ontvanger zijn bezorgd
`read`	number	Berichten die door de ontvanger zijn gelezen
`deleted`	number	Verwijderde berichten
`warning`	number	Berichten met waarschuwingen
`error`	number	Berichten met fouten
`unknown`	number	Berichten met onbekende status
`not-sended`	number	Berichten die niet konden worden verstuurd
`no-message`	number	Items zonder bericht (nog in de wachtrij, mislukt of geannuleerd)
`total`	number	Totaal aantal items

Gebruikstips

Een hoog aantal no-message terwijl de bulkbewerking running is, betekent dat de bezorging nog bezig is
Het aantal delivered toont de succesvolle bezorging van berichten
Het aantal read kunt u gebruiken om de betrokkenheid bij een campagne te meten
U kunt dit endpoint periodiek opvragen voor realtime tracking

Opties — paginering, filteren en sorteren

De parameter options die in de endpoints list en list-with-messages wordt gebruikt, biedt een standaardstructuur voor paginering, filteren en sorteren.

Optievelden

Veld	Type	Verplicht	Beschrijving
`pagination`	object	Nee	Pagineringsinstellingen
`filtering`	object	Nee	Filtercriteria
`sorting`	object	Nee	Sorteerinstellingen (bijv. `{"position": 1}`)

Pagineringsstructuur

Als pagination niet wordt meegestuurd, wordt de eerste pagina met maximaal 50 items teruggegeven. Als het wel wordt meegestuurd, is currentPage verplicht.

Veld	Type	Standaard	Beschrijving
`currentPage`	number	—	Paginanummer dat wordt opgevraagd (verplicht als `pagination` wordt meegestuurd)
`pageItems`	number	50	Aantal items per pagina (maximum: 50)

Filterstructuur

Filteren gebeurt in het MongoDB-queryformaat op de itemvelden, met de veldnamen precies zoals ze in het antwoord staan (bijv. status, payload.referenceId, result.messageId). In het endpoint list-with-messages kunt u ook filteren op berichtvelden (bijv. message.status).

// Filter by item status
{
  "options": {
    "filtering": {
      "status": "succeeded"
    }
  }
}

// Filter by referenceId
{
  "options": {
    "filtering": {
      "payload.referenceId": "ORDER-12345"
    }
  }
}

// Filter by message status (only list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// Filter by multiple statuses using $in (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// Exclude specific statuses using $nin (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

// List items that have no message (only list-with-messages)
{
  "options": {
    "filtering": {
      "message": {
        "$exists": false
      }
    }
  }
}

Sorteerstructuur

Sorteren gebeurt in het MongoDB-sorteerformaat. 1 betekent oplopend, -1 aflopend. position is de plaats van de ontvanger in de array recipients van het verzoek (vanaf 0).

// Sort in the order the recipients were sent in the request
{
  "options": {
    "sorting": {
      "position": 1
    }
  }
}

// Sort by multiple fields
{
  "options": {
    "sorting": {
      "status": 1,
      "position": 1
    }
  }
}

Voorbeeld van gecombineerd gebruik

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 2,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    },
    "sorting": {
      "position": 1
    }
  }
}

Dit voorbeeld toont de tweede pagina met bezorgde berichten, in de volgorde van de ontvangers.

Praktische tips

Combineer filtering en pagination voor gerichte queries
Het antwoord bevat options.pagination.totalCount en options.pagination.totalPages om te navigeren
Het filter message.status werkt alleen in het endpoint list-with-messages

Items — itemdetails en overzicht

Toont alle bezorgitems van een bulkbewerking. Elk item staat voor één vermelding in de array recipients.

List — lijst met items

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

Verzoekparameters

Parameter	Type	Verplicht	Beschrijving
`bulkOperationId`	string	Ja	Id van de bulkbewerking waarvan u de items wilt tonen
`options`	object	Nee	Opties voor paginering, filteren en sorteren. Zie Opties voor details.

Verzoek — basisgebruik

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

Verzoek — filteren op een specifieke status

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "status": "failed"
    }
  }
}

Toont alleen mislukte bezorgitems, met de reden in error.

Antwoord

{
  "bulkOperationItems": [
    {
      "_id": "item_1",
      "bulkOperationId": "abc123xyz789",
      "bulkOperationBatchId": "batch_1",
      "slug": "my-workspace",
      "position": 0,
      "payload": {
        "username": "905554443301",
        "referenceId": "ORDER-12345",
        "payload": {
          "template": {
            "variables": [{ "type": "BODY", "parameters": ["Ahmet", "ORD-001"] }]
          }
        }
      },
      "status": "succeeded",
      "attempt": 1,
      "result": {
        "userId": "user_123",
        "sessionId": "session_456",
        "messageId": "msg_789"
      },
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:00:01.000Z",
      "completedAt": "2026-06-10T10:00:01.000Z"
    },
    {
      "_id": "item_2",
      "bulkOperationId": "abc123xyz789",
      "bulkOperationBatchId": "batch_1",
      "slug": "my-workspace",
      "position": 1,
      "payload": { "username": "905554443302", "referenceId": "ORDER-12346" },
      "status": "failed",
      "attempt": 1,
      "error": { "code": "error", "message": "Variable missing", "retryable": false },
      "result": { "userId": "user_124", "sessionId": "session_457" },
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:00:01.000Z",
      "completedAt": "2026-06-10T10:00:01.000Z"
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {},
    "searching": {}
  }
}

List With Messages — lijst met berichtdetails

Heeft dezelfde mogelijkheden als het endpoint list (paginering, filteren, sorteren). Het verschil: elk item bevat ook de bijbehorende objecten message en session, als die bestaan. Zo ziet u de berichtstatus (delivered, read, error, enz.) en de payload in één query.

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

Verzoek — basisgebruik

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

Verzoek — filteren op berichtstatus

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

Dit voorbeeld haalt alleen berichten met de status "delivered" op.

Verzoek — mislukte berichten tonen

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

Wordt gebruikt om berichten te bekijken waarbij een bezorgfout is opgetreden.

Antwoord

{
  "bulkOperationItems": [
    {
      "_id": "item_1",
      "bulkOperationId": "abc123xyz789",
      "position": 0,
      "payload": { "username": "905554443301", "referenceId": "ORDER-12345" },
      "status": "succeeded",
      "result": {
        "userId": "user_123",
        "sessionId": "session_456",
        "messageId": "msg_789"
      },
      "message": {
        "_id": "msg_789",
        "type": "template",
        "status": "delivered",
        "payload": {
          "template": {
            "name": "order_notification"
          }
        },
        "createdAt": "2026-06-10T10:01:00.000Z"
      },
      "session": {
        "_id": "session_456",
        "status": "opened"
      }
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {},
    "searching": {}
  }
}

Itemvelden

Veld	Type	Beschrijving
`_id`	string	Item-id
`bulkOperationId`	string	Id van de bulkbewerking waartoe dit item behoort
`position`	number	Plaats van de ontvanger in de array `recipients` van het verzoek, vanaf `0`
`payload`	object	De ontvanger precies zoals in het verzoek verstuurd (`username` / `userId` / `sessionId`, `referenceId`, `payload`, `isMerge`)
`status`	string	Itemstatus: `pending`, `succeeded`, `failed`, `cancelled`, `unknown`
`error`	object	Alleen bij `failed` items: `code`, `message` en `retryable`
`result.userId`	string	Gebruikers-id van de ontvanger
`result.sessionId`	string	Id van de gespreksessie
`result.messageId`	string	Id van het verstuurde bericht (ontbreekt als er geen bericht is verstuurd)
`completedAt`	string	Wanneer het item is verwerkt
`message`	object	Berichtdetails (alleen in list-with-messages)
`session`	object	Gespreksdetails (alleen in list-with-messages)

Vergelijking van List en List-With-Messages

Functie	list	list-with-messages
Paginering	Ja	Ja
Filteren	Ja (alleen itemvelden)	Ja (item- en berichtvelden)
Message / Session	Nee	Ja (als ze bestaan)
Prestaties	Snel	Gemiddeld (voert een JOIN uit)
Filter message.status	Niet beschikbaar	Beschikbaar

Gebruiksscenario's

list: snel alle items tonen, filteren op referenceId, itemstatussen controleren
list-with-messages: WhatsApp-berichtstatussen (delivered, read) bekijken, berichtpayloads inspecteren
Filtervoorbeelden:
- {"status": "failed"} — mislukte bezorgitems
- {"payload.referenceId": "ORDER-123"} — een specifieke referentie-id
- {"message.status": "delivered"} — bezorgde berichten (alleen list-with-messages)
- {"message.status": "read"} — gelezen berichten (alleen list-with-messages)
- {"message.status": "error"} — berichten met fouten (alleen list-with-messages)
- {"message.status": {"$in": ["delivered", "read"]}} — berichten die bezorgd of gelezen zijn (alleen list-with-messages)
- {"message.status": {"$nin": ["error", "not-sended"]}} — berichten zonder fouten en niet-verstuurde berichten (alleen list-with-messages)
- {"message": {"$exists": false}} — items zonder bericht (alleen list-with-messages)
- {"status": {"$in": ["succeeded", "pending"]}} — items die geslaagd zijn of in behandeling zijn

Opmerkingen over prestaties en gebruik

Het endpoint list is sneller; gebruik het bij voorkeur voor algemene statuscontroles
Gebruik list-with-messages wanneer berichtdetails nodig zijn
Het maximum aantal items per pagina (pageItems) is 50; standaard 50 als het niet is opgegeven
Het filter message.status werkt alleen in list-with-messages
Items zonder result.messageId hebben geen message-object

Stop — bezorging annuleren

Stopt een lopende bezorging van een bulkbewerking. Alle items met de status pending krijgen de status cancelled en de bulkbewerking wordt stopped. Items die al als succeeded of failed zijn verwerkt, worden niet gewijzigd. Een geplande bulkbewerking kan ook vóór het tijdstip in scheduleAt worden gestopt.

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

waarschuwing

Deze actie kan niet ongedaan worden gemaakt. Een gestopte bezorging kan niet worden hervat.

Verzoekparameters

Parameter	Type	Verplicht	Beschrijving
`bulkOperationId`	string	Ja	Id van de bulkbewerking die u wilt stoppen

{
  "bulkOperationId": "abc123xyz789"
}

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

Antwoord

Bij een geslaagd verzoek is de responsebody leeg. Een HTTP 200-status geeft aan dat de bewerking is geslaagd.

{}

tip

Alleen bulkbewerkingen die via deze API zijn aangemaakt, kunnen worden gestopt
Na het stoppen van een bezorging kunt u het endpoint show gebruiken om het aantal geannuleerde items te controleren (bulkOperation.progress.cancelled)
Als de bulkbewerking niet kan worden gevonden, geeft de API de fout Bulk operation not found. terug

Overstappen van v1​

Endpoints​

Veldnamen​

Belangrijkste functies​

Verzoekparameters​

Parameters op het hoogste niveau​

Structuur van een ontvanger​

Structuur van een actie​

Structuur van de templatepayload​

Structuur van variabelen​

Parameterformaten​

HEADER-component​

BODY-component​

BUTTONS-component​

CAROUSEL-component​

Voorbeelden​

1. Eenvoudige template — geen variabelen, dezelfde inhoud voor alle ontvangers​

2. Template met gedeelde bodyvariabelen​

3. Gepersonaliseerde template — variabelen per ontvanger met isMerge​

4. Variabele voor URL-knop​

5. Geplande bezorging​

Antwoord​

Foutantwoorden​

Show — status en statistieken van de bulkbewerking​

Verzoekparameters​

Antwoord​

Velden van Show​

Referentie-id​

Message Stats — WhatsApp-berichtstatus​

Verzoekparameters​

Antwoord​

Velden van Message Stats​

Opties — paginering, filteren en sorteren​

Optievelden​

Pagineringsstructuur​

Filterstructuur​

Sorteerstructuur​

Voorbeeld van gecombineerd gebruik​

Items — itemdetails en overzicht​

List — lijst met items​

Verzoekparameters​

Verzoek — basisgebruik​

Verzoek — filteren op een specifieke status​

Antwoord​

List With Messages — lijst met berichtdetails​

Verzoek — basisgebruik​

Verzoek — filteren op berichtstatus​

Verzoek — mislukte berichten tonen​

Antwoord​

Itemvelden​

Vergelijking van List en List-With-Messages​

Stop — bezorging annuleren​

Verzoekparameters​

Antwoord​

Overstappen van v1

Endpoints

Veldnamen

Belangrijkste functies

Verzoekparameters

Parameters op het hoogste niveau

Structuur van een ontvanger

Structuur van een actie

Structuur van de templatepayload

Structuur van variabelen

Parameterformaten

HEADER-component

BODY-component

BUTTONS-component

CAROUSEL-component

Voorbeelden

1. Eenvoudige template — geen variabelen, dezelfde inhoud voor alle ontvangers

2. Template met gedeelde bodyvariabelen

3. Gepersonaliseerde template — variabelen per ontvanger met isMerge

4. Variabele voor URL-knop

5. Geplande bezorging

Antwoord

Foutantwoorden

Show — status en statistieken van de bulkbewerking

Verzoekparameters

Antwoord

Velden van Show

Referentie-id

Message Stats — WhatsApp-berichtstatus

Verzoekparameters

Antwoord

Velden van Message Stats

Opties — paginering, filteren en sorteren

Optievelden

Pagineringsstructuur

Filterstructuur

Sorteerstructuur

Voorbeeld van gecombineerd gebruik

Items — itemdetails en overzicht

List — lijst met items

Verzoekparameters

Verzoek — basisgebruik

Verzoek — filteren op een specifieke status

Antwoord

List With Messages — lijst met berichtdetails

Verzoek — basisgebruik

Verzoek — filteren op berichtstatus

Verzoek — mislukte berichten tonen

Antwoord

Itemvelden

Vergelijking van List en List-With-Messages

Stop — bezorging annuleren

Verzoekparameters

Antwoord