Entry Points API #

Et Entry Point (indgangspunkt) er en ruteregel: “når dette sker på denne kanal, så giv samtalen videre til denne Agent”. At forbinde en kanal får beskeder ind på kontoen, og at oprette en Agent giver dig noget, der kan svare, men ingen af delene afgør, hvem der besvarer en fremmeds første besked. Det gør Entry Points. For selve produktet, se Entry Points-guiden.

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

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

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

Det ene kald, som de fleste integrationer har brug for #

Forbind en kanal, opret en Agent, og peg derefter kanalen mod Agenten:

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

Det er hele opsætningen for “denne Agent besvarer WhatsApp”. Alt andet på denne side er til mere specifikke regler (nøgleord, kommentarer, nye følgere), flere numre på én kanal og læsning af, hvad der er konfigureret.

Hvordan ruting besluttes #

Når en besked ankommer, gennemgår platformen en fast stige, og det første trin, der træffer en beslutning, vinder:

1. Et menneske har overtaget samtalen — ingen AI.
2. Kontakten er allerede tildelt en Agent, manuelt eller fordi en samtale med denne Agent er i gang — den samme Agent beholder den. Entry Points flytter aldrig en eksisterende samtale; for at give en chat videre til en anden Agent, skal du tildele den (i appen eller med Automations-handlingen).
3. Kontakten svarer på en udsendelse — udsendelsens Agent svarer, eller ingen, hvis udsendelsen ikke havde nogen.
4. Et snævert Entry Point matcher. Nøgleordsregler slår kommentarregler, som slår følgerregler. Mellem to regler af samme type vinder den, der sidst er blevet opdateret.
5. Kanalens standard for den kanal, beskeden ankom på. En standard, der er begrænset til det specifikke nummer, kontakten skrev til, slår kanalens overordnede standard.
6. Intet matchede — beskeden lander i indbakken til dit team, og ingen assistent svarer.

To ting blødgør trin 6. En konto med præcis én aktiv Agent og ingen standard konfigureret for kanalen får stadig denne Agent som svarer, så en ny konto, der forbinder WhatsApp og sender en testbesked, oplever ikke tavshed. Dette gulv gælder aldrig for en kanal, der har en nøgleordsregel (her efterlades en besked, der ikke matcher noget nøgleord, bevidst til et menneske) og tilsidesætter aldrig en kanal, du har sat til ingen (se Lad en kanal stå uden svar).

Hvorvidt stigen er aktiv for en konto, rapporteres af GET /entry-points/routing-status. Den er tændt for alle konti i dag; kaldet findes, så en integration kan tjekke i stedet for at antage.

Entry Point-objektet #

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

Regeltyper #

En nøgleordsregel på en kanal uden en kanalstandard fungerer også som en port: beskeder, der ikke matcher nogen af nøgleordene, får ikke noget automatisk svar og lander blot i din indbakke, selv på en konto med en enkelt agent.

Tildel en kanal til en agent #

PUT /entry-points/channel-defaults — gør én agent til besvarer for nye kontakter på en kanal. Enhver anden agent, der i øjeblikket er indstillet som kanalens standard, trækkes tilbage i samme kald, så en kanal altid har præcis én besvarer. Hvis du indstiller den agent, der allerede er standard, ændres intet.

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

Svar

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

entry_point_id er reglen, der nu er gældende; disabled_entry_point_ids viser alle regler, der er trukket tilbage for at gøre plads til den (tom, når der ikke var noget at erstatte). Kun kontakter, du aldrig har talt med, bliver påvirket — alle, der allerede er i en samtale med en agent, beholder denne agent.

En 400 betyder, at channel eller agent_id mangler, agenten tilhører en anden konto, eller phone_number ikke er et af dine tilsluttede numre.

Se, hvem der besvarer hver kanal #

GET /entry-points/channel-defaults — hver kanalstandard på kontoen, nyeste først, inklusive tilbagetrukne (enabled: false) og en kanal, der bevidst er indstillet til ingen (agent_id: ""). Filtrer på enabled for at få det aktuelle overblik.

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

Svar

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

Dette er læsningen for hele kontoen. At liste én agents regler med GET /agents/{agentId}/entry-points kan ikke vise en kanal, der er indstillet til ingen, fordi den regel ikke tilhører nogen agent.

Efterlad en kanal uden besvarer #

DELETE /entry-points/channel-defaults?channel=instagram — trækker kanalens overordnede standard tilbage for én kanal. Kanalen navngives som en forespørgselsparameter, ikke i en brødtekst. Tilføj &phone_number=%2B31685101091 for kun at rydde det nummers standard og lade nummeret gå tilbage til den, der besvarer kanalen.

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

Svar

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

Sikkert at gentage: rydning af en kanal, der ikke har nogen standard, er en 200 med en tom liste. Rydning betyder fjern indstilling, ikke tavshed — på en konto med præcis én aktiv agent falder en ukonfigureret kanal stadig tilbage på den agent. For at holde AI’en helt væk fra en kanal, skal du vælge Ingen besvarer for den i appens panel Hvem besvarer nye samtaler (det skriver en eksplicit “ingen”-standard, som fallback-funktionen aldrig tilsidesætter), eller sæt agenten på pause med PATCH /agents/{agentId}/active.

Én agent pr. WhatsApp-nummer #

