Entry Points API #

Een Entry Point (toegangspunt) is een routeringsregel: “wanneer dit gebeurt op dit kanaal, draag het gesprek over aan deze Agent”. Het verbinden van een kanaal zorgt ervoor dat berichten in het account binnenkomen en het aanmaken van een Agent geeft je iemand die kan antwoorden, maar geen van beide bepaalt wie het eerste bericht van een vreemde beantwoordt. Entry Points doen dat wel. Zie voor het product zelf de Entry Points-gids.

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

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

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

De ene aanroep die de meeste integraties nodig hebben #

Verbind een kanaal, maak een Agent aan en wijs het kanaal vervolgens toe aan de Agent:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

Dat is de volledige configuratie voor “deze Agent beantwoordt WhatsApp”. Al het overige op deze pagina is bedoeld voor specifiekere regels (trefwoorden, reacties, nieuwe volgers), meerdere nummers op één kanaal en het uitlezen van de huidige configuratie.

Hoe routering wordt bepaald #

Wanneer een bericht binnenkomt, doorloopt het platform een vaste ladder en de eerste stap die een beslissing neemt, wint:

1. Een mens heeft het gesprek overgenomen — geen AI.
2. Het contact is al toegewezen aan een Agent, handmatig of omdat er al een gesprek met die Agent gaande is — dezelfde Agent blijft het gesprek voeren. Entry Points verplaatsen nooit een bestaand gesprek; om een chat over te dragen aan een andere Agent, wijs je deze toe (in de app of met de Automations-actie).
3. Het contact reageert op een broadcast — de Agent van de broadcast antwoordt, of niemand als de broadcast er geen had.
4. Een specifiek Entry Point komt overeen. Trefwoordregels gaan voor reactieregels, die weer voor volgersregels gaan. Tussen twee regels van hetzelfde type wint de meest recent bijgewerkte regel.
5. De kanaalstandaard voor het kanaal waarop het bericht binnenkwam. Een standaard die is beperkt tot het specifieke nummer waarnaar het contact schreef, gaat voor de kanaalbrede standaard.
6. Niets kwam overeen — het bericht belandt in de inbox voor je team en er antwoordt geen assistent.

Twee zaken verzachten stap 6. Een account met precies één actieve Agent en geen standaard geconfigureerd voor het kanaal, krijgt nog steeds die Agent als antwoordende partij, zodat een nieuw account dat WhatsApp verbindt en een testbericht stuurt, niet in stilte blijft. Die ondergrens geldt nooit voor een kanaal dat een trefwoordregel heeft (daar wordt een bericht dat niet overeenkomt met een trefwoord bewust overgelaten aan een mens) en overschrijft nooit een kanaal dat je op ‘niemand’ hebt ingesteld (zie Een kanaal verlaten zonder dat iemand antwoordt).

Of de ladder actief is voor een account wordt gerapporteerd door GET /entry-points/routing-status. Het is tegenwoordig voor elk account ingeschakeld; de aanroep bestaat zodat een integratie dit kan controleren in plaats van ervan uit te gaan.

Het Entry Point-object #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Regeltypen #

Een trefwoordregel op een kanaal zonder kanaalstandaard werkt ook als een poort: berichten die met geen van de trefwoorden overeenkomen, krijgen geen automatisch antwoord en komen gewoon in je inbox terecht, zelfs op een account met slechts één Agent.

Wijs een kanaal toe aan een Agent #

PUT /entry-points/channel-defaults — maakt één Agent de beantwoorder voor nieuwe contacten op een kanaal. Elke andere Agent die momenteel als standaard voor dat kanaal is ingesteld, wordt in dezelfde aanroep uitgeschakeld, zodat een kanaal altijd precies één beantwoorder heeft. Het instellen van de Agent die al de standaard is, verandert niets.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

Antwoord

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id is de regel die nu van kracht is; disabled_entry_point_ids somt alle regels op die zijn uitgeschakeld om er ruimte voor te maken (leeg als er niets te vervangen was). Alleen contacten met wie je nog nooit hebt gesproken worden beïnvloed — iedereen die al in gesprek is met een Agent, behoudt die Agent.

