API punktów wejścia #

Punkt wejścia to reguła routingu: „gdy wydarzy się to na tym kanale, przekaż konwersację temu Agentowi”. Podłączenie kanału pozwala na odbieranie wiadomości na koncie, a utworzenie Agenta daje możliwość udzielenia odpowiedzi, ale żadna z tych czynności nie decyduje o tym, kto odpowie na pierwszą wiadomość od nieznajomego. Robią to punkty wejścia. Informacje o samym produkcie znajdują się w przewodniku po punktach wejścia.

• Podstawowy adres URL — https://api.youraiconnector.com/v1
• Uwierzytelnianie — Twój klucz API (zobacz Uwierzytelnianie)
• Błędy i stronicowanie — zobacz Błędy i stronicowanie

Wszystkie poniższe przykłady pokazują formularz zapytania ?apiKey= w cURL oraz nagłówek X-API-Key w JavaScript i Pythonie — oba działają w każdym punkcie końcowym.

W eksploratorze API. Każdy punkt końcowy na tej stronie znajduje się w opublikowanej specyfikacji OpenAPI, dzięki czemu możesz przeglądać jego dokładne pola i uruchamiać zapytania na żywo w eksploratorze API.

Jedno wywołanie, którego potrzebuje większość integracji #

Podłącz kanał, utwórz Agenta, a następnie skieruj kanał na Agenta:

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

To cała konfiguracja dla scenariusza „ten Agent odpowiada na WhatsApp”. Wszystko inne na tej stronie dotyczy węższych reguł (słowa kluczowe, komentarze, nowi obserwujący), wielu numerów na jednym kanale oraz odczytywania bieżącej konfiguracji.

Jak podejmowana jest decyzja o routingu #

Gdy nadejdzie wiadomość, platforma przechodzi przez ustaloną hierarchię, a pierwszy krok, który podejmie decyzję, wygrywa:

1. Człowiek przejął konwersację — brak AI.
2. Kontakt jest już przypisany do Agenta, ręcznie lub dlatego, że konwersacja z tym Agentem trwa — ten sam Agent ją kontynuuje. Punkty wejścia nigdy nie przenoszą istniejącej konwersacji; aby przekazać czat innemu Agentowi, przypisz go (w aplikacji lub za pomocą akcji Automatyzacje).
3. Kontakt odpowiada na transmisję — odpowiada Agent transmisji lub nikt, jeśli transmisja go nie miała.
4. Dopasowano wąski punkt wejścia. Reguły słów kluczowych wygrywają z regułami komentarzy, które wygrywają z regułami obserwujących. Pomiędzy dwiema regułami tego samego rodzaju wygrywa ta, która została ostatnio zaktualizowana.
5. Domyślne ustawienie kanału, na który nadeszła wiadomość. Ustawienie domyślne ograniczone do konkretnego numeru, na który napisał kontakt, wygrywa z ustawieniem domyślnym dla całego kanału.
6. Nic nie pasuje — wiadomość trafia do skrzynki odbiorczej Twojego zespołu i żaden asystent nie odpowiada.

Dwie rzeczy łagodzą krok 6. Konto z dokładnie jednym aktywnym Agentem i bez skonfigurowanego ustawienia domyślnego dla kanału nadal otrzymuje tego Agenta jako odpowiadającego, więc nowe konto, które łączy WhatsApp i wysyła wiadomość testową, nie pozostaje w ciszy. Ta zasada nigdy nie ma zastosowania do kanału, który ma regułę słowa kluczowego (tam wiadomość, która nie pasuje do żadnego słowa kluczowego, jest celowo pozostawiana człowiekowi) i nigdy nie nadpisuje kanału, który ustawiłeś na „nikt” (zobacz Pozostawienie kanału bez odpowiedzi).

To, czy hierarchia jest aktywna dla konta, jest raportowane przez GET /entry-points/routing-status. Obecnie jest ona włączona dla każdego konta; wywołanie istnieje po to, aby integracja mogła to sprawdzić, zamiast zakładać.

Obiekt punktu wejścia #

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

Typy reguł #

Reguła słowa kluczowego na kanale bez domyślnego ustawienia kanału działa również jako bramka: wiadomości, które nie pasują do żadnego ze słów kluczowych, nie otrzymują automatycznej odpowiedzi i po prostu trafiają do Twojej skrzynki odbiorczej, nawet na koncie z jednym Agentem.

Przypisz kanał do Agenta #

PUT /entry-points/channel-defaults — sprawia, że jeden Agent staje się osobą odpowiadającą na nowe kontakty na danym kanale. Każdy inny Agent ustawiony obecnie jako domyślny dla tego kanału jest wycofywany w tym samym wywołaniu, dzięki czemu kanał ma zawsze dokładnie jedną osobę odpowiadającą. Ustawienie Agenta, który już jest domyślny, niczego nie zmienia.

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

