Bouw een integratie van begin tot eind

Deze handleiding leidt je door alles wat je nodig hebt om Your AI Connector vanuit je eigen code uit te voeren, zonder ooit het dashboard te openen. Aan het einde heb je een minimale integratie gebouwd die:

Authenticeert met een API-sleutel
Maakt een AI-agent aan en configureert het gedrag van de assistent
Verbindt een berichtkanaal (we gebruiken WhatsApp Web als voorbeeld) en koppelt dit aan de Agent
Importeert contacten
Verstuurt en leest berichten
Leest analyses
Abonneert zich op webhooks voor real-time gebeurtenissen

Elke stap linkt naar de volledige resourcegids, zodat je in de details kunt duiken wanneer dat nodig is. Deze pagina is de kaart; de resourcegidsen zijn het terrein.

Voordat je begint. API-toegang is een betaalde functie. Als je abonnement dit niet bevat, retourneert elk verzoek 403. Zie API-toegang om te bevestigen dat het is ingeschakeld, en Authenticatie voor alle manieren om je sleutel door te geven.

Alle onderstaande paden zijn relatief ten opzichte van de basis-URL:

https://api.youraiconnector.com/v1

Stap 1 — Haal een API-sleutel op en doe je eerste verzoek

Je API-sleutel vind je in de app onder Instellingen → Integraties → API-sleutel — een eigen sectie onder Integraties, los van Webhooks, die pas verschijnt zodra API-toegang is geactiveerd in het abonnement. Genereer er een, kopieer deze en sla hem veilig op (in een server-side secret store of omgevingsvariabele — nooit in browsercode). Volledige instructies staan in API-toegang.

Zodra je een sleutel hebt, kun je controleren of deze werkt door het health-eindpunt aan te roepen. Er zijn verschillende manieren om de sleutel te verzenden; de eenvoudigste is de ?apiKey= queryparameter, maar voor echte code heeft de X-API-Key header de voorkeur, zodat de sleutel nooit in serverlogs of browsergeschiedenis terechtkomt.

cURL

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

JavaScript

const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }

Python

import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }

Elk succesvol antwoord is verpakt in dezelfde envelop — een success: true veld plus de resultaatgegevens. Fouten retourneren success: false met een error bericht en een error_code. Zie Fouten & Paginering voor de volledige lijst en voor hoe lijsteindpunten pagineren met ?limit en ?cursor.

Snelheidslimiet. Geauthenticeerde verzoeken zijn beperkt tot 300 per minuut (met een ruimer plafond van 1.200 per minuut per account). Overschrijding resulteert in 429; wacht even en probeer het opnieuw.

Stap 2 — Een AI-agent aanmaken

Een AI-agent is de entiteit die het gedrag van je assistent bevat: de instructies, het doel, de actieve uren en hoe deze met contacten communiceert. Dit is degene die een gesprek beantwoordt, dus dit is het logische eerste punt om aan te maken.

Maak er een aan met POST /agents. name is het enige veld dat je vooraf hoeft mee te sturen; al het andere kan worden ingesteld met de onderstaande bot-config-aanroep.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'

JavaScript

const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]

Een succesvolle aanmaak retourneert 201 met het nieuwe ID:

{
  "success": true,
  "agent_id": "abc123agent"
}

Sla de agent_id op — je zult hiernaar verwijzen bij het routeren van kanalen.

De assistent configureren

PUT /agents/{agentId}/bot-config stelt het gedrag van de assistent in. Het voegt de velden die je verstuurt samen met de bestaande configuratie, dus alles wat je weglaat blijft behouden:

curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'

Stel actieve uren in met PUT /agents/{agentId}/active-hours zodat de assistent alleen tijdens kantooruren antwoordt; buiten die vensters antwoordt de assistent niet automatisch.

Kennisbank. Om de assistent te laten antwoorden op basis van je eigen inhoud, kun je veelgestelde vragen (FAQ’s) toevoegen. Zie de FAQ-handleiding.

Legacy: klassieke campagnes. Accounts die nog steeds een Campagnes-pagina hebben, creëren hetzelfde assistentgedrag op een campagne (POST /campaigns met een type en een bot object, daarna PUT /campaigns/{campaignId}/bot-config). De volledige lijst met campagnevelden en levenscycluscontroles staat in de Campagne-handleiding. Als je iets nieuws bouwt, maak dan een Agent aan.

Stap 3 — Een kanaal verbinden

Een Agent heeft een manier nodig om berichten te verzenden en te ontvangen. Zeven verbindingsstromen kunnen worden aangestuurd via de API: WhatsApp Business, WhatsApp Web, Instagram en Messenger samen (één gedeelde Meta-stroom), persoonlijke Instagram-accounts, Telegram, LINE en Viber. De overige kanalen — waaronder sms, e-mail, de chatwidget en aangepaste kanalen — worden ingesteld in het dashboard in plaats van via REST. Zodra ze zijn verbonden, werken de eindpunten voor berichten, contacten en routering op precies dezelfde manier. GET /channels is de actuele bron van waarheid voor wat er voor een bepaald account daadwerkelijk is verbonden:

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

