API Puncte de Intrare #

Un Punct de Intrare este o regulă de rutare: „când se întâmplă acest lucru pe acest canal, transmite conversația către acest Agent”. Conectarea unui canal aduce mesaje în cont, iar crearea unui Agent îți oferă ceva care poate răspunde, dar niciuna dintre acestea nu decide cine răspunde la primul mesaj al unui străin. Punctele de Intrare fac acest lucru. Pentru produsul în sine, consultă ghidul Punctelor de Intrare.

• URL de bază — https://api.youraiconnector.com/v1
• Autentificare — cheia ta API (vezi Autentificare)
• Erori și paginare — vezi Erori și paginare

Toate exemplele de mai jos arată forma de interogare ?apiKey= în cURL și antetul X-API-Key în JavaScript și Python — oricare dintre ele funcționează pe fiecare endpoint.

În exploratorul API. Fiecare endpoint de pe această pagină se află în specificația OpenAPI publicată, astfel încât puteți naviga prin câmpurile sale exacte și puteți rula cereri live în exploratorul API.

Singurul apel de care au nevoie majoritatea integrărilor #

Conectează un canal, creează un Agent, apoi direcționează canalul către 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" }'

Aceasta este întreaga configurare pentru „acest Agent răspunde pe WhatsApp”. Tot restul de pe această pagină este pentru reguli mai specifice (cuvinte cheie, comentarii, noi urmăritori), mai multe numere pe un singur canal și citirea configurației curente.

Cum se decide rutarea #

Când sosește un mesaj, platforma parcurge o ierarhie fixă, iar primul pas care ia o decizie câștigă:

1. Un om a preluat conversația — fără AI.
2. Contactul este deja alocat unui Agent, manual sau pentru că o conversație cu acel Agent este în desfășurare — același Agent o păstrează. Punctele de Intrare nu mută niciodată o conversație existentă; pentru a transmite un chat către un alt Agent, alocă-l (în aplicație sau cu acțiunea Automatizări).
3. Contactul răspunde la o difuzare — Agentul difuzării răspunde, sau nimeni dacă difuzarea nu a avut niciunul.
4. Un Punct de Intrare specific se potrivește. Regulile pentru cuvinte cheie bat regulile pentru comentarii, care bat regulile pentru urmăritori. Între două reguli de același tip, cea mai recent actualizată câștigă.
5. Setarea implicită a canalului pe care a sosit mesajul. O setare implicită limitată la numărul specific la care a scris contactul bate setarea implicită la nivel de canal.
6. Nimic nu s-a potrivit — mesajul ajunge în inbox-ul echipei tale și niciun asistent nu răspunde.

Două lucruri atenuează pasul 6. Un cont cu exact un Agent activ și fără nicio setare implicită configurată pentru canal primește totuși acel Agent ca respondent, astfel încât un cont nou care conectează WhatsApp și trimite un mesaj de test nu primește tăcere. Această regulă de bază nu se aplică niciodată unui canal care are o regulă de cuvânt cheie (acolo, un mesaj care nu se potrivește cu niciun cuvânt cheie este lăsat în mod deliberat pentru un om) și nu suprascrie niciodată un canal pe care l-ai setat să nu aibă niciun respondent (vezi Lasă un canal fără niciun respondent).

Dacă ierarhia este activă pentru un cont este raportat de GET /entry-points/routing-status. Este activă pentru fiecare cont astăzi; apelul există pentru ca o integrare să poată verifica în loc să presupună.

Obiectul Punct de Intrare #

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

Tipuri de reguli #

O regulă bazată pe cuvinte cheie pe un canal fără o setare implicită a canalului funcționează și ca o poartă: mesajele care nu corespund niciunuia dintre cuvintele cheie nu primesc niciun răspuns automat și ajung pur și simplu în căsuța de e-mail, chiar și într-un cont cu un singur Agent.

Direcționați un canal către un Agent #

PUT /entry-points/channel-defaults — desemnează un Agent ca răspunzător pentru contactele noi pe un canal. Orice alt Agent setat în prezent ca implicit pentru acel canal este retras în același apel, astfel încât un canal să aibă întotdeauna exact un răspunzător. Setarea Agentului care este deja implicit nu schimbă nimic.

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