Routing er som standard pr. kanal: alle dine WhatsApp-numre deler én besvarer. Med to eller flere numre tilsluttet på WhatsApp Business eller WhatsApp Web kan en standard begrænses til et enkelt nummer, så en virksomhed med et nummer pr. afdeling eller brand kan give hver sin egen agent inden for én konto.

Send phone_number med set-kaldet:

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

• Nummeret skal være et af dine tilknyttede numre på den kanal, skrevet som det vises under tilknyttede numre (E.164 med +); alt andet er en 400.
• Reglen gemmes som en kanalstandard med match_config.phone_numbers: ["+31685101091"]. En besked, der ankommer til det nummer, går til dets agent; alle andre numre fortsætter med at følge kanalens standard.
• Indstilling eller sletning af kanalens standard påvirker ikke nummer-specifikke regler, og omvendt. Slet et nummers egen regel med DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Svar sendes altid fra det nummer, som kontakten skrev til, så kontakten bliver ved med at tale med det samme nummer og den samme agent.

Tilføj en mere specifik regel #

POST /agents/{agentId}/entry-points — opretter en regel for nøgleord, kommentarer eller følgere (eller en kanalstandard, selvom PUT /entry-points/channel-defaults er det bedre valg til det, da den automatisk pensionerer den tidligere svarer for dig). Agenten i stien vinder altid: en regel kan aldrig oprettes for en anden agent end den, der er angivet i URL’en.

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

Svar (201)

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

En kommentar-til-DM-regel, der kun reagerer på kommentarer, der skriver “LINK” på to specifikke opslag, venter to minutter og sender en fast første besked:

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

Lad keywords være tom for at sende DM til alle, der kommenterer på de overvågede opslag, og post_ids være tom for at overvåge alle opslag. En 400 angiver, hvad der er galt: et ukendt type, et tomt channels, en nøgleordsregel uden nøgleord eller en kommentarregel, der ikke angiver sin egen kanal.

Vis en agents regler #

GET /agents/{agentId}/entry-points — de regler, der sender samtaler til denne agent, nyeste først: dens kanalstandarder, nøgleordsregler, kommentarregler og følgerregler. Pensionerede regler kommer også tilbage med 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()

Svar

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

Ændr en regel #

PUT /entry-points/{entryPointId} — ændrer én regel. Send kun de felter, du ændrer; indlejrede indstillinger kan adresseres punkt for punkt med en prik-adskilt nøgle såsom "match_config.keywords". Hver gang ændringen berører type, channels eller match_config, bliver hele reglen tjekket igen, så en delvis redigering aldrig kan efterlade en ubrugelig regel (skift af type til keyword uden at angive nøgleord afvises). Ved at sende agent_id gives reglen videre til en anden af dine agenter; en tom værdi afvises. Ejer- og identitetsfelter ignoreres.

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

Svar

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

Andre almindelige redigeringer: { "enabled": false } pensionerer en regel uden at slette den, og { "agent_id": "agOtherAgent" } flytter den til en anden agent. En tom brødtekst returnerer 400 med "No fields to update".

Slet en regel #

DELETE /entry-points/{entryPointId} — fjerner reglen permanent. Intet andet refererer til et Entry Point, så der er intet, der skal løsrives først.

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

Svar

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

For at stoppe en regel fra at blive aktiveret, men beholde den, skal du i stedet sætte enabled til false. Kanalstandarder bliver normalt pensioneret frem for slettet, hvilket er hvad DELETE /entry-points/channel-defaults gør.

Tjek at routing er aktiv #

GET /entry-points/routing-status — returnerer, hvorvidt Entry Points-stigen afgør, hvem der svarer på denne konto. Kan læses med visningsadgang, så et teammedlem ser det samme svar som ejeren.

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

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

Det er true på alle konti i dag. Kaldet beholdes, så en integration kan verificere, før den fortæller nogen, at deres routing-ændring er live, i stedet for at antage det.

De ældre, kampagneformede kald #

To slutpunkter fra før agenter fungerer stadig for konti, der er organiseret omkring kampagner. Nye integrationer bør bruge kanal-standardkaldene ovenfor i stedet.

• PUT /channel-routing/{channel} med { "campaignId": "cp5NbV8xQrT2wYzA" } — navngiver en kampagne, og den kampagnes agent bliver kanalens svarer. { "campaignId": null } rydder kanalen. En kampagne, der kun er udgående, afvises, fordi den ikke har nogen indgående adfærd at tilbyde.
• POST /channel-routing/clear med { "channels": ["whatsapp", "instagram"] } — frigør flere kanaler fra den agent, der svarer på dem i ét kald, typisk før de peges et andet sted hen. Svaret viser released_channels, dem der faktisk havde en svarer.

Begge nulstiller snarere end at gøre tavse: på en konto med præcis én aktiv agent falder en frigjort kanal stadig tilbage til den agent.

Entry Points API-fejl #

Entry Point-slutpunkter returnerer standardfejlkonvolutten:

{
  "success": false,
  "error": "Entry point not found"
}

De delte koder, som ethvert endpoint kan returnere — 401, 403 (din plan inkluderer ikke API-adgang), 429 (rate limit) og 500 — er angivet med vejledning om genforsøg i Errors & Pagination.

Næste skridt #

• Entry Points — konceptet, regeltyperne og panelet Hvem besvarer nye samtaler i appen.
• AI Agents API — opret og konfigurer de agenter, som disse regler ruter til.
• Channels API — forbind selve kanalerne.
• Automatisering af kommentar-til-DM — hvad kommentarreglerne gør, når de udløses.