Campaigns API #

Een campagne bundelt alles wat de AI-bot nodig heeft om met je contacten te praten: de instructies, de kanalen waarop deze actief is, de actieve uren en het follow-upgedrag. Met de Campaigns API kun je campagnes vanuit je eigen code vermelden, aanmaken, bijwerken, dupliceren, inschakelen, archiveren en verfijnen in plaats van via het dashboard.

Alle onderstaande endpoints zijn relatief ten opzichte van de basis-URL https://api.youraiconnector.com/v1. Elk verzoek moet worden geverifieerd — zie API Access en Authentication voor hoe je je API-sleutel verkrijgt en doorgeeft. API-toegang is een betaalde functie; zonder deze toegang worden verzoeken afgewezen met een 403.

Let op: Sommige voorbeelden tonen de eenvoudige ?apiKey=YOUR_API_KEY query-vorm, andere gebruiken de X-API-Key header. Beide werken overal — gebruik wat het beste bij je configuratie past.

Campagnetypen #

Wanneer je een campagne aanmaakt, moet je een van deze typen kiezen:

Hoofdlettergebruik maakt niet uit. type, status, booking_provider, first_response_mode, bot.anthropic_model en bot.ai_speed accepteren allemaal elk hoofdlettergebruik — "live", "Live" en "LIVE" zijn hetzelfde — en de waarde wordt opgeslagen in de canonieke vorm, wat de waarde is die je terugkrijgt wanneer je de campagne leest. De enige uitzondering is het pauzepaar: "Paused" en "paused" zijn twee wezenlijk verschillende statussen, dus een dubbelzinnige spelling zoals "PAUSED" wordt afgewezen met een 400 waarin je wordt gevraagd er een te kiezen.

De twee pauzestatussen #

Beide stoppen de campagne: inkomende routering werkt alleen terwijl de status exact Live is. Gebruik vanuit de API Paused om te pauzeren en Live om te hervatten — het paar met kleine letters bestaat voor de dashboardknop en blijft daarvoor werken.

Geen van beide is wat er gebeurt wanneer de AI stopt met antwoorden binnen één gesprek. Dat is een schakelaar per contact, is_bot_active op het contact — ingesteld wanneer een mens het overneemt, wanneer het contact zich afmeldt, of wanneer de AI de chat beëindigt. De status van de campagne zelf blijft onaangeroerd en elk ander gesprek daarin blijft doorgaan. Zie de AI pauzeren of hervatten voor één contact.

Het aanmaken van een campagne bepaalt niet wie een kanaal beantwoordt. Routering wordt afgehandeld door Entry Points op een AI Agent, niet door campagnes. Elk kanaal heeft een standaard Entry Point dat de Agent benoemt die nieuwe, onbekende contacten op dat kanaal beantwoordt: stel dit in met PUT /entry-points/channel-defaults, controleer of de ladder live is voor het account met GET /entry-points/routing-status, wis het met DELETE /entry-points/channel-defaults. POST /channels/campaign schrijft nog steeds de verouderde per-kanaal campagnerouteringskaart, maar die kaart wordt niet langer geraadpleegd voor inkomende routering op enig account; deze wordt alleen bewaard voor rollback. Bouw hier niet op voort. Zie Routeer een kanaal naar een campagne voor beide oppervlakken naast elkaar.

Campagnes vermelden #

GET /campaigns

Geeft je campagnes terug, de nieuwste eerst. Gearchiveerde campagnes zijn uitgesloten, tenzij je archived=true doorgeeft.

Queryparameters

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])

Antwoord

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

Wanneer next_cursor gelijk is aan null, heb je de laatste pagina bereikt.

Een campagne ophalen #

GET /campaigns/{campaignId}

Geeft het volledige campagnedocument terug, inclusief de live bot-configuratie (bot), follow-up instellingen, ingeschakelde kanalen en eventuele trefwoorden. Tijdstempels worden geretourneerd als epoch-milliseconden.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]

Antwoord

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

