Broadcasts-API #

En broadcast (utskick) är en utgående sändning: en målgrupp, ett öppningsmeddelande, en kanal och ett schema. Valfritt kan du även ange den AI-agent som hanterar svaren som kommer in. Broadcasts-API:et låter dig bygga, prissätta, starta och övervaka dessa sändningar från din egen kod istället för via kontrollpanelen. För själva produkten, se Broadcasts-guiden.

• Bas-URL — https://api.youraiconnector.com/v1
• Autentisering — din API-nyckel (se Autentisering)
• Fel och sidnumrering — se Fel och sidnumrering

Alla exempel nedan visar frågeformuläret ?apiKey= i cURL och headern X-API-Key i JavaScript och Python — båda fungerar på alla slutpunkter.

I API-utforskaren. Varje slutpunkt på denna sida finns i den publicerade OpenAPI-specifikationen, så att du kan bläddra bland dess exakta fält och köra live-anrop i API-utforskaren.

Hur en sändning sätts samman #

Att skicka en broadcast kräver fyra anrop, inte ett:

1. Skapa broadcasten med dess målgrupp, kanal och schema — den börjar som ett Draft.
2. Ställ in öppningsmeddelandet. På WhatsApp Business innebär det att skicka in en mall för godkännande (eller välja en som redan är godkänd). På alla andra kanaler är det vanlig text.
3. Beräkna kostnaden om du vill kontrollera priset innan du spenderar något (valfritt).
4. Starta den. Starten kör en fullständig kontroll — målgrupp, meddelande, mallgodkännande, ansluten avsändare — och antingen påbörjar sändningen eller talar om exakt vad som saknas.

Ingenting skickas förrän du anropar 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
}

Tidsstämplar returneras som epok-millisekunder (execution_date, created_at, last_modified_at, …), och alla kontaktreferenser returneras som en sökvägssträng som contacts/uid_whatsapp_15551234567.

Fält du anger #

Allt du skickar som user_id, id, status eller source_campaign_id ignoreras vid skapande och tas bort vid uppdatering — statusen ändras endast via slutpunkterna för start, paus och återuppta nedan.

Fält som plattformen underhåller #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, omgångsräknarna och contacts (de enskilda kontakterna som bifogats från kontrollpanelen, läses tillbaka som sökvägssträngar). Läs dem, skriv inte till dem.

Statusar #

Skapa en sändning #

POST /broadcasts — skapar 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" }

Lista sändningar #

GET /broadcasts — varje sändning på kontot, den nyaste först.

Frågeparametrar

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", "...": "..." }] }

Hämta en sändning #

GET /broadcasts/{broadcastId} — returnerar { "success": true, "broadcast": { ... } }. Använd den för att avläsa en pågående sändning: total_contacts_sent, unique_contacts_replied, overall_reply_rate och credits_used uppdateras allt eftersom. |

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

En sändning som inte finns på ditt konto returnerar 404.

Uppdatera en sändning #

PUT /broadcasts/{broadcastId} — skicka endast de fält du vill ändra. Du kan också adressera en enskild nyckel inuti ett nästlat objekt med en punktnotation, t.ex. "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 brödtext returnerar 400. Två regler som är värda att känna till:

• opener_media är allt-eller-inget. Skicka det fullständiga objektet, eller null för att ta bort bilagan. En punktnotation in i den (opener_media.name) avvisas med 400, eftersom en delvis uppdaterad bilaga skulle beskriva en fil som inte finns.
• Status kan inte redigeras. Använd lansera, pausa och återuppta.

Öppningsmeddelandet #

Varje sändning bär sin inledning i whats_app_template. Vad det innebär beror på kanalen:

• WhatsApp Business — det måste vara en mall som WhatsApp har godkänt. Använd en av de två slutpunkterna nedan.
• Alla andra kanaler (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — samma fälts body är helt enkelt texten som skickas. Att skicka in den via slutpunkten nedan lagrar den och markerar den som klar utan att involvera WhatsApp överhuvudtaget.

Skicka in en mall för godkännande #

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 är vad WhatsApp säger: pending medan den granskas, approved när den är användbar, rejected om den nekades. På en kanal som inte är WhatsApp kommer den direkt tillbaka som approved med template_sid: null — ingenting att granska.

Saker som kommer att stoppa dig:

• Att skicka in medan en tidigare mall fortfarande granskas returnerar 400. Vänta på beslutet först.
• Att redigera en mall som för närvarande är godkänd håller den godkända versionen aktiv tills den nya kommer tillbaka, så en pågående sändning förlorar aldrig sin inledning.
• På ett WhatsApp-nummer som är anslutet direkt via Meta kan en sändning med en bifogad bild eller video inte skickas in (400) — bilagor stöds på den hanterade WhatsApp Business-kanalen och på WhatsApp Web.

Använd en mall som du redan har fått godkänd #

POST /broadcasts/{broadcastId}/template/select — kopierar en redan godkänd mall från ditt mallbibliotek till sändningen, så det finns inget att vänta 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"
}

Godkännandet verifieras på vår sida från biblioteksposten — du skickar bara ID:t. Du får ett 400 om sändningen inte är ett WhatsApp-utkast, om mallen inte är godkänd, om det är en uppföljningsmall snarare än en inledning, eller om sändningen har en bilaga (biblioteksmallar är endast text). Ett mall-ID som inte finns på ditt konto returnerar 404.

Beräkna kostnaden #