Răspuns

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

entry_point_id este regula în vigoare acum; disabled_entry_point_ids listează orice reguli retrase pentru a face loc acesteia (gol când nu a fost nimic de înlocuit). Doar contactele cu care nu ați vorbit niciodată sunt afectate — oricine se află deja într-o conversație cu un Agent păstrează acel Agent.

O 400 înseamnă că channel sau agent_id lipsește, Agentul aparține unui alt cont sau phone_number nu este unul dintre numerele dumneavoastră conectate.

Vedeți cine răspunde pe fiecare canal #

GET /entry-points/channel-defaults — setarea implicită pentru fiecare canal din cont, cele mai noi primele, inclusiv cele retrase (enabled: false) și un canal setat în mod deliberat pe nimeni (agent_id: ""). Filtrați pe enabled pentru a vedea imaginea actuală.

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

Răspuns

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

Aceasta este citirea la nivel de cont. Listarea regulilor unui singur Agent cu GET /agents/{agentId}/entry-points nu poate afișa un canal setat pe nimeni, deoarece acea regulă nu aparține niciunui Agent.

Părăsirea unui canal fără niciun răspuns #

DELETE /entry-points/channel-defaults?channel=instagram — retrage setarea implicită la nivel de canal pentru un canal. Canalul este numit ca parametru de interogare, nu în corp. Adăugați &phone_number=%2B31685101091 pentru a șterge doar setarea implicită a acelui număr și a lăsa numărul să revină la oricine răspunde la canal.

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

Răspuns

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

Sigur de repetat: ștergerea unui canal care nu are nicio setare implicită este un 200 cu o listă goală. Ștergerea înseamnă anulare, nu tăcere — într-un cont cu exact un Agent activ, un canal neconfigurat revine tot la acel Agent. Pentru a menține AI-ul complet în afara unui canal, alegeți Nimeni nu răspunde pentru acesta în panoul Cine răspunde la conversațiile noi din aplicație (aceasta scrie o setare implicită explicită de “nimeni” pe care fallback-ul nu o suprascrie niciodată), sau suspendați Agentul cu PATCH /agents/{agentId}/active.

Un Agent per număr WhatsApp #

Rutarea se face implicit per canal: toate numerele dvs. WhatsApp partajează un singur respondent. Cu două sau mai multe numere conectate pe WhatsApp Business sau WhatsApp Web, o setare implicită poate fi limitată la un singur număr, astfel încât o afacere cu un număr per sucursală sau marcă poate oferi fiecăruia propriul Agent în cadrul unui singur cont.

Trimiteți phone_number cu apelul set:

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

• Numărul trebuie să fie unul dintre numerele tale conectate pe acel canal, scris așa cum apare la numere conectate (E.164 cu +); orice altceva este o 400.
• Regula este stocată ca o setare implicită a canalului cu match_config.phone_numbers: ["+31685101091"]. Un mesaj care sosește pe acel număr merge la Agentul său; orice alt număr continuă să urmeze setarea implicită a canalului.
• Setarea sau ștergerea setării implicite a canalului lasă intacte regulile specifice numerelor și invers. Șterge regula proprie a unui număr cu DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Răspunsurile sunt trimise întotdeauna de pe numărul la care a scris contactul, astfel încât contactul continuă să comunice cu același număr și cu același Agent.

Adaugă o regulă mai specifică #

POST /agents/{agentId}/entry-points — creează o regulă pentru cuvinte cheie, comentarii sau urmăritori (sau o setare implicită a canalului, deși PUT /entry-points/channel-defaults este alegerea mai bună pentru acest lucru, deoarece retrage automat respondentul anterior). Agentul din cale are întotdeauna prioritate: o regulă nu poate fi creată niciodată pentru un alt Agent decât cel din 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()

Răspuns (201)

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

O regulă de tip comentariu-către-DM care reacționează doar la comentariile ce conțin „LINK” pe două postări specifice, așteaptă două minute și trimite un prim mesaj fix:

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