Een campagne aanmaken #

POST /campaigns

Maakt een nieuwe campagne aan. name en type zijn vereist; al het overige is optioneel. Je kunt elk ander campagneveld in hetzelfde verzoek opnemen — bijvoorbeeld language, ai_mode of een volledig bot configuratieobject — en dit wordt opgeslagen bij de nieuwe campagne. De eigenaar en aanmaaktijd worden automatisch ingesteld.

Aanvraagvelden

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Een campagne bijwerken #

PUT /campaigns/{campaignId}

Werkt een campagne gedeeltelijk bij — stuur alleen de velden die u wilt wijzigen. Dit is het enige algemene update-werkwoord; er is geen PATCH /campaigns/{campaignId} (de twee PATCH routes zijn de specifieke inschakelen en archiveren schakelaars).

Welke velden u kunt wijzigen. Alles wat de campagne-editor schrijft, inclusief name, status, type, language, ai_mode, enabled_channels, de trigger- en drip-instellingen, de boekings- en follow-up-vlaggen, de Instagram/Facebook-monitoringsvelden en de volledige bot configuratie. Identiteit en eigendom zijn vergrendeld voor de levensduur van de campagne: user, id en created_at worden geweigerd, evenals elke veldnaam die het eindpunt niet herkent. Afwijzing is per verzoek, niet per veld — één onbekende sleutel retourneert een 400 en niets in dat verzoek wordt geschreven.

ai_mode bij een campagne ondersteund door een Agent weerspiegelt de Agent. Wanneer een campagne wordt beantwoord door een AI-agent, geeft het lezen van de campagne ai_mode terug die is afgeleid van de Actief-schakelaar van die Agent — de enige schakelaar die daadwerkelijk bepaalt of de AI antwoordt. Het schrijven van ai_mode bij een dergelijke campagne wordt geaccepteerd, maar verandert niets aan wat u terugleest; schakel in plaats daarvan de Actief-schakelaar van de Agent in of uit (in het dashboard of via de Agents API). Bij klassieke campagnes zonder Agent leest en schrijft ai_mode de opgeslagen waarde zoals voorheen.

Bot-velden worden samengevoegd, ze worden niet overschreven. Stuur bot-instellingen als punt-sleutels ("bot.instructions": "...") of als een genest object ("bot": { "instructions": "..." }) — beide schrijven blad voor blad, dus de velden die u weglaat behouden hun huidige waarden. bot.instructions, bot.goal, bot.rules en bot.personality zijn allemaal op deze manier bewerkbaar, evenals elke andere bot-instelling die wordt vermeld onder Bot-configuratievelden. Hetzelfde geldt voor test_bot, frequency en follow_up_config.

Om een bot-configuratie volledig te vervangen — waarbij elk veld dat u niet verstuurt wordt verwijderd — gebruikt u bot_replace (of test_bot_replace) met het volledige object. U kunt een vervanging en een samenvoeging voor hetzelfde object niet combineren in één verzoek; dat retourneert een 400.

Een paar velden worden ingesteld via een speciale sleutel in plaats van direct geschreven: gebruik list_id voor de contactenlijst, event_id voor het gebeurtenistype (of event_ids, een geordende array van gebeurtenistype-ID’s, om de AI er meerdere te laten boeken — de eerste is de standaard; een lege array ontkoppelt ze allemaal), en contact_ids (een array van contact-ID’s) voor de contacten van de campagne. Knowledge-base-items worden beheerd via de FAQs API, niet via dit eindpunt.

Tags vervangen, ze worden niet samengevoegd. Stuur tags als de volledige array en dit wordt de tagset van de campagne — zie Campagnetags voor de velden en voor de eindpunten die een enkele tag toevoegen of bewerken.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Een campagne verwijderen #

DELETE /campaigns/{campaignId}

Verwijdert een campagne definitief. Dit kan niet ongedaan worden gemaakt — als je de campagne later misschien nog nodig hebt, archiveer deze dan in plaats daarvan.