Odpowiedź

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

entry_point_id to reguła obecnie obowiązująca; disabled_entry_point_ids zawiera listę wszystkich reguł wycofanych, aby zrobić dla niej miejsce (puste, jeśli nie było nic do zastąpienia). Dotyczy to tylko kontaktów, z którymi nigdy nie rozmawiałeś — każdy, kto jest już w trakcie rozmowy z Agentem, zachowuje tego Agenta.

400 oznacza, że brakuje channel lub agent_id, Agent należy do innego konta lub phone_number nie jest jednym z Twoich połączonych numerów.

Zobacz, kto odpowiada na poszczególnych kanałach #

GET /entry-points/channel-defaults — domyślne ustawienia każdego kanału na koncie, od najnowszego, w tym wycofane (enabled: false) oraz kanał celowo ustawiony na nikogo (agent_id: ""). Przefiltruj enabled samodzielnie, aby uzyskać aktualny obraz.

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

Odpowiedź

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

To jest odczyt dla całego konta. Wyświetlenie reguł jednego Agenta za pomocą GET /agents/{agentId}/entry-points nie może pokazać kanału ustawionego na nikogo, ponieważ ta reguła nie należy do żadnego Agenta.

Opuść kanał, na którym nikt nie odpowiada #

DELETE /entry-points/channel-defaults?channel=instagram — wycofuje domyślne ustawienie dla całego kanału. Kanał jest podawany jako parametr zapytania, a nie w treści. Dodaj &phone_number=%2B31685101091, aby wyczyścić tylko domyślne ustawienie dla tego numeru i pozwolić, aby numer wrócił do osoby, która odpowiada na kanale.

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

Odpowiedź

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

Można bezpiecznie powtarzać: wyczyszczenie kanału, który nie ma ustawienia domyślnego, kończy się 200 z pustą listą. Czyszczenie oznacza brak ustawienia, a nie wyciszenie — na koncie z dokładnie jednym aktywnym Agentem nieskonfigurowany kanał nadal przypada temu Agentowi. Aby całkowicie wyłączyć sztuczną inteligencję na kanale, wybierz Nikt nie odpowiada w panelu aplikacji Kto odpowiada na nowe rozmowy (co zapisuje jawne domyślne ustawienie „nikt”, którego mechanizm rezerwowy nigdy nie nadpisuje) lub wstrzymaj pracę Agenta za pomocą PATCH /agents/{agentId}/active.

Jeden Agent na numer WhatsApp #

Domyślnie routing odbywa się według kanału: wszystkie Twoje numery WhatsApp współdzielą jednego odpowiadającego. W przypadku dwóch lub więcej numerów połączonych w WhatsApp Business lub WhatsApp Web, ustawienie domyślne można ograniczyć do pojedynczego numeru, dzięki czemu firma z numerem dla każdego oddziału lub marki może przypisać każdemu z nich własnego Agenta w ramach jednego konta.

Wyślij phone_number wraz z wywołaniem ustawienia:

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

• Numer musi być jednym z Twoich połączonych numerów na tym kanale, zapisanym tak, jak widnieje w sekcji połączonych numerów (E.164 z +); wszystko inne jest 400.
• Reguła jest zapisywana jako domyślna dla kanału za pomocą match_config.phone_numbers: ["+31685101091"]. Wiadomość, która dotrze na ten numer, trafi do przypisanego mu Agenta; każdy inny numer nadal korzysta z domyślnych ustawień całego kanału.
• Ustawienie lub usunięcie domyślnych ustawień kanału nie wpływa na reguły przypisane do konkretnych numerów i odwrotnie. Usuń regułę przypisaną do numeru za pomocą DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Odpowiedzi zawsze są wysyłane z numeru, na który napisał kontakt, dzięki czemu kontakt rozmawia z tym samym numerem i tym samym Agentem.

Dodaj węższą regułę #

POST /agents/{agentId}/entry-points — tworzy regułę słowa kluczowego, komentarza lub obserwującego (lub domyślną regułę kanału, chociaż PUT /entry-points/channel-defaults jest do tego lepszym wyborem, ponieważ automatycznie wycofuje poprzedniego odbiorcę). Agent w ścieżce zawsze ma pierwszeństwo: reguła nigdy nie może zostać utworzona dla innego Agenta niż ten wskazany w adresie 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()

Odpowiedź (201)

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

Reguła komentarza do wiadomości prywatnej (DM), która reaguje tylko na komentarze zawierające słowo „LINK” pod dwoma konkretnymi postami, czeka dwie minuty i wysyła ustaloną pierwszą wiadomość:

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