Een 400 betekent dat channel of agent_id ontbreekt, de Agent bij een ander account hoort, of phone_number geen van je gekoppelde nummers is.

Zie wie elk kanaal beantwoordt #

GET /entry-points/channel-defaults — elke kanaalstandaard op het account, nieuwste eerst, inclusief uitgeschakelde (enabled: false) en een kanaal dat bewust op niemand is ingesteld (agent_id: ""). Filter zelf op enabled voor het huidige overzicht.

cURL

curl "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Antwoord

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Dit is het overzicht voor het hele account. Het weergeven van de regels van één Agent met GET /agents/{agentId}/entry-points kan geen kanaal tonen dat op niemand is ingesteld, omdat die regel bij geen enkele Agent hoort.

Laat een kanaal onbeantwoord #

DELETE /entry-points/channel-defaults?channel=instagram — schakelt de kanaalbrede standaard voor één kanaal uit. Het kanaal wordt benoemd als een queryparameter, niet in een body. Voeg &phone_number=%2B31685101091 toe om alleen de standaard van dat nummer te wissen en het nummer terug te laten keren naar wie het kanaal ook beantwoordt.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { 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/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Antwoord

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

Veilig om te herhalen: het wissen van een kanaal dat geen standaard heeft, is een 200 met een lege lijst. Wissen betekent niet ingesteld, niet stilte — op een account met precies één actieve Agent valt een niet-geconfigureerd kanaal nog steeds terug op die Agent. Om de AI volledig van een kanaal te houden, kies Niemand antwoordt voor dat kanaal in het paneel Wie beantwoordt nieuwe gesprekken van de app (dat schrijft een expliciete “niemand”-standaard die de fallback nooit overschrijft), of pauzeer de Agent met PATCH /agents/{agentId}/active.

Eén Agent per WhatsApp-nummer #

Routering is standaard per kanaal: al je WhatsApp-nummers delen één beantwoorder. Met twee of meer nummers gekoppeld op WhatsApp Business of WhatsApp Web, kan een standaard worden beperkt tot één nummer, zodat een bedrijf met een nummer per vestiging of merk elk zijn eigen Agent kan geven binnen één account.

Verstuur phone_number met de set-aanroep:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• Het nummer moet een van uw gekoppelde nummers op dat kanaal zijn, geschreven zoals het wordt weergegeven onder gekoppelde nummers (E.164 met de +); al het andere is een 400.
• De regel wordt opgeslagen als een kanaalstandaard met match_config.phone_numbers: ["+31685101091"]. Een bericht dat op dat nummer binnenkomt, gaat naar de bijbehorende Agent; elk ander nummer blijft de kanaalbrede standaard volgen.
• Het instellen of wissen van de kanaalbrede standaard laat regels op nummerniveau ongemoeid, en vice versa. Wis de eigen regel van een nummer met DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Antwoorden worden altijd verzonden vanaf het nummer waarnaar de contactpersoon heeft geschreven, zodat de contactpersoon blijft praten met hetzelfde nummer en dezelfde Agent.

Een specifiekere regel toevoegen #

POST /agents/{agentId}/entry-points — maakt een trefwoord-, commentaar- of volgersregel aan (of een kanaalstandaard, hoewel PUT /entry-points/channel-defaults daarvoor de betere keuze is omdat het de vorige beantwoorder voor u intrekt). De Agent in het pad wint altijd: een regel kan nooit worden aangemaakt voor een andere Agent dan degene in de URL.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

Antwoord (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Een commentaar-naar-DM-regel die alleen reageert op commentaren met “LINK” op twee specifieke berichten, twee minuten wacht en een vast eerste bericht verstuurt:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

Laat keywords leeg om iedereen die reageert op de gevolgde berichten een DM te sturen, en post_ids leeg om elk bericht te volgen. Een 400 benoemt wat er mis is: een onbekende type, een lege channels, een trefwoordregel zonder trefwoorden, of een commentaarregel die zijn eigen kanaal niet vermeldt.

Regels van een Agent weergeven #

GET /agents/{agentId}/entry-points — de regels die gesprekken naar deze Agent sturen, nieuwste eerst: de kanaalstandaarden, trefwoordregels, commentaarregels en volgersregels. Ingetrokken regels komen ook terug, met enabled: false.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Antwoord

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Een regel wijzigen #

PUT /entry-points/{entryPointId} — wijzigt één regel. Stuur alleen de velden die u wijzigt; geneste instellingen kunnen per onderdeel worden aangepakt met een punt-gescheiden sleutel zoals "match_config.keywords". Wanneer de wijziging type, channels of match_config betreft, wordt de hele regel opnieuw gecontroleerd, zodat een gedeeltelijke bewerking nooit een onbruikbare regel kan achterlaten (het wijzigen van type naar keyword zonder trefwoorden op te geven wordt afgewezen). Het verzenden van agent_id draagt de regel over aan een andere Agent van u; een lege waarde wordt afgewezen. Eigendoms- en identiteitsvelden worden genegeerd.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

Antwoord

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Andere veelvoorkomende bewerkingen: { "enabled": false } trekt een regel in zonder deze te verwijderen, en { "agent_id": "agOtherAgent" } verplaatst deze naar een andere Agent. Een lege body retourneert 400 met "No fields to update".

Een regel verwijderen #

DELETE /entry-points/{entryPointId} — verwijdert de regel definitief. Niets anders verwijst naar een Entry Point, dus er hoeft niets eerst te worden losgekoppeld.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  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/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Antwoord

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Om te voorkomen dat een regel wordt geactiveerd maar deze wel te behouden, stelt u enabled in op false. Kanaalstandaarden worden in het bijzonder meestal ingetrokken in plaats van verwijderd, wat DELETE /entry-points/channel-defaults doet.

Controleren of de routering actief is #

GET /entry-points/routing-status — geeft aan of de Entry Points-ladder bepaalt wie op dit account antwoordt. Leesbaar met weergavetoegang, zodat een teamgenoot hetzelfde antwoord ziet als de eigenaar.

curl "https://api.youraiconnector.com/v1/entry-points/routing-status?apiKey=YOUR_API_KEY"

{ "success": true, "cutover_enabled": true }

Het staat vandaag op true voor elk account. De aanroep wordt bewaard zodat een integratie kan verifiëren voordat deze iemand vertelt dat hun routeringswijziging live is, in plaats van daarvan uit te gaan van aannames.

De oudere, campagne-vormige aanroepen #

Twee eindpunten van vóór Agents werken nog steeds voor accounts die rond campagnes zijn georganiseerd. Nieuwe integraties moeten de bovenstaande channel-defaults-aanroepen gebruiken.

• PUT /channel-routing/{channel} met { "campaignId": "cp5NbV8xQrT2wYzA" } — benoemt een campagne, en de Agent van die campagne wordt de beantwoorder van het kanaal. { "campaignId": null } maakt het kanaal leeg. Een campagne die alleen voor uitgaande berichten is, wordt geweigerd omdat deze geen inkomend gedrag te bieden heeft.
• POST /channel-routing/clear met { "channels": ["whatsapp", "instagram"] } — maakt verschillende kanalen vrij van de Agent die ze beantwoordt in één aanroep, meestal voordat ze ergens anders naartoe worden verwezen. Het antwoord bevat released_channels, de kanalen die daadwerkelijk een beantwoorder hadden.

Beide zetten de instelling terug in plaats van deze te dempen: op een account met precies één actieve Agent valt een vrijgemaakt kanaal nog steeds terug op die Agent.

Entry Points API-fouten #

Entry Point-eindpunten retourneren de standaard fouten-envelop:

{
  "success": false,
  "error": "Entry point 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.

Volgende stappen #

• Entry Points — het concept, de regeltypen en het paneel Wie beantwoordt nieuwe gesprekken in de app.
• AI Agents API — maak en configureer de Agents waarnaar deze regels routeren.
• Channels API — verbind de kanalen zelf.
• Comment-to-DM Automation — wat de commentaarregels doen zodra ze worden geactiveerd.