Entry Points API #

Ein Entry Point ist eine Routing-Regel: „Wenn dies auf diesem Kanal passiert, übergib die Konversation an diesen Agenten“. Das Verbinden eines Kanals bringt Nachrichten in das Konto und das Erstellen eines Agenten gibt Ihnen jemanden, der antworten kann, aber keiner von beiden entscheidet, wer die erste Nachricht eines Fremden beantwortet. Das tun Entry Points. Informationen zum Produkt selbst finden Sie im Entry Points-Leitfaden.

• Basis-URL — https://api.youraiconnector.com/v1
• Authentifizierung — Ihr API-Schlüssel (siehe Authentifizierung)
• Fehler & Paginierung — siehe Fehler & Paginierung

Alle nachstehenden Beispiele zeigen die ?apiKey=-Abfrageform in cURL und den X-API-Key-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

Im API-Explorer. Jeder Endpunkt auf dieser Seite ist in der veröffentlichten OpenAPI-Spezifikation enthalten, sodass Sie die genauen Felder durchsuchen und Live-Anfragen im API-Explorer ausführen können.

Der eine Aufruf, den die meisten Integrationen benötigen #

Verbinden Sie einen Kanal, erstellen Sie einen Agenten und weisen Sie den Kanal dann dem Agenten zu:

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

Das ist die gesamte Einrichtung für „dieser Agent antwortet auf WhatsApp“. Alles andere auf dieser Seite dient spezifischeren Regeln (Schlüsselwörter, Kommentare, neue Follower), mehreren Nummern auf einem Kanal und dem Auslesen der Konfiguration.

Wie das Routing entschieden wird #

Wenn eine Nachricht eingeht, durchläuft die Plattform eine feste Hierarchie, und der erste Schritt, der eine Entscheidung trifft, gewinnt:

1. Ein Mensch hat die Konversation übernommen — keine KI.
2. Der Kontakt ist bereits einem Agenten zugewiesen, manuell oder weil eine Konversation mit diesem Agenten im Gange ist — derselbe Agent behält sie. Entry Points verschieben niemals eine bestehende Konversation; um einen Chat an einen anderen Agenten zu übergeben, weisen Sie ihn zu (in der App oder mit der Automatisierungs-Aktion).
3. Der Kontakt antwortet auf einen Broadcast — der Agent des Broadcasts antwortet, oder niemand, falls der Broadcast keinen hatte.
4. Ein spezifischer Entry Point stimmt überein. Schlüsselwort-Regeln schlagen Kommentar-Regeln, die wiederum Follower-Regeln schlagen. Zwischen zwei Regeln der gleichen Art gewinnt die zuletzt aktualisierte.
5. Der Kanal-Standardwert für den Kanal, auf dem die Nachricht eingegangen ist. Ein Standardwert, der auf die spezifische Nummer begrenzt ist, an die der Kontakt geschrieben hat, schlägt den kanalweiten Standardwert.
6. Nichts stimmte überein — die Nachricht landet im Posteingang für Ihr Team und kein Assistent antwortet.

Zwei Dinge mildern Schritt 6 ab. Ein Konto mit genau einem aktiven Agenten und ohne für den Kanal konfigurierten Standardwert erhält dennoch diesen Agenten als Antwortenden, sodass ein neues Konto, das WhatsApp verbindet und eine Testnachricht sendet, nicht ignoriert wird. Diese Untergrenze gilt nie für einen Kanal, der eine Schlüsselwort-Regel hat (dort wird eine Nachricht, die mit keinem Schlüsselwort übereinstimmt, bewusst einem Menschen überlassen) und überschreibt niemals einen Kanal, den Sie auf „niemand“ gesetzt haben (siehe Einen Kanal ohne Antwortenden belassen).

Ob die Hierarchie für ein Konto aktiv ist, wird durch GET /entry-points/routing-status gemeldet. Sie ist heute für jedes Konto aktiviert; der Aufruf existiert, damit eine Integration dies prüfen kann, anstatt es vorauszusetzen.

Das Entry Point-Objekt #

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

Eine Schlüsselwortregel für einen Kanal ohne Kanal-Standardeinstellung fungiert auch als Filter: Nachrichten, die auf keines der Schlüsselwörter passen, erhalten keine automatische Antwort und landen einfach in Ihrem Posteingang, selbst bei einem Konto mit nur einem Agenten.

Einen Kanal einem Agenten zuweisen #

PUT /entry-points/channel-defaults – macht einen Agenten zum Antwortenden für neue Kontakte auf einem Kanal. Jeder andere Agent, der aktuell als Standard für diesen Kanal festgelegt ist, wird im selben Aufruf abgelöst, sodass ein Kanal immer genau einen Antwortenden hat. Das Festlegen des Agenten, der bereits der Standard ist, ändert nichts.

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

