API pentru Agenți AI #

Un Agent AI este creierul din spatele botului tău: instrucțiunile, personalitatea, limba, cunoștințele și instrumentele sale. Construiești un Agent o singură dată și apoi direcționezi traficul către acesta. Acest ghid acoperă tot ce poți face cu un Agent prin intermediul API-ului — să-l creezi, să-l configurezi, să-i oferi cunoștințe și instrumente, să-i revizuiești ciornele și să direcționezi conversațiile către el.

• 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.

Dacă ești nou în conceptul de Agenți, citește mai întâi Agenți AI.

Cum este structurat un Agent #

Patru elemente sunt gestionate separat și este util să știi care este care înainte de a începe:

Un Agent nou nu răspunde nimănui până când nu direcționezi traficul către el. Crearea unui Agent nu îl plasează pe un canal. Acesta este pasul pe care majoritatea integrărilor îl omit — vezi Direcționarea conversațiilor către un Agent la sfârșitul acestei pagini.

Obiectul Agent #

Un document complet al unui Agent este mare — câteva sute de kiloocteți, în principal lista sa de întrebări frecvente, sursele sale de cunoștințe și orice conținut de pagină citit de pe site-ul tău. Din acest motiv, listarea returnează un rând rezumat scurt pentru fiecare Agent atunci când îl soliciți:

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Documentul complet adaugă tot restul: instructions, rules, personality, availability, follow_up_config, listele legate de întrebări frecvente și surse de cunoștințe, blocurile de text generate și orice stare de execuție (tag_generation, optimize_run).

Unele răspunsuri conțin și substrate_campaign_id. Este o înregistrare internă păstrată în conturile mai vechi; nu trebuie să acționezi niciodată asupra ei, iar în conturile mai noi este null sau lipsește.

Listarea Agenților #

GET /agents — fiecare Agent din cont, cele mai noi primele.

Acest endpoint nu este paginat. În mod implicit, fiecare Agent este returnat cu configurația sa completă, care este voluminoasă: un singur Agent poate ajunge la 580 KB, iar un cont cu 64 de Agenți la peste 3 MB. Transmite view=summary pentru a obține un rând scurt per Agent, apoi citește-l pe cel dorit folosind Obține un Agent.

