Documentatie Bulk Template Message API

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 bulkMessageId 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/bulk-message/send.js

Belangrijkste functies

Verstuur bulktemplateberichten naar 1–5.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 5.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/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" }
  ]
}'

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 bulkMessageId terug, waarmee u het bezorgproces kunt volgen:

{
  "bulkMessageId": "abc123xyz789"
}

Foutantwoorden

Status	Beschrijving
`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
`invalidRequest`	Voor een ontvanger zijn meerdere identificatoren opgegeven of een verplichte payload ontbreekt
`channelNotFound`	Er is geen actief kanaal gevonden dat overeenkomt met het opgegeven `channelId`
`schema-error`	Een veld in de verzoekbody voldeed niet aan de schemavalidatie (ontbrekend verplicht veld, onjuist type of niet-ondersteunde waarde)

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

Stats — bezorgstatistieken

Vraagt de huidige bezorgstatus van een bulkbericht op. Geeft aantallen terug voor records in behandeling, geslaagd, mislukt en geannuleerd.

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

Verzoekparameters

Parameter	Type	Verplicht	Beschrijving
`bulkMessageId`	string	Ja	Id van het bulkbericht dat u wilt volgen (teruggegeven door `createBulkPerRecipient`)

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

Antwoord

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

Statvelden

Veld	Type	Beschrijving
`stats.pending`	number	Aantal records dat nog in de wachtrij staat
`stats.success`	number	Aantal records dat succesvol voor bezorging is verwerkt
`stats.failed`	number	Aantal records waarbij een bezorgfout is opgetreden
`stats.cancelled`	number	Aantal geannuleerde records
`stats.total`	number	Totaal aantal records (`pending + success + failed + cancelled`)

notitie

stats.success 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.

Stats versus Message Stats

Endpoint stats: toont de status van de bezorgtaak (pending, success, failed, cancelled)
Endpoint message-stats: toont de werkelijke berichtstatus (pending, sending, sent, delivered, read, error, enz.)
Een taak kan geslaagd zijn terwijl het bericht nog niet is bezorgd of gelezen

Referentie-id

De referenceId is een optioneel veld waarmee u bezorgrecords kunt koppelen aan een id uit uw eigen systeem om ze te volgen (bijv. ordernummer, ticket-id).

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

Belangrijk

Niet verplicht om te gebruiken
Mag niet worden dubbel gebruikt binnen hetzelfde bulkbericht
Kan wel opnieuw worden gebruikt in andere bulkberichten

Message Stats — WhatsApp-berichtstatus

Vraagt de berichtstatusstatistieken van een bulkbericht op. In tegenstelling tot het endpoint stats toont dit de werkelijke message.status van elk record in plaats van de taakstatus.

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/bulk-message/message-stats.js

Verzoekparameters

Parameter	Type	Verplicht	Beschrijving
`bulkMessageId`	string	Ja	Id van het bulkbericht dat u wilt opvragen

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

Antwoord

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

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	Records zonder bericht (nog in de wachtrij)
`total`	number	Totaal aantal records

Gebruikstips

Een hoog aantal no-message 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. `{"createdAt": -1}`)

Pagineringsstructuur

Veld	Type	Standaard	Beschrijving
`currentPage`	number	1	Paginanummer dat wordt opgevraagd
`pageItems`	number	50	Aantal records per pagina (maximum: 50)

Filterstructuur

Filteren gebeurt in het MongoDB-queryformaat. U kunt filteren op recordvelden. In het endpoint list-with-messages kunt u ook filteren op berichtvelden (bijv. message.status).

// Filter by record status
{
  "options": {
    "filtering": {
      "status": "success"
    }
  }
}

// Filter by referenceId
{
  "options": {
    "filtering": {
      "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"]
      }
    }
  }
}

Sorteerstructuur

Sorteren gebeurt in het MongoDB-sorteerformaat. 1 betekent oplopend, -1 aflopend.

// Sort by creation date descending (newest first)
{
  "options": {
    "sorting": {
      "createdAt": -1
    }
  }
}

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

Voorbeeld van gecombineerd gebruik

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

Dit voorbeeld sorteert bezorgde berichten van nieuw naar oud.

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

Records — recorddetails en overzicht

Toont alle bezorgrecords van een bulkbericht. Elk record staat voor één bericht dat naar een ontvanger is verstuurd.

List — lijst met records

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

Verzoekparameters

Parameter	Type	Verplicht	Beschrijving
`bulkMessageId`	string	Ja	Id van het bulkbericht waarvan u de records wilt tonen
`options`	object	Nee	Opties voor paginering, filteren en sorteren. Zie Opties voor details.

Verzoek — basisgebruik

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

Verzoek — filteren op een specifieke status

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

Toont alleen geslaagde bezorgrecords (record.status = "success").

Antwoord

{
  "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 — lijst met berichtdetails

Heeft dezelfde mogelijkheden als het endpoint list (paginering, filteren, sorteren). Het enige verschil: als een record een messageId heeft, wordt ook het bijbehorende message-object teruggegeven. 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/bulk-message-records/list-with-messages.js

Verzoek — basisgebruik

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

Verzoek — filteren op berichtstatus

{
  "bulkMessageId": "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

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

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

Antwoord

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

Recordvelden

Veld	Type	Beschrijving
`_id`	string	Record-id
`bulkMessageId`	string	Id van het bulkbericht waartoe dit record behoort
`userId`	string	Gebruikers-id van de ontvanger
`sessionId`	string	Id van de gespreksessie
`messageId`	string	Id van het verstuurde bericht (null als het nog niet is verstuurd)
`referenceId`	string	Optionele referentie-id (indien opgegeven)
`status`	string	Recordstatus: `pending`, `success`, `failed`, `cancelled`
`message`	object	Berichtdetails (alleen in list-with-messages)

Vergelijking van List en List-With-Messages

Functie	list	list-with-messages
Paginering	Ja	Ja
Filteren	Ja (alleen recordvelden)	Ja (record- en berichtvelden)
Berichtobject	Nee	Ja (als messageId bestaat)
Prestaties	Snel	Gemiddeld (voert een JOIN uit)
Filter message.status	Niet beschikbaar	Beschikbaar

Gebruiksscenario's

list: snel alle records tonen, filteren op referenceId, recordstatussen controleren
list-with-messages: WhatsApp-berichtstatussen (delivered, read) bekijken, berichtpayloads inspecteren
Filtervoorbeelden:
- {"status": "failed"} — mislukte bezorgrecords
- {"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)
- {"status": {"$in": ["success", "pending"]}} — records 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 records per pagina (pageItems) is 50; standaard 50 als het niet is opgegeven
Het filter message.status werkt alleen in list-with-messages
Records met een null-messageId hebben een null-message-object

Stop — bezorging annuleren

Stopt een lopende bulkbezorging. De taak in de wachtrij wordt geannuleerd en alle records met de status pending krijgen de status cancelled. Records die al als success of failed zijn verwerkt, worden niet gewijzigd.

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

waarschuwing

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

Verzoekparameters

Parameter	Type	Verplicht	Beschrijving
`bulkMessageId`	string	Ja	Id van het bulkbericht dat u wilt stoppen

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

Antwoord

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

{}

tip

Alleen bulkberichten die via deze API zijn aangemaakt, kunnen worden gestopt
Na het stoppen van een bezorging kunt u het endpoint stats gebruiken om het aantal geannuleerde records te controleren
Als het bulkbericht niet kan worden gevonden, geeft de API de fout bulkMessageNotFound terug

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​

Stats — bezorgstatistieken​

Verzoekparameters​

Antwoord​

Statvelden​

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​

Records — recorddetails en overzicht​

List — lijst met records​

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​

Recordvelden​

Vergelijking van List en List-With-Messages​

Stop — bezorging annuleren​

Verzoekparameters​

Antwoord​

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

Stats — bezorgstatistieken

Verzoekparameters

Antwoord

Statvelden

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

Records — recorddetails en overzicht

List — lijst met records

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

Recordvelden

Vergelijking van List en List-With-Messages

Stop — bezorging annuleren

Verzoekparameters

Antwoord