Antwort

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

entry_point_id ist die nun geltende Regel; disabled_entry_point_ids listet alle Regeln auf, die abgelöst wurden, um Platz dafür zu schaffen (leer, wenn nichts zu ersetzen war). Nur Kontakte, mit denen Sie noch nie gesprochen haben, sind betroffen – jeder, der bereits in einem Gespräch mit einem Agenten ist, behält diesen Agenten.

Ein 400 bedeutet, dass channel oder agent_id fehlt, der Agent zu einem anderen Konto gehört oder phone_number keine Ihrer verbundenen Nummern ist.

Sehen, wer auf welchem Kanal antwortet #

GET /entry-points/channel-defaults – jede Kanal-Standardeinstellung des Kontos, die neuesten zuerst, einschließlich abgelöster (enabled: false) und eines Kanals, der bewusst auf „Niemand“ gesetzt wurde (agent_id: ""). Filtern Sie selbst nach enabled, um den aktuellen Stand zu sehen.

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

Antwort

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

Dies ist die kontoweite Übersicht. Das Auflisten der Regeln eines Agenten mit GET /agents/{agentId}/entry-points kann keinen Kanal anzeigen, der auf „Niemand“ gesetzt ist, da diese Regel zu keinem Agenten gehört.

Einen Kanal ohne Antwortenden belassen #

DELETE /entry-points/channel-defaults?channel=instagram – löst die kanalweite Standardeinstellung für einen Kanal ab. Der Kanal wird als Abfrageparameter benannt, nicht im Body. Fügen Sie &phone_number=%2B31685101091 hinzu, um nur die Standardeinstellung dieser Nummer zu löschen und die Nummer wieder demjenigen zuzuweisen, der den Kanal beantwortet.

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

Antwort

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

Sicher zu wiederholen: Das Löschen eines Kanals ohne Standardeinstellung ist ein 200 mit einer leeren Liste. Löschen bedeutet aufheben, nicht stummschalten – auf einem Konto mit genau einem aktiven Agenten greift ein nicht konfigurierter Kanal weiterhin auf diesen Agenten zurück. Um die KI vollständig von einem Kanal fernzuhalten, wählen Sie im Bereich Wer beantwortet neue Konversationen der App die Option Niemand antwortet (dies schreibt eine explizite „Niemand“-Standardeinstellung, die vom Fallback niemals überschrieben wird), oder pausieren Sie den Agenten mit PATCH /agents/{agentId}/active.

Ein Agent pro WhatsApp-Nummer #

Das Routing erfolgt standardmäßig pro Kanal: Alle Ihre WhatsApp-Nummern teilen sich einen Antwortenden. Bei zwei oder mehr verbundenen Nummern über WhatsApp Business oder WhatsApp Web kann eine Standardeinstellung auf eine einzelne Nummer beschränkt werden, sodass ein Unternehmen mit einer Nummer pro Filiale oder Marke jedem Bereich innerhalb eines Kontos einen eigenen Agenten zuweisen kann.

Senden Sie phone_number mit dem Set-Aufruf:

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

• Die Nummer muss eine Ihrer verbundenen Nummern auf diesem Kanal sein, geschrieben wie unter verbundenen Nummern angezeigt (E.164 mit dem +); alles andere ist ein 400.
• Die Regel wird als Kanalstandard mit match_config.phone_numbers: ["+31685101091"] gespeichert. Eine Nachricht, die unter dieser Nummer eingeht, geht an deren Agenten; jede andere Nummer folgt weiterhin dem kanalweiten Standard.
• Das Festlegen oder Löschen des kanalweiten Standards lässt nummernspezifische Regeln unberührt und umgekehrt. Löschen Sie die eigene Regel einer Nummer mit DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Antworten werden immer von der Nummer gesendet, an die der Kontakt geschrieben hat, sodass der Kontakt weiterhin mit derselben Nummer und demselben Agenten spricht.

Eine spezifischere Regel hinzufügen #

POST /agents/{agentId}/entry-points — erstellt eine Keyword-, Kommentar- oder Follower-Regel (oder einen Kanalstandard, obwohl PUT /entry-points/channel-defaults dafür die bessere Wahl ist, da es den vorherigen Antwortenden für Sie in den Ruhestand versetzt). Der Agent im Pfad gewinnt immer: Eine Regel kann niemals für einen anderen Agenten erstellt werden als den, der in der URL angegeben ist.

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

Antwort (201)

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

Eine Kommentar-zu-DM-Regel, die nur auf Kommentare reagiert, die „LINK“ unter zwei bestimmten Beiträgen enthalten, zwei Minuten wartet und eine feste erste Nachricht sendet:

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