cURL

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

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Antwoord

{
  "success": true
}

Een campagne dupliceren #

POST /campaigns/{campaignId}/duplicate

Maakt een kopie van de campagne waarbij alle instellingen behouden blijven. De kopie begint als uitgeschakeld en de naam krijgt een (copy) achtervoegsel, zodat er nooit berichten worden verzonden totdat je deze expliciet inschakelt.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

Antwoord

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

Dubbele kopieën binnen één account.

Een campagne in- of uitschakelen #

PATCH /campaigns/{campaignId}/enabled

Schakelt een campagne in of uit. Een uitgeschakelde campagne stopt met het benaderen van contactpersonen, maar behoudt al zijn configuratie.

Aanvraagvelden

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

Een campagne archiveren of herstellen #

PATCH /campaigns/{campaignId}/archived

Archiveert of herstelt een campagne. Gearchiveerde campagnes worden verborgen in de standaard campagnelijst, maar behouden al hun gegevens en kunnen op elk gewenst moment worden hersteld.

Aanvraagvelden

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

De botconfiguratie bijwerken #

PUT /campaigns/{campaignId}/bot-config

Dit is de veilige manier om individuele botinstellingen te wijzigen. Elk veld dat u verstuurt, wordt samengevoegd met de bestaande botconfiguratie, dus alle velden die u weglaat, blijven behouden. Gebruik dit in plaats van het campaign-update-eindpunt wanneer u slechts een deel van de bot wilt aanpassen.

Veldnamen mogen alleen letters, cijfers, underscores en koppeltekens bevatten.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Botconfiguratievelden #

Alle botvelden zijn optioneel. Stuur alleen de velden die u wilt instellen. Eventuele extra botvelden buiten de hier vermelde velden worden geaccepteerd en ongewijzigd opgeslagen.

De actieve uren van de bot instellen #

PUT /campaigns/{campaignId}/active-hours

Stelt het beschikbaarheidsschema van de bot in. Buiten de geconfigureerde vensters antwoordt de bot niet automatisch. Dit schrijft naar het availability-veld van de botconfiguratie.

Aanvraagvelden

Elke weekdag bevat ofwel een enkel tijdvenster of een reeks vensters. Een venster heeft een start_time en end_time in 24-uurs HH:MM-indeling.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Aangepaste functies van een campagne weergeven #

GET /campaigns/{campaignId}/custom-functions

Geeft de aangepaste functies terug die aan deze campagne zijn gekoppeld, opgelost naar volledige definities. Aangepaste functies zijn externe HTTP-acties die de bot tijdens een gesprek kan aanroepen — bijvoorbeeld het controleren van de voorraad in uw winkel of het aanmaken van een record in uw CRM.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

Antwoord

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

Een aangepaste functie koppelen aan een campagne #

POST /campaigns/{campaignId}/custom-functions

Koppelt een bestaande aangepaste functie aan deze campagne, zodat de bot deze tijdens een gesprek kan aanroepen. Het koppelen van een functie die al is gekoppeld, heeft geen effect.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Een aangepaste functie ontkoppelen van een campagne #

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

Het ontkoppelen van een functie die niet is gekoppeld, heeft geen effect.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Een kennisbron koppelen aan een campagne #

POST /campaigns/{campaignId}/kb-sources

Koppelt een kennisbron (gemaakt via de FAQ-API) aan deze campagne, zodat de bot deze kan gebruiken bij het beantwoorden van vragen. Het koppelen van een bron die al is gekoppeld, heeft geen effect.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Een kennisbron ontkoppelen van een campagne #

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

Het ontkoppelen van een bron die niet is gekoppeld, heeft geen effect.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Een MCP-server koppelen aan een campagne #

POST /campaigns/{campaignId}/mcp-servers

Koppelt een MCP-server aan deze campagne, waardoor de bot tijdens een gesprek toegang krijgt tot de tools van die server. Het koppelen van een server die al gekoppeld is, heeft geen effect.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Een MCP-server ontkoppelen van een campagne #

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

