Entry Points-API #

En Entry Point (startpunkt) är en routingsregel: “när detta händer i denna kanal, skicka konversationen till denna Agent”. Att ansluta en kanal gör att meddelanden når kontot och att skapa en Agent ger dig någon som kan svara, men inget av dem avgör vem som svarar på en främlings första meddelande. Det gör Entry Points. För själva produkten, se Entry Points-guiden.

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

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

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

Det enda anropet de flesta integrationer behöver #

Anslut en kanal, skapa en Agent, och peka sedan kanalen mot 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 är hela konfigurationen för “denna Agent svarar på WhatsApp”. Allt annat på denna sida är till för mer specifika regler (nyckelord, kommentarer, nya följare), flera nummer på en kanal, och för att läsa av vad som är konfigurerat.

Hur routing beslutas #

När ett meddelande anländer går plattformen igenom en fast stege och det första steget som fattar ett beslut vinner:

1. En människa har tagit över konversationen — ingen AI.
2. Kontakten är redan tilldelad en Agent, manuellt eller för att en konversation med den Agenten pågår — samma Agent behåller den. Entry Points flyttar aldrig en befintlig konversation; för att skicka en chatt till en annan Agent, tilldela den (i appen, eller med Automations-åtgärden).
3. Kontakten svarar på ett utskick — utskickets Agent svarar, eller ingen om utskicket inte hade någon.
4. En specifik Entry Point matchar. Nyckelordsregler slår kommentarsregler, som slår följarregler. Mellan två regler av samma slag vinner den som senast uppdaterades.
5. Kanalens standardinställning för den kanal meddelandet anlände på. En standardinställning begränsad till det specifika nummer kontakten skrev till slår kanalens generella standardinställning.
6. Inget matchade — meddelandet hamnar i inkorgen för ditt team och ingen assistent svarar.

Två saker mildrar steg 6. Ett konto med exakt en aktiv Agent och ingen standardinställning konfigurerad för kanalen får fortfarande den Agenten som svarare, så ett nytt konto som ansluter WhatsApp och skickar ett testmeddelande möts inte av tystnad. Denna lägstanivå gäller aldrig för en kanal som har en nyckelordsregel (där lämnas ett meddelande som inte matchar något nyckelord avsiktligt till en människa) och åsidosätter aldrig en kanal som du har ställt in till ingen (se Lämna en kanal utan svarare).

Huruvida stegen är aktiv för ett konto rapporteras av GET /entry-points/routing-status. Den är på för varje konto idag; anropet finns så att en integration kan kontrollera istället för att anta.

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 nyckelordsregel på en kanal utan kanalstandard fungerar också som en grind: meddelanden som inte matchar något av nyckelorden får inget automatiskt svar och hamnar helt enkelt i din inkorg, även på ett konto med en enda Agent.

Peka en kanal till en Agent #

PUT /entry-points/channel-defaults — gör en Agent till svarare för nya kontakter på en kanal. Alla andra agenter som för närvarande är inställda som kanalens standard tas bort i samma anrop, så en kanal har alltid exakt en svarare. Att ställa in den Agent som redan är standard ändrar ingenting.

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 är regeln som nu gäller; disabled_entry_point_ids listar alla regler som tagits bort för att ge plats åt den (tom när det inte fanns något att ersätta). Endast kontakter du aldrig har pratat med påverkas — alla som redan är i en konversation med en Agent behåller den Agenten.

Ett 400 innebär att channel eller agent_id saknas, att Agenten tillhör ett annat konto eller att phone_number inte är ett av dina anslutna nummer.

Se vem som svarar på varje kanal #

GET /entry-points/channel-defaults — varje kanalstandard på kontot, nyaste först, inklusive borttagna (enabled: false) och en kanal som avsiktligt ställts in på ingen (agent_id: ""). Filtrera på enabled själv för den aktuella bilden.

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

Detta är läsningen för hela kontot. Att lista en Agents regler med GET /agents/{agentId}/entry-points kan inte visa en kanal inställd på ingen, eftersom den regeln inte tillhör någon Agent.

Lämna en kanal utan svarare #

DELETE /entry-points/channel-defaults?channel=instagram — tar bort kanalens globala standard för en kanal. Kanalen namnges som en frågeparameter, inte i en brödtext. Lägg till &phone_number=%2B31685101091 för att endast rensa det numrets standard och låta numret gå tillbaka till den som svarar på 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"] }

Säkert att upprepa: att rensa en kanal som inte har någon standard är ett 200 med en tom lista. Att rensa betyder avmarkera, inte tysta — på ett konto med exakt en aktiv Agent faller en okonfigurerad kanal fortfarande tillbaka på den Agenten. För att hålla AI:n borta från en kanal helt, välj Ingen svarar för den i appens panel Vem svarar på nya konversationer (det skriver en explicit “ingen”-standard som fallbacken aldrig åsidosätter), eller pausa Agenten med PATCH /agents/{agentId}/active.

En Agent per WhatsApp-nummer #

Routing sker per kanal som standard: alla dina WhatsApp-nummer delar en svarare. Med två eller fler nummer anslutna på WhatsApp Business eller WhatsApp Web kan en standard begränsas till ett enskilt nummer, så att ett företag med ett nummer per filial eller varumärke kan ge varje nummer sin egen Agent inom ett konto.