POST /broadcasts/{broadcastId}/estimate-cost — prissätter sändningen innan du förbinder dig till den. Tillgängligt på whatsapp och sms sändningar; alla andra kanaler returnerar 400. Sändningen behöver en list_id, eftersom uppskattningen räknar målgruppen.

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

WhatsApp-svar (200) — krediter, uppdelat per 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) — amerikanska dollar, baserat på aktuell Twilio-prissättning för ditt eget 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 innan du visar ett nummer. Den talar om för dig vem som faktureras:

SMS utan anslutna Twilio-uppgifter returnerar fortfarande segmentantalet, med estimatedCostUsd: 0 — det finns ingen prissättning att slå upp.

Starta en sändning #

POST /broadcasts/{broadcastId}/launch

Starten kontrollerar allt först och går sedan vidare med sändningen. Det finns ingen partiell start: antingen startar den, eller så ändras ingenting och du får ett felmeddelande som förklarar varför.

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 är där sändningen hamnade:

• Scheduled — execution_date ligger i framtiden.
• Sending — den startade nu.
• Pending Approval — WhatsApp-mallen granskas fortfarande. Den skickas automatiskt så snart mallen har godkänts; anropa inte start igen.

Endast en Draft (eller en Pending Approval-sändning vars mall har godkänts sedan dess) kan startas — allt annat returnerar 400.

Varför en start nekas #

Var och en av dessa returneras som 400 med ett error-meddelande på vanligt språk:

Pausa och återuppta #

POST /broadcasts/{broadcastId}/pause stoppar en Sending- eller Scheduled-sändning och rensar allt som ligger i kö.

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

Att pausa en Pending Approval-sändning återställer den till Draft istället — ingenting var schemalagt ännu, så det finns inget att återuppta till. Alla andra statusar returnerar 400.

POST /broadcasts/{broadcastId}/resume startar om en Paused-sändning:

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

Svar (200)

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

Den återupptas till Sending, eller tillbaka till Scheduled om dess execution_date fortfarande ligger i framtiden. Endast en Paused-sändning kan återupptas.

Fortsätt skicka efter en paus på grund av lågt engagemang #

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

Medan en sändning skickas i omgångar mäter vi hur många som svarade på varje omgång innan nästa påbörjas. Om nästan ingen svarar pausas sändningen automatiskt — en sändning som fortsätter att skicka ut i tystnad är det snabbaste sättet att få ett nummer filtrerat eller blockerat. Det är knappen Fortsätt ändå i kontrollpanelen.

Eftersom svarsfrekvensen som orsakade pausen inte kan ändras medan sändningen är stoppad, skulle en vanlig återuppta bara pausas igen vid nästa kontroll. Denna slutpunkt är beslutet att fortsätta ändå: den registrerar åsidosättandet för den specifika sändningen och häver pausen i samma anrop om sändningen pausades på grund av lågt engagemang.

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 — sändningen pausades på grund av lågt engagemang och körs nu igen; status är där den återupptogs till.
• resumed: false — ingenting hävdes, åsidosättandet registreras helt enkelt för framtida kontroller. Det är vad du får om sändningen aldrig pausades, eller pausades av en annan anledning (du pausade den manuellt, en sändningsgräns nåddes eller för många sändningar gav fel). Dessa pauser hävs inte här — återuppta den själv när du har hanterat orsaken.

Åsidosättandet gäller endast för denna sändning. Det är inte en kontoinställning, och det är säkert att anropa två gånger.

Duplicera en sändning #

POST /broadcasts/{broadcastId}/duplicate — kopierar målgrupp, meddelande och inställningar till en ny Draft. Allt som rör den tidigare körningen (räknare, omgångar, schema, svarsstatistik) börjar om från början.

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 kopia ärver aldrig ett aktivt WhatsApp-godkännande: på en WhatsApp-kopia kommer mallen över och kräver din bekräftelse, och vid en kopia till en annan kanal tas den bort och texten blir den vanliga inledningen. Kopiering till SMS tar även bort eventuella bilagor, eftersom SMS inte kan skicka sådana.

Ta bort en sändning #

DELETE /broadcasts/{broadcastId}

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

En Sending eller Scheduled-sändning nekas med 400 — pausa den först.

Sändningar som speglar en klassisk kampanj #

Klassiska kampanjer som skickar meddelanden visas även i Sändningar, och API:et returnerar dem tillsammans med inbyggda sändningar (de har en source_campaign_id). De fungerar lite annorlunda eftersom kampanjen fortfarande har kontrollen:

• Redigering av målgrupp, meddelande eller schema fungerar och skrivs över till kampanjen.
• Kanal, svarsagent, bilaga och alla körningsräknare är skrivskyddade här — 400 om du försöker ändra dem. Ändra dem i kampanjen.
• Starta returnerar 400 som hänvisar dig till kampanjredigeraren.
• Pausa och återuppta fungerar och påverkar kampanjen.
• Ta bort returnerar 400 — ta bort kampanjen istället, så försvinner även dess sändningspost.
• Duplicera ger dig en oberoende inbyggd sändning, vilket är det rekommenderade sättet att flytta en beprövad kampanj.

Fel #

Misslyckade förfrågningar returnerar {"success": false, "error": "<message>"} med dessa statusar:

Nästa steg #

• Guide för sändningar — produkten bakom dessa slutpunkter, inklusive takt och säkerhetsbeteende
• Kontakter-API — bygg listan som en sändning skickas till
• Mallar-API — hantera de godkända WhatsApp-mallar du kan välja mellan
• Webhooks-API — prenumerera på Broadcast Started och Broadcast Completed istället för att polla