Broadcasts API #

Een broadcast is één uitgaande verzending: een doelgroep, een openingsbericht, één kanaal en een planning. Optioneel benoemt het ook de AI-agent die de ontvangen antwoorden afhandelt. Met de Broadcasts API kun je die verzendingen vanuit je eigen code opbouwen, prijzen, lanceren en monitoren in plaats van via het dashboard. Zie voor het product zelf de Broadcasts-handleiding.

• Basis-URL — https://api.youraiconnector.com/v1
• Authenticatie — uw API-sleutel (zie Authenticatie)
• Fouten & paginering — zie Fouten & Paginering

Alle onderstaande voorbeelden tonen de ?apiKey= query-vorm in cURL en de X-API-Key header in JavaScript en Python — beide werken op elk eindpunt.

In de API-explorer. Elk eindpunt op deze pagina staat in de gepubliceerde OpenAPI-specificatie, dus je kunt de exacte velden bekijken en live verzoeken uitvoeren in de API-explorer.

Hoe een verzending is opgebouwd #

Het versturen van een broadcast bestaat uit vier aanroepen, niet één:

1. Maak de broadcast aan met de doelgroep, het kanaal en de planning — deze begint als een Draft.
2. Stel het openingsbericht in. Bij WhatsApp Business betekent dit het indienen van een sjabloon ter goedkeuring (of het kiezen van een sjabloon dat al is goedgekeurd). Op elk ander kanaal is het platte tekst.
3. Schat de kosten als je de prijs wilt controleren voordat je iets uitgeeft (optioneel).
4. Lanceer het. Bij het lanceren wordt een volledige controle uitgevoerd — doelgroep, bericht, sjabloongoedkeuring, verbonden afzender — en wordt de verzending gestart of krijg je precies te horen wat er ontbreekt.

Er wordt niets verzonden totdat je de lancering aanroept.

Het broadcast-object #

{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}

Tijdstempels worden geretourneerd als epoch-milliseconden (execution_date, created_at, last_modified_at, …), en elke contactverwijzing wordt geretourneerd als een pad-string zoals contacts/uid_whatsapp_15551234567.

Velden die je zelf instelt #

Alles wat je verstuurt als user_id, id, status of source_campaign_id wordt genegeerd bij het aanmaken en verwijderd bij het bijwerken — de status verandert alleen via de onderstaande eindpunten voor lanceren, pauzeren en hervatten.

Velden die het platform beheert #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, de batchtellers en contacts (de individuele contacten die vanuit het dashboard zijn toegevoegd, teruggelezen als pad-strings). Lees deze, schrijf ze niet.

Statussen #

Een broadcast aanmaken #

POST /broadcasts — maakt een Draft aan.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])

Antwoord (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

Broadcasts weergeven #

GET /broadcasts — elke broadcast in het account, nieuwste eerst.

Queryparameters

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]

Antwoord (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

Een broadcast ophalen #

GET /broadcasts/{broadcastId} — retourneert { "success": true, "broadcast": { ... } }. Gebruik dit om een lopende verzending te pollen: total_contacts_sent, unique_contacts_replied, overall_reply_rate en credits_used worden bijgewerkt naarmate het proces vordert.

curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Een broadcast die niet bestaat in uw account retourneert 404.

Een broadcast bijwerken #

PUT /broadcasts/{broadcastId} — stuur alleen de velden die u wilt wijzigen. U kunt ook een enkele sleutel binnen een genest object adresseren met een puntnotatie, bijv. "whats_app_template.body".

curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'

await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});

Een lege body retourneert 400. Twee regels die het weten waard zijn:

• opener_media is alles-of-niets. Stuur het volledige object, of null om de bijlage te verwijderen. Een puntnotatie hierin (opener_media.name) wordt geweigerd met 400, omdat een gedeeltelijk bijgewerkte bijlage een bestand zou beschrijven dat er niet is.
• Status is niet bewerkbaar. Gebruik lanceren, pauzeren en hervatten.

Het openingsbericht #

Elke uitzending bevat zijn opener in whats_app_template. Wat dat betekent, hangt af van het kanaal:

• WhatsApp Business — dit moet een sjabloon zijn dat door WhatsApp is goedgekeurd. Gebruik een van de twee onderstaande eindpunten.
• Elk ander kanaal (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — de body van hetzelfde veld is simpelweg de tekst die wordt verzonden. Het indienen via het onderstaande eindpunt slaat het op en markeert het als gereed, zonder dat WhatsApp hierbij betrokken is.

Een sjabloon ter goedkeuring indienen #

POST /broadcasts/{broadcastId}/template

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'

Antwoord (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status is wat WhatsApp zegt: pending terwijl het wordt beoordeeld, approved wanneer het bruikbaar is, rejected als het is geweigerd. Op een niet-WhatsApp-kanaal komt het direct terug als approved met template_sid: null — er is niets om te beoordelen.

Zaken die je zullen tegenhouden:

• Indienen terwijl een vorig sjabloon nog in behandeling is, geeft 400 terug. Wacht eerst op de beslissing.
• Het bewerken van een sjabloon dat momenteel is goedgekeurd, houdt het goedgekeurde sjabloon actief totdat het nieuwe terugkomt, zodat een lopende uitzending nooit zijn opener verliest.
• Op een WhatsApp-nummer dat rechtstreeks via Meta is verbonden, kan een uitzending met een bijgevoegde afbeelding of video niet worden ingediend (400) — bijlagen worden ondersteund op het beheerde WhatsApp Business-kanaal en op WhatsApp Web.

Een sjabloon gebruiken dat je al hebt laten goedkeuren #

POST /broadcasts/{broadcastId}/template/select — kopieert een reeds goedgekeurd sjabloon uit je sjabloonbibliotheek naar de uitzending, dus er is niets om op te wachten.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'

Antwoord (200)

{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}

De goedkeuring wordt aan onze kant geverifieerd op basis van het bibliotheekrecord — je verstuurt alleen de id. Je krijgt een 400 als de uitzending geen WhatsApp-concept is, als het sjabloon niet is goedgekeurd, als het een vervolgsjabloon is in plaats van een opener, of als de uitzending een bijlage heeft (bibliotheeksjablonen zijn alleen tekst). Een sjabloon-id die niet in je account staat, geeft 404 terug.

De kosten schatten #

POST /broadcasts/{broadcastId}/estimate-cost — berekent de prijs van de verzending voordat je deze bevestigt. Beschikbaar voor whatsapp en sms uitzendingen; elk ander kanaal geeft 400 terug. De uitzending heeft een list_id nodig, aangezien de schatting het aantal ontvangers telt.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"

WhatsApp-reactie (200) — tegoeden, uitgesplitst per land van bestemming:

{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

SMS-antwoord (200) — Amerikaanse dollars, gebaseerd op actuele Twilio-prijzen voor uw eigen Twilio-account:

{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}

Lees billing_mode voordat u een nummer toont. Hierin staat wie er wordt gefactureerd:

Bij sms-berichten zonder gekoppelde Twilio-inloggegevens worden nog steeds de segmentaantallen geretourneerd, met estimatedCostUsd: 0 — er is geen prijs om op te zoeken.

Een broadcast starten #

POST /broadcasts/{broadcastId}/launch

Bij het starten wordt eerst alles gecontroleerd en pas daarna wordt de broadcast voortgezet. Er is geen gedeeltelijke start: of het start, of er verandert niets en u krijgt een foutmelding met de reden.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

Antwoord (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status is waar de broadcast is terechtgekomen:

• Scheduled — execution_date ligt in de toekomst.
• Sending — het is nu gestart.
• Pending Approval — de WhatsApp-template is nog in afwachting van goedkeuring. Het wordt automatisch verzonden zodra de template is goedgekeurd; roep de startfunctie niet opnieuw aan.

Alleen een Draft (of een Pending Approval-broadcast waarvan de template in de tussentijd is goedgekeurd) kan worden gestart — al het andere retourneert 400.

Waarom een start wordt geweigerd #

Elk van deze wordt geretourneerd als 400 met een error-bericht in begrijpelijke taal:

Pauzeren en hervatten #

POST /broadcasts/{broadcastId}/pause stopt een Sending- of Scheduled-broadcast en verwijdert alles wat in de wachtrij staat.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"

Het pauzeren van een Pending Approval-uitzending zet deze terug naar Draft — er was nog niets gepland, dus er is niets om naar te hervatten. Elke andere status keert terug naar 400.

POST /broadcasts/{broadcastId}/resume herstart een Paused-uitzending:

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

Antwoord (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

Het hervat naar Sending, of terug naar Scheduled als de execution_date nog in de toekomst ligt. Alleen een Paused-uitzending kan worden hervat.

Blijven verzenden na een pauze vanwege lage betrokkenheid #

POST /broadcasts/{broadcastId}/override-engagement-guard

Terwijl een uitzending in batches wordt verzonden, meten we hoeveel mensen op elke batch hebben gereageerd voordat de volgende wordt gestart. Als bijna niemand reageert, pauzeert de uitzending zichzelf — een verzending die blijft pushen in stilte is de snelste manier om een nummer gefilterd of geblokkeerd te krijgen. Dit is de knop Toch doorgaan in het dashboard.

Omdat het antwoordpercentage dat de pauze veroorzaakte niet kan veranderen terwijl de uitzending is gestopt, zou een gewone hervatting bij de volgende controle gewoon weer worden gepauzeerd. Dit eindpunt is de beslissing om toch door te gaan: het registreert de overschrijving op die ene uitzending en heft de pauze op in dezelfde aanroep als de uitzending was gepauzeerd vanwege lage betrokkenheid.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

Antwoord (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

• resumed: true — de uitzending was gepauzeerd vanwege lage betrokkenheid en draait nu weer; status is waar deze naar is hervat.
• resumed: false — er is niets opgeheven, de overschrijving wordt simpelweg geregistreerd voor toekomstige controles. Dat is wat je krijgt als de uitzending nooit was gepauzeerd, of was gepauzeerd om een andere reden (je hebt het handmatig gepauzeerd, een verzendlimiet is bereikt, of er zijn te veel verzendfouten opgetreden). Die pauzes worden hier niet opgeheven — hervat het zelf zodra je de oorzaak hebt aangepakt.

De overschrijving is alleen van toepassing op deze uitzending. Het is geen accountinstelling en het is veilig om deze twee keer aan te roepen.

Een uitzending dupliceren #

POST /broadcasts/{broadcastId}/duplicate — kopieert het publiek, het bericht en de instellingen naar een nieuwe Draft. Alles van de vorige run (tellers, batches, planning, antwoordstatistieken) begint opnieuw.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

Antwoord (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

Een kopie neemt nooit een live WhatsApp-goedkeuring over: bij een WhatsApp-kopie moet de sjabloon door jou worden bevestigd, en bij een kopie naar een ander kanaal wordt deze verwijderd en wordt de tekst de gewone opener. Kopiëren naar sms verwijdert ook eventuele bijlagen, aangezien sms deze niet kan verzenden.

Een uitzending verwijderen #

DELETE /broadcasts/{broadcastId}

curl -X DELETE "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Een Sending of Scheduled uitzending wordt geweigerd met 400 — pauzeer deze eerst.

Uitzendingen die een klassieke campagne spiegelen #

Klassieke campagnes die berichten versturen verschijnen ook in Uitzendingen, en de API retourneert ze naast native uitzendingen (ze bevatten een source_campaign_id). Ze gedragen zich iets anders, omdat de campagne de leiding behoudt:

• Het bewerken van het publiek, bericht of schema werkt en wordt doorgevoerd naar de campagne.
• Kanaal, antwoord-Agent, bijlage en alle run-tellers zijn hier alleen-lezen — 400 als u probeert deze te wijzigen. Wijzig deze in de campagne.
• Starten retourneert 400 die u naar de campagne-editor verwijst.
• Pauzeren en hervatten werken en zijn van invloed op de campagne.
• Verwijderen retourneert 400 — verwijder in plaats daarvan de campagne, dan verdwijnt het bijbehorende item in Uitzendingen ook.
• Dupliceren geeft u een onafhankelijke native uitzending, wat de ondersteunde manier is om een bewezen campagne over te zetten.

Fouten #

Mislukte verzoeken retourneren {"success": false, "error": "<message>"} met deze statussen:

Volgende stappen #

• Uitzendingen-gids — het product achter deze endpoints, inclusief tempo en veiligheidsgedrag
• Contacten-API — bouw de lijst waarnaar een uitzending verzendt
• Sjablonen-API — beheer de goedgekeurde WhatsApp-sjablonen waaruit u kunt kiezen
• Webhooks-API — abonneer u op Broadcast Started en Broadcast Completed in plaats van te pollen