Parametri de interogare

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Răspuns (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Creează un Agent #

POST /agents — doar name este cu adevărat necesar; trimite orice configurație pe care o cunoști deja împreună cu acesta. Un Agent nou este activ în mod implicit.

Câmpuri de solicitare (toate opționale, cu excepția name)

Construirea unui Agent de pe site-ul tău. Include scrape_urls, iar platforma citește acele pagini și scrie instrucțiunile pentru tine. Răspunsul îți indică dacă acea generare a început, astfel încât să știi dacă trebuie să interoghezi Agentul pentru progres.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Răspuns (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued este true atunci când platforma a început să scrie instrucțiunile din paginile pe care le-ați furnizat.

O 400 înseamnă că corpul cererii nu a fost un obiect JSON, un câmp a fost respins sau Agentul depășește dimensiunea de configurare permisă de planul dumneavoastră. O 403 înseamnă că contului nu îi este permis să utilizeze una dintre setările pe care le-ați trimis — de exemplu, un nivel AI pe care furnizorul contului său nu l-a acordat.

Obțineți un Agent #

GET /agents/{agentId}

Transmiteți fields cu o listă separată prin virgulă pentru a primi înapoi doar ceea ce aveți nevoie, de exemplu fields=name,active,goal. id este întotdeauna inclus, iar numele care nu există în Agent sunt ignorate în loc să fie respinse. Omiteți-l pentru a obține întregul document.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Un Agent care nu există în contul dumneavoastră returnează 404.

Actualizați un Agent #

PUT /agents/{agentId} — trimiteți doar câmpurile pe care doriți să le modificați; tot restul rămâne neatins.

Setările imbricate pot fi adresate frunză cu frunză folosind o cheie punctată, astfel încât "availability.monday" modifică doar ziua de luni și lasă restul săptămânii intact.

Note

• Pentru a schimba tipul de eveniment rezervabil în care Agentul face rezervări, trimiteți event_id (id-ul evenimentului sau null pentru a-l șterge). Trimiteți event_ids cu o matrice pentru a conecta mai multe simultan — primul devine cel principal, iar [] deconectează totul. event_id și event_ids se exclud reciproc, iar câmpul event în sine nu poate fi scris direct.
• enable_bookings trebuie să fie un boolean real, iar booking_provider trebuie să fie unul dintre default, zenchef, formitable.
• Câmpurile de proprietate și identitate sunt ignorate, la fel ca starea internă de execuție (progresul generării și optimizării).
• Rutarea nu este setată aici. Utilizați PUT /entry-points/channel-defaults pentru a face Agentul să răspundă pe un canal, POST /agents/{agentId}/entry-points pentru regulile de cuvinte cheie și comentarii și PATCH /agents/{agentId}/active pentru a-l întrerupe sau relua.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Răspuns (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Un corp gol returnează 400 cu "No fields to update".

Actualizarea setărilor botului #

PUT /agents/{agentId}/bot-config — modalitatea restrânsă de a modifica doar setările conversaționale.

Un Agent nu are o secțiune separată pentru boți: setările sale se află direct pe Agent, deci numele câmpurilor de aici sunt aceleași pe care le-ați trimite către PUT /agents/{agentId}. Acest endpoint există ca o modalitate sigură și concentrată de a modifica câteva dintre ele. Este necesar cel puțin un câmp.

Numele câmpurilor trebuie să fie nume simple aici — litere, cifre, caractere de subliniere și cratime. Căile punctate nu sunt acceptate pe acest endpoint (spre deosebire de PUT /agents/{agentId}), deci bot.goal este respins cu un 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

Textul lung contează în limita dimensiunii de configurare permisă de planul dvs., deci un set de instrucțiuni foarte mare poate fi refuzat cu un 400.

Setarea orelor de activitate #

PUT /agents/{agentId}/active-hours — orele în care Agentul răspunde automat. În afara acelor ferestre, acesta rămâne inactiv.

Trimiteți un obiect availability cu chei reprezentând ziua săptămânii (monday până la sunday). Fiecare zi acceptă o singură fereastră de timp sau o listă de ferestre, în format HH:MM de 24 de ore. Zilele pe care le omiteți își păstrează setările anterioare, iar orice cheie care nu reprezintă o zi a săptămânii este respinsă — astfel, o greșeală de scriere nu poate trece neobservată.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Răspuns (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

O cheie de zi a săptămânii incorectă returnează 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Întreruperea sau reluarea unui Agent #

PATCH /agents/{agentId}/active — pornește sau oprește Agentul. Un Agent întrerupt își păstrează toată configurația, dar încetează imediat să mai răspundă; reluarea activității are efect imediat.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Răspuns (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active trebuie să fie o valoare booleană reală — orice altceva returnează 400 cu "active (boolean) is required".

Duplicarea unui Agent #

POST /agents/{agentId}/duplicate — creează o copie cu configurația păstrată. Copia nu trimite nimic până când nu direcționați un canal sau un Punct de Intrare către aceasta.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Răspuns (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Un duplicat este luat în calculul limitei de Agenți a planului dumneavoastră exact ca și cum ați crea unul de la zero, deci este refuzat cu 403 atunci când contul a atins limita.

Ștergerea unui Agent #

DELETE /agents/{agentId}

Ștergerea este refuzată cât timp Agentul este încă atașat de ceva care nu ar mai funcționa fără el — o difuzare, un Punct de Intrare sau (în cazul conturilor mai vechi) o campanie. Răspunsul listează elementele care îl rețin, astfel încât să le puteți detașa mai întâi și să reîncercați.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Răspuns (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Blocat (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Ciorne: revizuiți modificările înainte ca acestea să devină active #

Editările efectuate în editor și orice rescriere produsă prin Optimizează cu AI sunt păstrate ca o ciornă nepublicată până când le publicați. Agentul activ continuă să răspundă cu configurația sa actuală până în acel moment.

Publicarea ciornei #

POST /agents/{agentId}/publish-draft — mută ciorna în configurația activă și șterge ciorna în același pas.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Răspuns (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys listează setările care au fost mutate din ciornă în Agentul activ, astfel încât să puteți vedea ce s-a schimbat.

Verificați dacă există o ciornă înainte de a apela această funcție. Publicarea unui Agent care nu are nicio ciornă nu este un apel suportat și în prezent returnează un 500 cu un mesaj generic, nu unul specific. Pentru a renunța la o ciornă, utilizați eliminarea de mai jos.

Renunță la ciornă #

POST /agents/{agentId}/discard-draft — elimină ciorna și lasă configurația activă exact așa cum este. Este sigur de apelat atunci când nu există nicio ciornă; nu se întâmplă nimic.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Optimizarea unui Agent cu AI #

POST /agents/{agentId}/optimize — rescrie configurația Agentului pe baza feedback-ului tău („continuă să ofere reduceri”, „răspunsurile sunt prea lungi”) și salvează rescrierea ca ciornă în loc să o facă activă.

Trimite fie user_feedback (o instrucțiune simplă), fie, atunci când reacționezi la un răspuns necorespunzător specific, thumbs_down_feedback împreună cu thumbs_down_message problematic. Cel puțin unul dintre cele două trebuie să conțină text.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Răspuns (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Procesul rulează în fundal, iar apelul returnează imediat un rezultat. Citește Agentul cu GET /agents/{agentId} și urmărește optimize_run.status; odată ce revine la Draft, rescrierea va fi disponibilă ca ciornă a Agentului. Revizuiește-o, apoi public-o sau renunță la ea.

Doar o singură execuție simultan per Agent — un al doilea apel în timp ce unul este în desfășurare va returna 409. Această acțiune consumă credite AI.

Reguli de etichetare #

O regulă de etichetare reprezintă o etichetă plus o descriere a momentului în care se aplică. În timpul unei conversații, Agentul citește acea descriere și etichetează contactul atunci când se potrivește, acesta fiind modul în care sunt declanșate automatizările bazate pe etichete.

Obiectul regulă

Adăugarea unei reguli de etichetare #

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Răspuns (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Înlocuirea unei reguli de etichetare #

PUT /agents/{agentId}/tags/{tagId} — regula este găsită după id-ul etichetei din cale și înlocuită complet, nu îmbinată, așa că trimiteți regula întreagă în loc de doar partea pe care o modificați. Eticheta către care indică este păstrată chiar dacă omiteți tag_id, deci o editare nu poate detașa regula de eticheta sa.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Eliminarea unei reguli de etichetare #

DELETE /agents/{agentId}/tags/{tagId} — Agentul încetează să mai aplice acea etichetă. Eticheta în sine și orice contacte care o poartă deja rămân intacte.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Ambele puncte finale returnează 404 atunci când Agentul nu există sau când nu are nicio regulă pentru acea etichetă.

Generarea unui set de etichete cu AI #

POST /agents/{agentId}/tags/generate — concepe un set întreg de reguli (numele etichetelor și formularea „aplică atunci când…” din spatele fiecăreia) prin citirea instrucțiunilor și a obiectivului propriu al Agentului.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Răspuns (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

Procesul rulează în fundal. Citiți Agentul și urmăriți tag_generation.status; regulile propriu-zise ajung în tags al Agentului. Doar o singură execuție simultan per Agent (409 în caz contrar), și utilizează credite AI.

Surse de cunoștințe #

Sursele de cunoștințe sunt paginile și documentele pe care platforma le-a citit pentru dumneavoastră. Atașarea uneia la un Agent îi permite acestuia să răspundă pe baza acelui conținut.

De unde provin id-urile surselor. Adăugați conținut cu punctele finale ale bazei de cunoștințe — POST /kb-sources/url pentru o pagină, POST /kb-sources/file pentru un document, POST /kb-sources/bulk-import pentru un întreg site. Acestea returnează un source_id pe care îl interogați cu GET /kb-sources/{sourceId} până când este gata. POST /kb-sources/url acceptă de asemenea autoLinkToAgentId, care atașează sursa la un Agent imediat ce importul se finalizează, astfel încât să puteți omite apelul de atașare de mai jos.

Atașarea surselor de cunoștințe #

POST /agents/{agentId}/kb-sources — trimiteți kb_source_ids cu o listă pentru a atașa un set întreg într-un singur apel (ceea ce doriți după indexarea unui site), sau kb_source_id pentru una singură. Trimiteți una sau alta. Atașarea a ceva deja atașat nu schimbă nimic.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Răspuns (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Detașarea surselor de cunoștințe #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} pentru unul, sau POST /agents/{agentId}/kb-sources/bulk-remove cu kb_source_ids pentru mai multe. Eliminarea în masă este un POST deoarece lista de ID-uri este transmisă în corp.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

Sursele în sine nu sunt șterse și rămân disponibile pentru ceilalți Agenți ai tăi. Detașarea a ceva ce nu este atașat nu schimbă nimic.

Întrebări frecvente (FAQ) #

Întrebările frecvente sunt gestionate prin propriile lor endpoint-uri și legate de un Agent de acolo: POST /faqs/{faqId}/link cu { "agent_id": "ag7HkQ2ZpLxR3mNb" }, și POST /faqs/{faqId}/unlink pentru a o elimina din nou. O întrebare frecventă poate fi partajată de orice număr de Agenți. Consultă API-ul pentru FAQ.

O întrebare frecventă este utilizată doar de Agenții de care este legată — crearea uneia nu este suficientă de la sine.

Instrumente #

Funcții personalizate #

POST /agents/{agentId}/custom-functions permite Agentului să apeleze una dintre funcțiile tale personalizate în timpul conversațiilor. Doar funcțiile care aparțin aceluiași cont pot fi atașate, iar atașarea uneia care este deja atașată nu schimbă nimic.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} o detașează. Funcția în sine nu este ștearsă și rămâne disponibilă pentru ceilalți Agenți ai tăi.

Gestionează funcțiile în sine pe /custom-functions — consultă Funcții personalizate pentru a vedea ce sunt acestea.

Servere MCP #

Un server MCP este un pachet gata de utilizare de instrumente pe care Agentul tău le poate descoperi și apela singur — consultă Conectarea serverelor MCP la botul tău. Serverele sunt înregistrate o singură dată în cont, apoi atașate oricăror Agenți care ar trebui să le utilizeze.

Serverele MCP necesită funcționalitatea de funcții personalizate în planul tău. Fără aceasta, endpoint-urile /mcp-servers la nivel de cont returnează 403. Atașarea unui server deja înregistrat la un Agent nu este restricționată.

Înregistrarea unui server #

POST /mcp-servers

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Răspuns (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

La salvare, platforma se conectează la server și stochează în cache lista de instrumente pe care acesta le oferă. Un server care nu poate fi accesat este totuși salvat, cu motivul în last_error și o listă de instrumente goală — astfel încât să puteți înregistra mai întâi și să remediați conectivitatea ulterior.

Un auth_type de tip oauth2 salvează înregistrarea cu oauth_connected: false și fără instrumente: nu există încă niciun token. Autorizarea unui server OAuth necesită o autentificare prin browser și se face din tabloul de bord, nu prin API.

Listarea, actualizarea și ștergerea serverelor #

• GET /mcp-servers — fiecare server înregistrat, cele mai noi primele, sub servers.
• PUT /mcp-servers/{serverId} — trimiteți doar ceea ce doriți să modificați. Modificarea URL-ului sau a câmpurilor de autentificare retestează conexiunea și reîmprospătează lista de instrumente stocată în cache.
• DELETE /mcp-servers/{serverId} — elimină înregistrarea și o deconectează de la fiecare Agent și campanie care o avea activată.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

Secretele nu se întorc niciodată. Răspunsurile conțin auth_header_value_set (un flag true/false care indică faptul că o valoare este stocată) în loc de acreditare, iar tokenurile OAuth și secretele clientului rămân pe partea de server. Tot restul este returnat: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Testarea unei conexiuni #

POST /mcp-servers/test-connection — se conectează la un server și listează instrumentele acestuia. Două moduri de a-l apela:

• cu server_id — testează configurația salvată și reîmprospătează lista de instrumente stocată în cache;
• cu un url inline (plus auth_header_name / auth_header_value) — un test înainte de salvare care nu stochează nimic.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Răspuns (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

O eroare de conexiune nu este o eroare HTTP — primiți un 200 cu success: false și un error care descrie ce a mers prost, astfel încât să îl puteți afișa lângă câmpul pe care îl editează operatorul.

Atașarea unui server la un Agent #

Înregistrarea unui server nu oferă niciunui Agent acces la acesta. Atașați-l:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Răspuns (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} îl detașează din nou. Serverul în sine nu este șters și rămâne disponibil pentru ceilalți Agenți ai dumneavoastră. Atașarea sau detașarea a ceva ce se află deja în acea stare nu schimbă nimic.

Biblioteca media #

Biblioteca media conține fișierele pe care un Agent le poate trimite în timpul unei conversații — un meniu, o listă de prețuri, o fotografie de produs. Un Agent poate deține cel mult 50 de elemente.

Listare conținut media #

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Răspuns (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Elementele stocate pe Agent apar primele, urmate de orice elemente mai vechi încă stocate în campania din care a fost creat Agentul; media_home (agent sau campaign) indică care este care. În cadrul fiecărui grup, cele mai noi apar primele.

media_url expiră după 7 zile. Acesta este linkul de descărcare creat în momentul încărcării fișierului — tratați un link vechi ca fiind expirat, nu defect, și recitiți lista pentru a obține un link nou.

Încărcare conținut media #

POST /agents/{agentId}/media-library — fișierul este încărcat inline ca base64, până la 10 MB. Apelul returnează un răspuns odată ce fișierul este stocat, așa că acordați puțin mai mult timp decât pentru o cerere obișnuită. Rețineți că acest corp folosește nume de câmpuri în format camelCase.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Două lucruri se întâmplă automat: un GIF animat este convertit în video pentru a fi redat pe orice canal, iar platforma scrie un scurt rezumat al conținutului fișierului, astfel încât Agentul să știe când este potrivit să îl folosească.

O eroare 400 acoperă câmpurile lipsă, un tip de fișier neacceptat, un fișier gol sau prea mare și atingerea limitei de 50 de elemente. O eroare 403 înseamnă că biblioteca media este dezactivată pentru cont.

Actualizarea unui element media #

PATCH /agents/{agentId}/media-library/{itemId} — doar metadate. Fișierul în sine nu poate fi înlocuit; încărcați un element nou și ștergeți-l pe cel vechi. Acest corp folosește snake_case: title, description, send_message, max_sends_per_conversation (un număr întreg nenegativ sau null pentru a șterge limita).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Răspuns (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Ștergerea unui element media #

DELETE /agents/{agentId}/media-library/{itemId} — elimină elementul și fișierul stocat aferent. Ștergerea unui element care a fost deja eliminat reușește și raportează deleted: false, deci apelul poate fi reîncercat în siguranță.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Generarea mesajelor de follow-up #

POST /agents/{agentId}/template-generation — scrie mesajele de follow-up ale Agentului pentru dumneavoastră (atenționările pe care le trimite când o conversație devine inactivă), pe baza scopului Agentului.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Există două moduri în care acesta revine, iar câmpul target vă indică care dintre ele:

• target: "agent" cu un 200 — mesajele au fost scrise în timpul apelului, iar rezultatul se află în data. Citiți-le din follow_up_config Agentului. Acesta este cazul obișnuit.
• target: "campaign" cu un 202 — lucrarea a fost pusă la coadă în campania numită în campaign_id. Urmăriți template_generation_status acelei campanii până când se finalizează.

cold_only necesită o campanie de ieșire și este refuzat cu 409 (reason: "cold_only_requires_campaign") pe un Agent care nu are niciuna. Un 403 înseamnă că urmăririle automate nu sunt activate pentru cont. Aceasta utilizează credite AI, iar un 400 cu "Insufficient credits." înseamnă că contul nu mai are credite.

Direcționarea conversațiilor către un Agent #

Un Agent răspunde doar la conversațiile trimise de un Punct de intrare. Până când un canal are unul, un prim mesaj de la cineva cu care nu ați mai vorbit este stocat, dar nimic nu îl preia și niciun asistent nu răspunde.

Listați punctele de intrare ale unui Agent #

GET /agents/{agentId}/entry-points — regulile de direcționare care trimit conversații către acest Agent, cele mai noi primele. Atât regulile curente, cât și cele retrase sunt returnate; o regulă retrasă are enabled: false.

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

Pentru setările implicite ale canalului întregului cont, inclusiv un canal setat în mod deliberat să nu aibă pe nimeni, citiți GET /entry-points/channel-defaults în schimb.

Creați un punct de intrare #

POST /agents/{agentId}/entry-points — Agentul din cale câștigă întotdeauna, deci o regulă nu poate fi creată niciodată pentru un alt Agent decât cel din URL.

channels este obligatoriu și specifică ce canale acoperă regula — de exemplu whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget sau custom_channel. Regulile noi sunt activate, cu excepția cazului în care specificați altfel.

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

Răspuns (201)

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

Ce regulă câștigă atunci când mai multe ar putea: o conversație în curs sau o atribuire manuală păstrează Agentul pe care îl are deja; în caz contrar, regulile bazate pe cuvinte cheie prevalează asupra regulilor de comentarii, care prevalează asupra regulilor de urmăritori, iar o setare implicită a canalului este ultima soluție. Dacă aceste reguli decid ceva în acest moment pe un cont este raportat de GET /entry-points/routing-status.

Aceasta este versiunea scurtă. Ghidul Entry Points API acoperă întreaga ierarhie, regulile pentru comentarii și urmăritori, un singur Agent per număr de WhatsApp, precum și modificarea sau ștergerea unei reguli. Consultați Entry Points pentru concept și Channels API pentru conectarea canalului propriu-zis.

Erori API Agenți AI #

Endpoint-urile pentru agenți returnează plicul standard de eroare:

{
  "success": false,
  "error": "Agent 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.

O notă despre explorator. Endpoint-urile /agents se află în specificația OpenAPI publicată, astfel încât puteți naviga prin câmpurile lor exacte și puteți rula cereri live în Referința API. Endpoint-urile /mcp-servers la nivel de cont sunt, de asemenea, în specificație, deci le puteți explora și acolo.

Legate #

• Agenți AI — ce este un Agent, explicat pe înțelesul tuturor.
• Puncte de intrare — cum sunt direcționate conversațiile către un Agent.
• API Întrebări frecvente — construiți și conectați cunoștințele din care răspunde Agentul dvs.
• API Canale — conectați canalele pe care răspunde un Agent.
• Conectați servere MCP la botul dvs. · Funcții personalizate
• Referință API — exploratorul interactiv complet de endpoint-uri.