Het ontkoppelen van een server die niet gekoppeld is, heeft geen effect.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Mediatheek van de campagne #

De mediatheek bevat afbeeldingen, video’s, documenten en spraakberichten die de bot tijdens een gesprek kan versturen.

De mediatheek van een campagne weergeven #

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url is een ondertekende URL die is vastgelegd op het moment van uploaden — deze kan al verlopen zijn tegen de tijd dat u deze terugleest; het dashboard ondertekent deze opnieuw op aanvraag.

Een mediabestand uploaden #

POST /campaigns/{campaignId}/media-library

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

Antwoord

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

Een media-item bijwerken #

PATCH /campaigns/{campaignId}/media-library/{itemId}

Wijzigt alleen de metadata van het item — om het bestand zelf te vervangen, verwijdert u het item en uploadt u een nieuwe.

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

Een media-item verwijderen #

DELETE /campaigns/{campaignId}/media-library/{itemId}

Het verwijderen van een item dat al weg is, heeft geen effect.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

Antwoord

{ "success": true, "deleted": true }

Campagnetags #

Een campagnetag is een label dat je de bot leert toe te passen op een contactpersoon tijdens een gesprek — hot-lead, not-interested, booked-a-call. Elke tag bestaat uit drie delen:

Tagnamen moeten uniek zijn binnen een campagne. De bot past tags op naam toe, dus twee items die dezelfde naam delen, hebben geen gedefinieerde winnaar.

Alle tags van een campagne instellen #

PUT /campaigns/{campaignId} met een tags array.

Dit vervangt de tags van de campagne door precies wat je verstuurt, wat hetzelfde is als wat het tabblad Tags in het dashboard doet wanneer je het opslaat. Verstuur elke keer de volledige array — een tag die je weglaat, is een tag die je hebt verwijderd. Het versturen van [] wist ze allemaal.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Lees de tags terug met GET /campaigns/{campaignId}.

Eén tag toevoegen #

POST /campaigns/{campaignId}/tags

Voegt een enkele tag toe zonder de rest opnieuw te versturen. Gebruik dit wanneer je toevoegt aan een set die je niet in dit verzoek hebt opgebouwd.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

Het twee keer plaatsen van exact dezelfde tag doet niets de tweede keer. Het plaatsen van dezelfde tag_id met een andere naam of beschrijving voegt een tweede item toe in plaats van de eerste te bewerken — gebruik het onderstaande eindpunt om op de huidige plek te bewerken.

Eén tag bijwerken of verwijderen #

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

Deze adresseren één item via zijn tag_id, dus ze werken alleen op tags die er een hebben. Als een tag geen tag_id heeft, wijzig deze dan met de volledige-array PUT /campaigns/{campaignId} hierboven.

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

Een tagId die niet in de campagne staat, retourneert 404 met "Tag not found in campaign tags".

Kanalen van een campagne in- of uitschakelen #

POST /campaigns/{campaignId}/channels

Voegt kanalen toe aan of verwijdert ze uit de enabled_channels-array van de campagne zonder de hele array opnieuw te verzenden — veiliger dan PUT /campaigns/{campaignId} wanneer iets anders de campagne mogelijk tegelijkertijd bewerkt.

Verzend ofwel een enkele schakelactie of een batch — niet beide in hetzelfde verzoek:

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

Geldige kanalen: whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

Dit wijzigt alleen op welke kanalen de campagne adverteert — het bepaalt niet wie een kanaal beantwoordt. Zie Campagnetypen hierboven en Een campagne routeren naar inkomende kanalen hieronder voor meer informatie.

Comment-to-DM (Instagram en Facebook) #

Comment-to-DM verandert een reactie op een van je berichten in een privégesprek: iemand reageert, de bot stuurt een DM en de campagne neemt het gesprek vanaf daar over. Het wordt volledig geconfigureerd via het campagne-object, dus er is niets dat alleen via de UI verloopt.