Lasă keywords gol pentru a trimite DM tuturor celor care comentează la postările urmărite și post_ids gol pentru a urmări fiecare postare. Un 400 indică ce este greșit: un type necunoscut, un channels gol, o regulă pentru cuvinte cheie fără cuvinte cheie sau o regulă pentru comentarii care nu listează propriul canal.

Listează regulile unui Agent #

GET /agents/{agentId}/entry-points — regulile care trimit conversații către acest Agent, cele mai noi primele: setările implicite ale canalului, regulile pentru cuvinte cheie, regulile pentru comentarii și regulile pentru urmăritori. Regulile retrase apar și ele, cu 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()

Răspuns

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

Modifică o regulă #

PUT /entry-points/{entryPointId} — modifică o regulă. Trimite doar câmpurile pe care le schimbi; setările imbricate pot fi accesate element cu element folosind o cheie cu punct, cum ar fi "match_config.keywords". Ori de câte ori modificarea atinge type, channels sau match_config, întreaga regulă este reverificată, astfel încât o editare parțială nu poate lăsa niciodată în urmă o regulă inutilizabilă (schimbarea type în keyword fără a furniza cuvinte cheie este respinsă). Trimiterea agent_id transferă regula către un alt Agent de-al tău; unul gol este respins. Câmpurile de proprietate și identitate sunt ignorate.

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

Răspuns

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

Alte editări comune: { "enabled": false } retrage o regulă fără a o șterge, iar { "agent_id": "agOtherAgent" } o mută la un alt Agent. Un corp gol returnează 400 cu "No fields to update".

Șterge o regulă #

DELETE /entry-points/{entryPointId} — elimină regula definitiv. Nimic altceva nu face referire la un Punct de Intrare, deci nu există nimic de detașat mai întâi.

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

Răspuns

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

Pentru a opri activarea unei reguli, dar a o păstra, setează enabled la false. Setările implicite ale canalului, în special, sunt de obicei retrase mai degrabă decât șterse, ceea ce face DELETE /entry-points/channel-defaults.

Verifică dacă rutarea este activă #

GET /entry-points/routing-status — returnează dacă ierarhia Punctelor de Intrare decide cine răspunde în acest cont. Poate fi citit cu acces de vizualizare, astfel încât un coleg vede același răspuns ca și proprietarul.

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

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

Este true pe fiecare cont astăzi. Apelul este păstrat pentru ca o integrare să poată verifica înainte de a anunța pe cineva că modificarea rutării este activă, în loc să presupună acest lucru.

Apelurile mai vechi, bazate pe campanii #

Două endpoint-uri de dinainte de Agenți funcționează în continuare pentru conturile organizate în jurul campaniilor. Noile integrări ar trebui să utilizeze apelurile de setări implicite ale canalului de mai sus.

• PUT /channel-routing/{channel} cu { "campaignId": "cp5NbV8xQrT2wYzA" } — denumește o campanie, iar Agentul acelei campanii devine cel care răspunde pe canal. { "campaignId": null } eliberează canalul. O campanie destinată exclusiv apelurilor de ieșire este respinsă deoarece nu are niciun comportament de intrare de oferit.
• POST /channel-routing/clear cu { "channels": ["whatsapp", "instagram"] } — eliberează mai multe canale de la orice Agent care răspunde la acestea într-un singur apel, de obicei înainte de a le direcționa în altă parte. Răspunsul listează released_channels, cele care aveau efectiv un agent care răspundea.

Ambele anulează setarea în loc să oprească: pe un cont cu un singur Agent activ, un canal eliberat revine tot la acel Agent.

Erori API Puncte de Intrare #

Endpoint-urile Punctelor de Intrare returnează plicul standard de eroare:

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

Codurile partajate pe care orice endpoint le poate returna — 401, 403 (planul dvs. nu include acces API), 429 (limită de rată) și 500 — sunt listate cu îndrumări pentru reîncercare în Erori și Paginare.

Pașii următori #

• Puncte de Intrare — conceptul, tipurile de reguli și panoul Cine răspunde la conversațiile noi din aplicație.
• API Agenți AI — creează și configurează Agenții către care direcționează aceste reguli.
• API Canale — conectează canalele propriu-zise.
• Automatizare Comentariu-la-DM — ce fac regulile de comentarii odată ce sunt declanșate.