Skicka phone_number med set-anropet:

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

• Numret måste vara ett av dina anslutna nummer på den kanalen, skrivet så som det visas under anslutna nummer (E.164 med +); allt annat är ett 400.
• Regeln lagras som en kanalstandard med match_config.phone_numbers: ["+31685101091"]. Ett meddelande som anländer till det numret går till dess Agent; alla andra nummer fortsätter att följa kanalens standardinställning.
• Att ställa in eller rensa kanalens standardinställning påverkar inte nummer-specifika regler, och vice versa. Rensa ett nummers egen regel med DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Svar skickas alltid från det nummer som kontakten skrev till, så att kontakten fortsätter att prata med samma nummer och samma Agent.

Lägg till en mer specifik regel #

POST /agents/{agentId}/entry-points — skapar en regel för nyckelord, kommentarer eller följare (eller en kanalstandard, även om PUT /entry-points/channel-defaults är ett bättre val för det eftersom det automatiskt avaktiverar den tidigare svararen åt dig). Agenten i sökvägen vinner alltid: en regel kan aldrig skapas för en annan Agent än den som finns 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 regel för kommentar-till-DM som endast reagerar på kommentarer som säger “LINK” på två specifika inlägg, väntar två minuter och skickar ett fast första meddelande:

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

Lämna keywords tomt för att skicka DM till alla som kommenterar de bevakade inläggen, och post_ids tomt för att bevaka varje inlägg. Ett 400 anger vad som är fel: ett okänt type, ett tomt channels, en nyckelordsregel utan nyckelord, eller en kommentarsregel som inte listar sin egen kanal.

Lista en Agents regler #

GET /agents/{agentId}/entry-points — reglerna som skickar konversationer till denna Agent, sorterade från nyast till äldst: dess kanalstandarder, nyckelordsregler, kommentarsregler och följarregler. Avaktiverade regler kommer också tillbaka, 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
    }
  ]
}

Ändra en regel #

PUT /entry-points/{entryPointId} — ändrar en regel. Skicka endast de fält du ändrar; nästlade inställningar kan adresseras blad för blad med en punktmarkerad nyckel såsom "match_config.keywords". Närhelst ändringen rör type, channels eller match_config, kontrolleras hela regeln på nytt, så en partiell redigering kan aldrig lämna kvar en oanvändbar regel (att byta type till keyword utan att ange nyckelord avvisas). Att skicka agent_id överlämnar regeln till en annan av dina Agenter; en tom sådan avvisas. Ägande- och identitetsfält ignoreras.

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

Andra vanliga redigeringar: { "enabled": false } avaktiverar en regel utan att ta bort den, och { "agent_id": "agOtherAgent" } flyttar den till en annan Agent. En tom brödtext returnerar 400 med "No fields to update".

Ta bort en regel #

DELETE /entry-points/{entryPointId} — tar bort regeln permanent. Inget annat refererar till en Entry Point, så det finns inget att koppla loss 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" }

För att stoppa en regel från att köras men behålla den, ställ in enabled till false istället. Kanalstandarder avaktiveras normalt snarare än raderas, vilket är vad DELETE /entry-points/channel-defaults gör.

Kontrollera att routingen är aktiv #

GET /entry-points/routing-status — returnerar om Entry Points-stegen avgör vem som svarar på detta konto. Kan läsas med läsbehörighet, så att en teammedlem ser samma svar som ägaren.

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

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

Det är true på varje konto idag. Anropet behålls så att en integration kan verifiera innan den meddelar någon att deras routingsändring är live, istället för att anta det.

De äldre, kampanjformade anropen #

Två slutpunkter från tiden före agenter fungerar fortfarande för konton som är organiserade kring kampanjer. Nya integrationer bör använda kanalstandardanropen ovan istället.

• PUT /channel-routing/{channel} med { "campaignId": "cp5NbV8xQrT2wYzA" } — namnger en kampanj, och den kampanjens agent blir kanalens svarare. { "campaignId": null } rensar kanalen. En kampanj som endast är för utgående samtal avvisas eftersom den inte har något inkommande beteende att erbjuda.
• POST /channel-routing/clear med { "channels": ["whatsapp", "instagram"] } — frigör flera kanaler från vilken agent som än svarar på dem i ett anrop, vanligtvis innan de pekas om någon annanstans. Svaret listar released_channels, de som faktiskt hade en svarare.

Båda återställer snarare än tystar: på ett konto med exakt en aktiv agent faller en frigjord kanal fortfarande tillbaka på den agenten.

Fel i Entry Points-API:et #

Entry Point-slutpunkter returnerar standardfelkuvertet:

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

De delade koderna som alla slutpunkter kan returnera — 401, 403 (din plan inkluderar inte API-åtkomst), 429 (hastighetsbegränsning) och 500 — listas med vägledning för återförsök i Fel & Paginering.

Nästa steg #

• Entry Points — konceptet, regeltyperna och panelen Vem svarar på nya konversationer i appen.
• AI Agents API — skapa och konfigurera agenterna som dessa regler dirigerar till.
• Channels API — anslut själva kanalerna.
• Automatisering av kommentar till DM — vad kommentarsreglerna gör när de aktiveras.