Verbind eerst de Facebook-pagina — zie Kanaalverbinding. Stel vervolgens de onderstaande velden in met PUT /campaigns/{campaignId}.

De campagne moet Live zijn. Comment-monitoring pikt alleen campagnes op waarvan de status Live is (elk hoofdlettergebruik — zie Campagnetypen). Elke andere status schakelt dit stilletjes uit, en een verzonnen status zoals "Active" wordt nu afgewezen met een 400 in plaats van opgeslagen. Geldige statussen zijn onder andere Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent en Failed.

Velden

Een veld wissen

Deze velden worden verwijderd in plaats van ingesteld op null wanneer je null verstuurt, zodat de bot terugvalt op zijn standaardwaarden: instagram_post_ids, facebook_post_ids, instagram_comment_delay_minutes, facebook_comment_delay_minutes, public_comment_reply_instructions, follower_outreach_instructions, first_response_exact_text, first_response_exact_text_variants, public_comment_reply_exact_text, public_comment_reply_exact_text_variants.

Eén onbekende sleutel wijst het hele verzoek af. PUT /campaigns/{campaignId} valideert de volledige body tegen een toegestane lijst. Een sleutel die niet wordt herkend, retourneert 400 voor het hele verzoek — het wordt niet geruisloos genegeerd en geen van de andere velden in die body wordt geschreven.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Het zichtbare antwoord dat bij de reactie wordt achtergelaten, vereist de functie voor reactie-antwoorden in je abonnement. Zonder dit wordt de DM nog steeds verzonden en wordt het openbare antwoord overgeslagen.

Een campagne optimaliseren met AI #

POST /campaigns/{campaignId}/optimize

Voert dezelfde AI-herschrijving uit als de ‘Optimaliseren’- en ‘duim omlaag’-feedbackstromen in het dashboard: verwerkt je feedback, herschrijft de instructies van de bot en zet het resultaat klaar als een nieuwe conceptrevisie die je kunt beoordelen.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

Antwoord (202 — de herschrijving wordt op de achtergrond uitgevoerd)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

Poll GET /campaigns/{campaignId} en bekijk test_bot.status: deze verspringt direct naar "Optimizing" en vervolgens terug naar "Draft" zodra de herschrijving in test_bot is geplaatst. Vanaf dat punt gedraagt het zich als elk ander dashboard-concept — beoordeel het en publiceer het vervolgens in het dashboard om het live te zetten. Een 409 betekent dat er al een optimalisatie voor deze campagne wordt uitgevoerd.

Optimaliseren kost credits, net als elke andere AI-bewerking op je account.

Een contactpersoon toewijzen aan een campagne #

POST /campaigns/{campaignId}/contacts/{contactId}/assign

Plaatst een bestaande contactpersoon in een campagne en verstuurt, indien gewenst, direct het openingsbericht van de campagne. Dit is de manier om het goedgekeurde WhatsApp-sjabloon van een campagne naar één contactpersoon te sturen: het sjabloon waarmee een campagne is goedgekeurd, hoort bij die campagne, dus het verschijnt niet in de Templates API bibliotheek en kan niet worden verzonden via /whatsapp-templates/send.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

Antwoord

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

Credits: Het versturen van het openingsbericht bij een WhatsApp-campagne wordt in rekening gebracht als een reguliere sjabloonverzending, geprijsd op basis van het land van de ontvanger en de categorie van het sjabloon. Bij andere kanalen is het openingsbericht een normaal uitgaand bericht.

Een campagne toewijzen aan inkomende kanalen #

Deze eindpunten beheren welke campagne nieuwe, onbekende contacten op een kanaal beantwoordt. Geef de voorkeur aan Entry Points voor nieuwe integraties (zie de opmerking onder Campagnetypen) — deze blijven nuttig voor het werken met campagnes die op de oudere manier routeren, en voor het oplossen van een conflict over kanaaleigendom tussen twee inkomende campagnes.

Een campagne toewijzen aan inkomende kanalen #