Pozostaw keywords puste, aby wysłać DM do każdego, kto skomentuje monitorowane posty, oraz post_ids puste, aby monitorować każdy post. 400 wskazuje, co jest nie tak: nieznany type, puste channels, reguła słowa kluczowego bez słów kluczowych lub reguła komentarza, która nie wymienia własnego kanału.

Wyświetl reguły Agenta #

GET /agents/{agentId}/entry-points — reguły, które kierują konwersacje do tego Agenta, od najnowszych: domyślne ustawienia kanału, reguły słów kluczowych, reguły komentarzy i reguły obserwujących. Wycofane reguły również powracają za pomocą 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()

Odpowiedź

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

Zmień regułę #

PUT /entry-points/{entryPointId} — zmienia jedną regułę. Wyślij tylko te pola, które zmieniasz; zagnieżdżone ustawienia można adresować element po elemencie za pomocą klucza z kropką, takiego jak "match_config.keywords". Ilekroć zmiana dotyczy type, channels lub match_config, cała reguła jest sprawdzana ponownie, więc częściowa edycja nigdy nie pozostawi bezużytecznej reguły (przełączenie type na keyword bez podania słów kluczowych zostanie odrzucone). Wysłanie agent_id przekazuje regułę innemu Twojemu Agentowi; pusta wartość zostanie odrzucona. Pola własności i tożsamości są ignorowane.

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

Odpowiedź

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

Inne typowe edycje: { "enabled": false } wycofuje regułę bez jej usuwania, a { "agent_id": "agOtherAgent" } przenosi ją do innego Agenta. Puste ciało żądania zwraca 400 wraz z "No fields to update".

Usuń regułę #

DELETE /entry-points/{entryPointId} — usuwa regułę na stałe. Nic innego nie odwołuje się do punktu wejścia, więc nie ma nic do odłączania w pierwszej kolejności.

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

Odpowiedź

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

Aby zatrzymać działanie reguły, ale zachować ją w systemie, ustaw enabled na false. W szczególności domyślne ustawienia kanału są zazwyczaj wycofywane, a nie usuwane, co właśnie robi DELETE /entry-points/channel-defaults.

Sprawdź, czy routing działa #

GET /entry-points/routing-status — zwraca informację, czy drabinka punktów wejścia (Entry Points) decyduje o tym, kto odpowiada na tym koncie. Dostępne do odczytu z uprawnieniami podglądu, dzięki czemu członek zespołu widzi tę samą odpowiedź co właściciel.

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

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

Obecnie na każdym koncie jest to true. Wywołanie jest zachowywane, aby integracja mogła zweryfikować zmianę przed poinformowaniem kogoś, że zmiana routingu jest aktywna, zamiast zakładać to z góry.

Starsze wywołania oparte na kampaniach #

Dwa punkty końcowe sprzed wprowadzenia Agentów nadal działają dla kont zorganizowanych wokół kampanii. Nowe integracje powinny korzystać z powyższych wywołań domyślnych kanałów.

• PUT /channel-routing/{channel} z { "campaignId": "cp5NbV8xQrT2wYzA" } — nazywa kampanię, a Agent tej kampanii staje się osobą odpowiadającą na kanale. { "campaignId": null } czyści kanał. Kampania tylko wychodząca jest odrzucana, ponieważ nie oferuje żadnego zachowania przychodzącego.
• POST /channel-routing/clear z { "channels": ["whatsapp", "instagram"] } — zwalnia kilka kanałów z przypisanego do nich Agenta w jednym wywołaniu, zazwyczaj przed skierowaniem ich w inne miejsce. Odpowiedź zawiera listę released_channels, czyli tych, które faktycznie miały osobę odpowiadającą.

Oba ustawienia oznaczają raczej brak ustawienia niż wyciszenie: na koncie z dokładnie jednym aktywnym Agentem zwolniony kanał nadal wraca do tego Agenta.

Błędy API punktów wejścia (Entry Points) #

Punkty końcowe Entry Point zwracają standardową kopertę błędu:

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

Wspólne kody, które może zwrócić każdy punkt końcowy — 401, 403 (Twój plan nie obejmuje dostępu do API), 429 (limit szybkości) oraz 500 — zostały wymienione wraz ze wskazówkami dotyczącymi ponawiania prób w sekcji Błędy i stronicowanie.

Następne kroki #

• Punkty wejścia (Entry Points) — koncepcja, typy reguł oraz panel Kto odpowiada na nowe konwersacje w aplikacji.
• API Agentów AI — tworzenie i konfigurowanie Agentów, do których kierują te reguły.
• API kanałów — łączenie samych kanałów.
• Automatyzacja komentarzy do wiadomości prywatnych — co robią reguły komentarzy po ich uruchomieniu.