Lassen Sie keywords leer, um jedem eine DM zu senden, der die überwachten Beiträge kommentiert, und post_ids leer, um jeden Beitrag zu überwachen. Ein 400 benennt, was falsch ist: ein unbekanntes type, ein leeres channels, eine Keyword-Regel ohne Keywords oder eine Kommentar-Regel, die ihren eigenen Kanal nicht auflistet.

Regeln eines Agenten auflisten #

GET /agents/{agentId}/entry-points — die Regeln, die Konversationen an diesen Agenten senden, beginnend mit der neuesten: seine Kanalstandards, Keyword-Regeln, Kommentar-Regeln und Follower-Regeln. Regeln im Ruhestand werden ebenfalls zurückgegeben, mit 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()

Antwort

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

Eine Regel ändern #

PUT /entry-points/{entryPointId} — ändert eine Regel. Senden Sie nur die Felder, die Sie ändern; verschachtelte Einstellungen können Blatt für Blatt mit einem punktierten Schlüssel wie "match_config.keywords" adressiert werden. Wann immer die Änderung type, channels oder match_config betrifft, wird die gesamte Regel erneut überprüft, sodass eine teilweise Bearbeitung niemals eine unbrauchbare Regel hinterlassen kann (das Wechseln von type zu keyword ohne Angabe von Keywords wird abgelehnt). Das Senden von agent_id übergibt die Regel an einen anderen Ihrer Agenten; ein leerer Wert wird abgelehnt. Eigentums- und Identitätsfelder werden ignoriert.

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

Antwort

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

Weitere häufige Bearbeitungen: { "enabled": false } versetzt eine Regel in den Ruhestand, ohne sie zu löschen, und { "agent_id": "agOtherAgent" } verschiebt sie zu einem anderen Agenten. Ein leerer Body gibt 400 mit "No fields to update" zurück.

Eine Regel löschen #

DELETE /entry-points/{entryPointId} — entfernt die Regel dauerhaft. Nichts anderes verweist auf einen Entry Point, daher muss vorher nichts getrennt werden.

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

Antwort

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

Um zu verhindern, dass eine Regel ausgelöst wird, sie aber beizubehalten, setzen Sie enabled stattdessen auf false. Insbesondere Kanalstandards werden normalerweise eher in den Ruhestand versetzt als gelöscht, was DELETE /entry-points/channel-defaults bewirkt.

Überprüfen, ob das Routing aktiv ist #

GET /entry-points/routing-status — gibt zurück, ob die Entry Points-Hierarchie entscheidet, wer auf diesem Konto antwortet. Lesbar mit Lesezugriff, sodass ein Teammitglied dieselbe Antwort sieht wie der Inhaber.

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

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

Es ist heute auf jedem Konto true. Der Aufruf wird beibehalten, damit eine Integration dies überprüfen kann, bevor sie jemandem mitteilt, dass seine Routing-Änderung live ist, anstatt dies nur anzunehmen.

Die älteren, kampagnenbasierten Aufrufe #

Zwei Endpunkte aus der Zeit vor den Agents funktionieren weiterhin für Konten, die um Kampagnen herum organisiert sind. Neue Integrationen sollten die oben genannten Channel-Defaults-Aufrufe verwenden.

• PUT /channel-routing/{channel} mit { "campaignId": "cp5NbV8xQrT2wYzA" } — benennt eine Kampagne, und der Agent dieser Kampagne wird zum Antwortenden des Kanals. { "campaignId": null } leert den Kanal. Eine reine Ausgangskampagne wird abgelehnt, da sie kein eingehendes Verhalten bietet.
• POST /channel-routing/clear mit { "channels": ["whatsapp", "instagram"] } — befreit mehrere Kanäle von dem Agent, der sie in einem Aufruf beantwortet, normalerweise bevor sie woanders hin geleitet werden. Die Antwort listet released_channels auf, also diejenigen, die tatsächlich einen Antwortenden hatten.

Beide setzen zurück, anstatt zu stummschalten: Auf einem Konto mit genau einem aktiven Agent fällt ein befreiter Kanal immer noch auf diesen Agent zurück.

Entry Points API-Fehler #

Entry Point-Endpunkte geben den Standard-Fehler-Envelope zurück:

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

Die gemeinsamen Codes, die jeder Endpunkt zurückgeben kann — 401, 403 (Ihr Plan beinhaltet keinen API-Zugriff), 429 (Ratenbegrenzung) und 500 — sind zusammen mit Hinweisen zur Wiederholung unter Fehler & Paginierung aufgeführt.

Nächste Schritte #

• Entry Points — das Konzept, die Regeltypen und das Panel Wer beantwortet neue Konversationen in der App.
• AI Agents API — Erstellen und Konfigurieren der Agents, an die diese Regeln weiterleiten.
• Channels API — Verbinden der Kanäle selbst.
• Kommentar-zu-DM-Automatisierung — was die Kommentarregeln tun, sobald sie ausgelöst werden.