POST /campaigns/{campaignId}/incoming-routing

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'

Antwoord

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channels bevat alleen de kanalen die daadwerkelijk naar deze campagne zijn gerouteerd; failed bevat alle kanalen die dat niet zijn. Als elk opgevraagd kanaal mislukt, mislukt het verzoek zelf ook.

Inkomende routering van een campagne wissen #

DELETE /campaigns/{campaignId}/incoming-routing

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

Antwoord

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

Een inactieve campagne opnieuw activeren #

POST /campaigns/{campaignId}/reactivate

Brengt een campagne terug uit Ended, Completed, Paused of Draft en claimt de kanalen opnieuw. Werkt alleen bij Incoming from Unknown Contacts of Combined campagnes — een campagne die al Live is, wordt behandeld als een succes waarbij niets hoeft te gebeuren.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

Een kanaal dat al door de agent van een andere campagne is geclaimd, verschijnt in channelsBlockedByConflict in plaats van dat de hele aanroep mislukt — gebruik stop een conflicterende inkomende campagne hieronder om het eerst vrij te maken als je wilt dat deze campagne het overneemt. Er wordt een 400 geretourneerd voor een campagnetype dat reactivering niet ondersteunt, of een status die niet een van de bovenstaande inactieve statussen is.

Stop een conflicterende inkomende campagne #

POST /campaigns/{campaignId}/stop-incoming

Maakt de kanalen van deze campagne vrij van welke ANDERE campagne ze momenteel ook bezet houdt, zodat deze campagne ze als volgende kan claimen. Dit is de REST-versie van wat het dashboard automatisch doet wanneer je een inkomende campagne start in een kanaal dat iemand anders al beantwoordt.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

released_channels komt leeg terug wanneer deze campagne al elk kanaal bezit waarvoor geadverteerd wordt — er is niets om over te nemen.

Kostenramingen #

Schat wat het starten van een campagne kost voordat je deze verstuurt.

Kostenraming WhatsApp-sjabloon #

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode is "credits" op de beheerde WhatsApp-baan. Op een baan waar Meta je eigen WhatsApp Business-account rechtstreeks factureert, komen costPerContact, subtotal en totalTemplateCost terug als null — nooit 0, wat als gratis zou worden gelezen — aangezien er geen tegoedbedrag is om te rapporteren.

Kostenraming SMS #

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

SMS wordt altijd verzonden via je eigen Twilio-account (zie SMS-provider), dus dit wordt altijd rechtstreeks door Twilio gefactureerd — estimatedCostUsd is een schatting van die Twilio-factuur, geen tegoedafschrijving.

Limietcontroles #

Controleer een limiet voordat u start, in plaats van erachter te komen door een mislukte verzending.

Controles op campagneniveau #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — of het starten of inplannen van deze campagne de AI-credit-berichtlimiet van uw account zou overschrijden.

GET /campaigns/{campaignId}/limits/messaging — of het de dagelijkse berichtlimiet van uw account zou overschrijden.

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

Antwoord (limiet niet overschreden)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

Een 400 wordt in plaats daarvan geretourneerd wanneer de limiet zou worden overschreden, met de reden in error.

Controles op accountniveau #

GET /campaigns/limits/campaigns — of u de maandelijkse limiet voor het aanmaken van campagnes van uw abonnement heeft bereikt.

GET /campaigns/limits/contacts — of u de contactlimiet van uw abonnement heeft bereikt.

curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

Campagnestatistieken totalen #

GET /campaigns/stats/totals

Totalen voor verzonden en beantwoorde berichten voor elke campagne EN elke AI-agent in uw account, over een voortschrijdend venster — dezelfde cijfers die de campagnelijstpagina naast elke rij toont, in één aanroep in plaats van één verzoek per campagne.

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent is een eigen totaaloverzicht, geen som van byCampaign — het verkeer van een account dat inherent is aan AI-agents kan helemaal geen campagne bevatten, dus zou het hier anders onzichtbaar zijn.