De volledige set verbindings-/verbindingsverbrekingsstromen voor elk kanaal staat gedocumenteerd in de Kanaalgids. Hieronder doorlopen we WhatsApp Web van begin tot eind, omdat dit het meest interessante patroon laat zien: een QR-code koppelingsstroom die je wrapper moet renderen en pollen.

Uitgewerkt voorbeeld: WhatsApp Web koppelen via QR-code

Het koppelen van WhatsApp Web is een dans van drie aanroepen — starten, de QR ophalen, pollen tot verbonden.

1. Start de koppelingssessie. Geef het nummer dat je wilt verbinden door in E.164-formaat.

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)

2. Haal de QR-code op en toon deze aan de gebruiker. Pol deze elke 10–15 seconden. Het antwoord bevat de onbewerkte qr_code-payload (render deze zelf als een QR-afbeelding) en een qr_data_url die klaar is om weer te geven.

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}

Plaats in de UI van je wrapper de qr_data_url direct in een <img src="..."> en vraag de gebruiker om deze te scannen via WhatsApp → Gekoppelde apparaten op hun telefoon. Als de QR verloopt (een 410-antwoord), begin dan opnieuw bij stap 1 om een nieuwe te krijgen.

3. Pol de status totdat deze verbonden is. Nadat de gebruiker heeft gescand, blijf je het statuseindpunt pollen totdat het connected rapporteert (de service kan ook open rapporteren). Behandel disconnected en not_initialized als terminale fouten.

import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)

async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Let op. Voor elk verbonden WhatsApp Web-nummer geldt een terugkerende maandelijkse onderhoudskost totdat je de verbinding verbreekt (DELETE /channels/whatsapp-web/connections/{phoneNumber}).

Het kanaal routeren naar je Agent

Het verbinden van een kanaal zorgt ervoor dat het werkt; door het te routeren vertel je het platform welke AI-agent nieuwe inkomende gesprekken op dat kanaal moet beantwoorden. Stel het standaard-toegangspunt (Entry Point) voor het kanaal in en benoem de Agent die je in stap 2 hebt aangemaakt:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'

Herhaal de aanroep één keer per kanaal — één kanaalstandaard per kanaal. Om een kanaal achter te laten zonder dat een Agent antwoordt, roep je DELETE /entry-points/channel-defaults?channel=whatsapp_web aan; om te controleren of de Entry Points-ladder live is voor het account, roep je GET /entry-points/routing-status aan. De oudere POST /channels/campaign-map is alleen behouden voor terugdraai-acties en wordt niet langer geraadpleegd voor inkomende routering. Zie de Kanaalhandleiding voor de andere kanaaltypen en voor de WhatsApp Business OAuth-stroom.

Stap 4 — Importeer je contacten

Zodra een kanaal live is, kun je de mensen laden die je wilt bereiken. Het import-eindpunt verwerkt maximaal 500 records per aanroep. Elk record heeft een phone_number in internationaal formaat nodig; al het overige is optioneel. Records met ongeldige nummers, niet-ondersteunde kanalen of nummers die al bestaan worden overgeslagen — en elke overgeslagen record wordt gerapporteerd met de index en de reden, zodat je alleen de mislukte records opnieuw kunt proberen.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);

Python

res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")

Het antwoord vertelt je precies wat er is gebeurd:

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

Voor het aanmaken per stuk, opzoeken, lijsten, tags en aangepaste velden, zie de Gids voor contacten.

Stap 5 — Berichten verzenden en lezen

Een bericht verzenden

De eenvoudigste manier van verzenden is kanaalonafhankelijk: geef de identiteit van de contactpersoon en de berichtinhoud op, en het platform bezorgt het via het kanaal waarop de contactpersoon zich bevindt. Je kunt targeten op contact_id, of op channel plus het bijbehorende identiteitsveld (phone_number voor WhatsApp/WhatsApp Web/SMS, instagram_id voor Instagram, enzovoort).

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]

Bezorging is asynchroon — een 201 betekent dat het bericht is geaccepteerd en in de wachtrij geplaatst, nog niet bezorgd. (Contacten met ‘niet storen’ of de privacymodus ingeschakeld worden geweigerd met een 422.)

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}

Een gesprek lezen

Om berichten terug te lezen, vermeld je ze per contactpersoon, nieuwste eerst, met cursor-paginering. Geef de next_cursor van het ene antwoord door als de cursor van het volgende om door de geschiedenis terug te bladeren.

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page

