Broadcasts API #

En broadcast er én udgående afsendelse: et publikum, en åbningsbesked, én kanal og en tidsplan. Valgfrit navngiver den også den AI-agent, der håndterer de svar, der kommer retur. Broadcasts API’et lader dig oprette, prissætte, starte og overvåge disse afsendelser fra din egen kode i stedet for fra dashboardet. For selve produktet, se Broadcasts-guiden.

• Base URL — https://api.youraiconnector.com/v1
• Autentificering — din API-nøgle (se Autentificering)
• Fejl & paginering — se Fejl & Paginering

Alle eksempler herunder viser ?apiKey= forespørgselsformen i cURL og X-API-Key headeren i JavaScript og Python — begge virker på alle slutpunkter.

I API-udforskeren. Hvert endpoint på denne side findes i den publicerede OpenAPI-specifikation, så du kan gennemse dens præcise felter og køre live-forespørgsler i API-udforskeren.

Hvordan en afsendelse sammensættes #

At sende en broadcast kræver fire kald, ikke ét:

1. Opret broadcasten med dens publikum, kanal og tidsplan — den starter som en Draft.
2. Indstil åbningsbeskeden. På WhatsApp Business betyder det at indsende en skabelon til godkendelse (eller vælge en, du allerede har fået godkendt). På alle andre kanaler er det almindelig tekst.
3. Estimer omkostningen, hvis du vil tjekke prisen, før du bruger noget (valgfrit).
4. Start den. Start-handlingen kører et fuldt tjek — publikum, besked, skabelongodkendelse, forbundet afsender — og starter enten afsendelsen eller fortæller dig præcis, hvad der mangler.

Intet bliver sendt, før du kalder start.

Broadcast-objektet #

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

Tidsstempler returneres som epoch-millisekunder (execution_date, created_at, last_modified_at, …), og enhver kontaktreference returneres som en stistreng som contacts/uid_whatsapp_15551234567.

Felter du indstiller #

Alt, hvad du sender som user_id, id, status eller source_campaign_id, ignoreres ved oprettelse og fjernes ved opdatering — status bevæger sig kun gennem start-, pause- og genoptag-endpoints nedenfor.

Felter platformen vedligeholder #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, batch-tællerne og contacts (de individuelle kontakter tilknyttet fra dashboardet, læst tilbage som stistrenge). Læs dem, skriv ikke til dem.

Statusser #

Opret en udsendelse #

POST /broadcasts — opretter en Draft.

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

Svar (201)

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

List udsendelser #

GET /broadcasts — hver udsendelse på kontoen, nyeste først.

Forespørgselsparametre

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

Svar (200)

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

Hent en udsendelse #

GET /broadcasts/{broadcastId} — returnerer { "success": true, "broadcast": { ... } }. Brug den til at forespørge på en igangværende afsendelse: total_contacts_sent, unique_contacts_replied, overall_reply_rate og credits_used opdateres løbende. |

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

En udsendelse, der ikke findes på din konto, returnerer 404.

Opdater en udsendelse #

PUT /broadcasts/{broadcastId} — send kun de felter, du ønsker at ændre. Du kan også adressere en enkelt nøgle inde i et indlejret objekt med en punktum-sti, f.eks. "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" }),
});

En tom krop returnerer 400. To regler, der er værd at kende:

• opener_media er alt-eller-intet. Send det komplette objekt, eller null for at fjerne vedhæftningen. En punktum-sti ind i den (opener_media.name) afvises med 400, fordi en delvist opdateret vedhæftning ville beskrive en fil, der ikke er der.
• Status kan ikke redigeres. Brug lancering, pause og genoptag.

Åbningsbeskeden #

Hver udsendelse har sin åbner i whats_app_template. Hvad det betyder, afhænger af kanalen:

• WhatsApp Business — det skal være en skabelon, som WhatsApp har godkendt. Brug et af de to endpoints nedenfor.
• Alle andre kanaler (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — det samme felts body er blot den tekst, der sendes. Ved at indsende den via endpointet nedenfor gemmes den og markeres som klar uden at involvere WhatsApp overhovedet.

Indsend en skabelon til godkendelse #

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

Svar (200)

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

template_status er hvad WhatsApp siger: pending mens den bliver gennemset, approved når den er klar til brug, rejected hvis den blev afvist. På en ikke-WhatsApp-kanal kommer den direkte tilbage som approved med template_sid: null — intet der skal gennemses.

Ting der vil stoppe dig:

• Indsendelse mens en tidligere skabelon stadig er under gennemgang returnerer 400. Vent på afgørelsen først.
• Redigering af en skabelon, der i øjeblikket er godkendt, holder den godkendte version aktiv, indtil den nye kommer tilbage, så en kørende udsendelse aldrig mister sin åbner.
• På et WhatsApp-nummer, der er forbundet direkte via Meta, kan en udsendelse med et vedhæftet billede eller video ikke indsendes (400) — vedhæftede filer understøttes på den administrerede WhatsApp Business-linje og på WhatsApp Web.

Brug en skabelon, du allerede har fået godkendt #

POST /broadcasts/{broadcastId}/template/select — kopierer en allerede godkendt skabelon fra dit skabelonbibliotek til udsendelsen, så der er intet at vente på.

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

Svar (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"
}

Godkendelsen verificeres på vores side ud fra biblioteksposten — du sender kun id’et. Du får en 400, hvis udsendelsen ikke er et WhatsApp-udkast, hvis skabelonen ikke er godkendt, hvis det er en opfølgningsskabelon frem for en åbner, eller hvis udsendelsen har en vedhæftet fil (biblioteksskabeloner er kun tekst). Et skabelon-id, der ikke findes på din konto, returnerer 404.

Estimer omkostningerne #

POST /broadcasts/{broadcastId}/estimate-cost — prissætter afsendelsen, før du forpligter dig til den. Tilgængelig på whatsapp og sms udsendelser; enhver anden kanal returnerer 400. Udsendelsen kræver en list_id, da estimatet tæller modtagerne.

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

WhatsApp-svar (200) — kreditter, opdelt efter destinationsland:

{
  "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-svar (200) — amerikanske dollars, baseret på live Twilio-priser for din egen Twilio-konto:

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

Læs billing_mode før du viser et nummer. Det fortæller dig, hvem der bliver faktureret:

SMS uden tilsluttede Twilio-legitimationsoplysninger returnerer stadig segmentantallet med estimatedCostUsd: 0 — der er ingen priser at slå op.

Start en udsendelse #

POST /broadcasts/{broadcastId}/launch

Start-processen tjekker alt først og går derefter videre med udsendelsen. Der findes ingen delvis start: enten starter den, eller også ændres intet, og du får en fejlmeddelelse, der forklarer hvorfor.

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())

Svar (200)

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

status er hvor udsendelsen landede:

• Scheduled — execution_date ligger i fremtiden.
• Sending — den startede nu.
• Pending Approval — WhatsApp-skabelonen er stadig til gennemsyn. Den sendes automatisk, så snart skabelonen er godkendt; kald ikke start igen.

Kun en Draft (eller en Pending Approval-udsendelse, hvis skabelon siden er blevet godkendt) kan startes — alt andet returnerer 400.

Hvorfor en start afvises #

Hver af disse kommer tilbage som 400 med en letforståelig error-besked:

Pause og genoptag #

POST /broadcasts/{broadcastId}/pause stopper en Sending- eller Scheduled-udsendelse og fjerner alt, der ligger i kø.

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

Hvis du sætter en Pending Approval-udsendelse på pause, føres den tilbage til Draft i stedet – intet var planlagt endnu, så der er intet at genoptage. Enhver anden status returnerer 400.

POST /broadcasts/{broadcastId}/resume genstarter en Paused-udsendelse:

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

Svar (200)

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

Den genoptages i Sending eller tilbage i Scheduled, hvis dens execution_date stadig ligger i fremtiden. Kun en Paused-udsendelse kan genoptages.

Fortsæt afsendelse efter pause pga. lavt engagement #

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

Mens en udsendelse sendes i batches, måler vi, hvor mange personer der svarede på hver batch, før vi starter den næste. Hvis næsten ingen svarer, sætter udsendelsen sig selv på pause – en afsendelse, der bliver ved med at sende ud i stilhed, er den hurtigste måde at få et nummer filtreret eller blokeret på. Det er knappen Fortsæt alligevel i dashboardet.

Da svarraten, der forårsagede pausen, ikke kan ændre sig, mens udsendelsen er stoppet, ville en almindelig genoptagelse bare blive sat på pause igen ved næste tjek. Dette endpoint er beslutningen om at fortsætte alligevel: Det registrerer tilsidesættelsen på den pågældende udsendelse og ophæver pausen i samme kald, hvis udsendelsen var sat på pause pga. lavt engagement.

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

Svar (200)

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

• resumed: true – udsendelsen blev sat på pause pga. lavt engagement og kører nu igen; status er der, hvor den blev genoptaget.
• resumed: false – intet blev ophævet, tilsidesættelsen er blot registreret til fremtidige tjek. Det er, hvad du får, hvis udsendelsen aldrig blev sat på pause, eller blev sat på pause af en anden årsag (du satte den manuelt på pause, en afsendelsesgrænse blev nået, eller for mange afsendelser fejlede). Disse pauser ophæves ikke her – genoptag den selv, når du har håndteret årsagen.

Tilsidesættelsen gælder kun for denne udsendelse. Det er ikke en kontoindstilling, og det er sikkert at kalde den to gange.

Dupliker en udsendelse #

POST /broadcasts/{broadcastId}/duplicate – kopierer målgruppen, beskeden og indstillingerne til en ny Draft. Alt vedrørende den forrige kørsel (tællere, batches, tidsplan, svarstatistik) starter forfra.

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

Svar (201)

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

En kopi arver aldrig en live WhatsApp-godkendelse: På en WhatsApp-kopi skal skabelonen bekræftes af dig, og ved en kopi til en anden kanal fjernes den, og teksten bliver til den almindelige åbner. Kopiering til SMS fjerner også eventuelle vedhæftede filer, da SMS ikke kan sende dem.

Slet en udsendelse #

DELETE /broadcasts/{broadcastId}

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

En Sending eller Scheduled udsendelse afvises med 400 — sæt den på pause først.

Udsendelser, der spejler en klassisk kampagne #

Klassiske kampagner, der sender beskeder, vises også i Udsendelser, og API’et returnerer dem sammen med native udsendelser (de bærer et source_campaign_id). De opfører sig lidt anderledes, fordi kampagnen forbliver ansvarlig:

• Redigering af målgruppe, besked eller tidsplan fungerer og skrives direkte til kampagnen.
• Kanal, svar-agent, vedhæftet fil og alle kørselstællere er skrivebeskyttede her — 400 hvis du forsøger at ændre dem. Skift dem i kampagnen.
• Start returnerer 400, der henviser dig til kampagneditoren.
• Pause og genoptag fungerer og påvirker kampagnen.
• Slet returnerer 400 — slet kampagnen i stedet, så forsvinder dens Udsendelser-post sammen med den.
• Dupliker giver dig en uafhængig native udsendelse, hvilket er den understøttede måde at flytte en gennemprøvet kampagne på.

Fejl #

Mislykkede anmodninger returnerer {"success": false, "error": "<message>"} med disse statusser:

Næste skridt #

• Guide til udsendelser — produktet bag disse endpoints, inklusive tempo og sikkerhedsadfærd
• Kontakter API — opbyg listen, som en udsendelse sendes til
• Skabeloner API — administrer de godkendte WhatsApp-skabeloner, du kan vælge imellem
• Webhooks API — abonner på Broadcast Started og Broadcast Completed i stedet for at polle