Een campagne testen in de playground #

In de playground kun je een gesprek voeren met de bot van een campagne zonder een echt kanaal of een echt contact aan te raken. Het is dezelfde sandbox als het testpaneel van het dashboard en is volledig beschikbaar via de API.

De flow is: maak een verborgen testcontact aan, stuur een bericht en pols vervolgens de campagne voor het antwoord van de bot. Antwoorden worden asynchroon gegenereerd, dus ze komen aan in test_messages op de campagne in plaats van in de response body.

De Playground verbruikt API-tegoed. Een testgesprek dat wordt gestart met een API-sleutel wordt in rekening gebracht tegen het normale tarief voor AI-berichten, hetzelfde als een echt antwoord, en verschijnt in je gebruiksgeschiedenis als een reguliere vermelding. Testen vanuit het dashboard blijft gratis. Het verschil is bewust: een testrun voert hetzelfde AI-werk uit als een live run, dus een onbeperkte API-playground zou een manier zijn om onbeperkt AI te gebruiken op kosten van iemand anders.

Stap 1 - Maak het testcontact aan #

POST /campaigns/{campaignId}/try-out/contact

Maakt het verborgen testcontact aan en koppelt dit aan de campagne. Alle hoofdtekstvelden zijn optioneel; alles wat u weglaat, valt terug op een ingebouwde voorbeeldidentiteit (John Doe).

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

Antwoord

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

Stap 2 - Het inkomende bericht vastleggen #

POST /campaigns/{campaignId}/try-out/messages

Voegt berichten toe aan de testthread. Verstuur het bericht van de bezoeker hier eerst, zodat het verschijnt in de gespreksgeschiedenis die de bot leest.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

Stap 3 - De bot vragen om te antwoorden #

POST /campaigns/{campaignId}/try-out/test-message

Verstuurt het bericht naar de AI-pipeline. Dit is de aanroep die daadwerkelijk een bot-antwoord genereert.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

Antwoord

{
  "success": true,
  "data": "Published"
}

"Published" betekent dat het bericht naar de AI-pipeline is verzonden. "Ignored" betekent dat een nieuwer testbericht dit bericht heeft vervangen — de playground voegt een snelle reeks berichten samen tot één antwoord, ongeveer vier seconden na het laatste bericht, op dezelfde manier als een echt gesprek wacht tot iemand klaar is met typen. Vanwege dit samenvoegvenster duurt het enkele seconden voordat deze aanroep resultaat geeft.

Stap 4 - Het antwoord lezen #

GET /campaigns/{campaignId}

Het antwoord van de bot wordt toegevoegd aan de test_messages-array van de campagne. Pols de campagne totdat er een nieuw outbound-item verschijnt.

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

De playground resetten #

POST /campaigns/{campaignId}/try-out/reset

Wist de volledige sandbox: verwijdert het testcontact, wist test_messages en geeft de antwoordvergrendelingen van de bot vrij. Gebruik dit tussen testruns door.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Andere playground-endpoints #

Fouten in de Campaigns API #

Campagne-endpoints retourneren de standaard fouten-envelop:

{
  "success": false,
  "error": "Campaign not found"
}

De gedeelde codes die elk endpoint kan retourneren — 401, 403 (uw abonnement bevat geen API-toegang), 429 (snelheidslimiet) en 500 — worden vermeld met richtlijnen voor opnieuw proberen in Fouten & Paginering.

Gerelateerd #

• Routeer een kanaal naar een campagne — koppel Instagram, WhatsApp of elk ander kanaal aan de AI-agent die het moet beantwoorden, met behulp van Entry Points.
• Genereer follow-up-sjablonen met AI — start een achtergrondtaak die de WhatsApp-follow-up-sjablonen van een campagne schrijft.
• FAQs API — beheer de vraag-en-antwoord-items die uw campagnes gebruiken.
• API-toegang — genereer uw API-sleutel.
• Authenticatie — alle manieren om uw sleutel door te geven.