Je kunt ook filteren op inhoudstype (?filter=text|media|tool_use) of richting (?direction=inbound|outbound). De Gids voor berichten behandelt mediabijlagen, het markeren van berichten als gelezen en de berichtweergaven per sessie.

Poll niet voor antwoorden. Berichten op een timer opvragen werkt wel, maar het verspilt verzoeken en zorgt voor vertraging. Gebruik voor inkomende berichten webhooks — dat is Stap 7.

Stap 6 — Analytics lezen

Zodra er berichten worden verstuurd, geeft het analytics-overzicht geaggregeerde totalen over een datumbereik: verzonden, afgeleverd, gelezen, beantwoord, geboekt, aangemaakte contacten en verbruikte/opgewaardeerde credits. Je krijgt zowel totalen voor het bereik als een reeks per dag met nullen opgevuld — perfect voor een dashboardgrafiek. Je kunt dit optioneel beperken tot één campagne met campaign_id (de onderstaande voorbeelden gebruiken een tijdelijke campagne-ID, abc123campaign); laat de parameter weg voor totalen op accountniveau.

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();

res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]

Het bereik staat standaard op de laatste 30 dagen en is gemaximeerd op 366. Voor gebruiksgegevens per credit en uitsplitsingen van AI-kosten, zie de Analytics-handleiding.

Stap 7 — Abonneer je op webhooks voor realtime gebeurtenissen

Polling is prima voor een snel script, maar een echte integratie moet push-gebaseerd zijn. Met webhooks kan het platform jouw server aanroepen op het moment dat er iets gebeurt — een nieuw contact, een antwoord, een geboekte afspraak, een afgesloten chat.

Ontdek eerst de exacte namen van de gebeurtenissen waarop je je kunt abonneren:

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}

Maak vervolgens een abonnement aan dat verwijst naar een HTTPS-URL op jouw server. Gebruik de exacte gebeurtenis-strings uit de bovenstaande aanroep.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'

JavaScript

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

De URL moet HTTPS gebruiken en publiekelijk bereikbaar zijn. Vanaf nu ontvangt jouw server een POST voor elke geabonneerde gebeurtenis. Je kunt een testbericht sturen, de status van een abonnement controleren en een abonnement opnieuw inschakelen dat na herhaalde fouten automatisch was uitgeschakeld — zie de Webhooks-handleiding en de Webhooks-pagina op integratieniveau voor payload-structuren en verificatie.

Alles op een rij

Hier is het volledige proces in één oogopslag:

Stap	Doel	Belangrijkste aanroep
1	Authenticeren	`GET /health`
2	Assistent aanmaken + afstemmen	`POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours`
3	Kanaal verbinden en routeren	`POST /channels/whatsapp-web/connections` → QR scannen + status → `PUT /entry-points/channel-defaults`
4	Contacten laden	`POST /contacts/import`
5	Verzenden & lezen	`POST /contacts/send`, `GET /contacts/{id}/messages`
6	Meten	`GET /analytics/summary`
7	Realtime reageren	`POST /webhooks`

Een minimale wrapper bestaat uit slechts deze zeven aanroepen die in je eigen UI zijn verwerkt. Voeg vanaf daar de per-resource handleidingen toe naarmate je meer nodig hebt:

Campagnes · Contacten · Veelgestelde vragen · Berichten · Afspraken
Kanalen · Sjablonen · Analytics · Webhooks · API-sleutels
Nieuw hier? Aan de slag · Authenticatie · Fouten & Paginering

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

Bouw een integratie van begin tot eind #

Stap 1 — Haal een API-sleutel op en doe je eerste verzoek #

Stap 2 — Een AI-agent aanmaken #

De assistent configureren #

Stap 3 — Een kanaal verbinden #

Uitgewerkt voorbeeld: WhatsApp Web koppelen via QR-code #

Het kanaal routeren naar je Agent #

Stap 4 — Importeer je contacten #

Stap 5 — Berichten verzenden en lezen #

Een bericht verzenden #

Een gesprek lezen #

Stap 6 — Analytics lezen #

Stap 7 — Abonneer je op webhooks voor realtime gebeurtenissen #

Alles op een rij #

Bouw een integratie van begin tot eind

Stap 1 — Haal een API-sleutel op en doe je eerste verzoek

Stap 2 — Een AI-agent aanmaken

De assistent configureren

Stap 3 — Een kanaal verbinden

Uitgewerkt voorbeeld: WhatsApp Web koppelen via QR-code

Het kanaal routeren naar je Agent

Stap 4 — Importeer je contacten

Stap 5 — Berichten verzenden en lezen

Een bericht verzenden

Een gesprek lezen

Stap 6 — Analytics lezen

Stap 7 — Abonneer je op webhooks voor realtime gebeurtenissen

Alles op een rij