Construiește o integrare cap-la-cap

Acest ghid parcurge tot ce ai nevoie pentru a rula Your AI Connector din propriul tău cod, fără a deschide vreodată tabloul de bord. Până la final, vei fi construit o integrare minimală care:

Autentificare cu o cheie API
Crearea unui Agent AI și configurarea comportamentului asistentului său
Conectarea unui canal de mesagerie (folosim WhatsApp Web ca exemplu practic) și direcționarea acestuia către Agent
Importarea contactelor
Trimiterea și citirea mesajelor
Citirea analizei datelor
Abonarea la webhook-uri pentru evenimente în timp real

Fiecare pas oferă link-uri către ghidul complet de resurse, astfel încât să poți aprofunda detaliile atunci când ai nevoie. Această pagină este harta; ghidurile de resurse sunt teritoriul.

Înainte de a începe. Accesul API este o funcționalitate plătită. Dacă planul tău nu o include, fiecare cerere va returna 403. Consultă Acces API pentru a confirma că este activat și Autentificare pentru toate modalitățile de a transmite cheia ta.

Toate căile de mai jos sunt relative la URL-ul de bază:

https://api.youraiconnector.com/v1

Pasul 1 — Obține o cheie API și fă prima ta cerere

Cheia ta API se află în aplicație la Setări → Integrări → Cheie API — o secțiune proprie în cadrul Integrărilor, separată de Webhook-uri, care apare doar după ce accesul API este activat în planul tău. Generează una, copiază-o și stochează-o într-un loc sigur (un magazin de secrete pe partea de server sau o variabilă de mediu — niciodată în codul browserului). Instrucțiunile complete se află în Acces API.

Odată ce ai o cheie, confirmă că funcționează apelând endpoint-ul de stare (health). Există mai multe moduri de a trimite cheia; cel mai simplu este parametrul de interogare ?apiKey=, dar pentru cod real preferă antetul X-API-Key, astfel încât cheia să nu ajungă niciodată în jurnalele serverului sau în istoricul browserului.

cURL

curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"

JavaScript

const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }

Python

import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }

Fiecare răspuns reușit este împachetat în același plic — un câmp success: true plus datele rezultatului. Erorile returnează success: false cu un mesaj error și un error_code. Consultă Erori și Paginare pentru lista completă și pentru modul în care endpoint-urile de listare paginează cu ?limit și ?cursor.

Limită de rată. Cererile autentificate sunt limitate la 300 pe minut (cu un plafon mai generos de 1.200/minut per cont). Depășirea acestei limite returnează 429; așteptați și reîncercați.

Pasul 2 — Crearea unui Agent AI

Un Agent AI este unitatea care conține comportamentul asistentului tău: instrucțiunile sale, scopul său, orele de activitate și modul în care comunică cu contactele. Acesta este cel care răspunde la o conversație, deci este primul lucru natural de creat.

Creează unul cu POST /agents. name este singurul câmp care merită trimis inițial; orice altceva poate fi setat cu apelul bot-config de mai jos.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'

JavaScript

const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]

O creare reușită returnează 201 cu noul ID:

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

Salvează agent_id — îl vei referenția atunci când direcționezi canalele.

Configurarea asistentului

PUT /agents/{agentId}/bot-config setează comportamentul asistentului. Acesta îmbină câmpurile pe care le trimiți cu configurația existentă, astfel încât tot ceea ce omiți este păstrat:

curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'

Setează orele de activitate cu PUT /agents/{agentId}/active-hours, astfel încât asistentul să răspundă doar în timpul orelor de program; în afara acestor ferestre, acesta nu răspunde automat.

Baza de cunoștințe. Pentru ca asistentul să răspundă pe baza propriului tău conținut, atașează întrebări frecvente (FAQ). Consultă ghidul FAQ.

Moștenire: campanii clasice. Conturile care au încă o pagină de Campanii creează același comportament al asistentului pe o campanie în schimb (POST /campaigns cu un obiect type și un obiect bot, apoi PUT /campaigns/{campaignId}/bot-config). Lista completă a câmpurilor de campanie și controalele ciclului de viață se află în ghidul Campanii. Dacă construiești ceva nou, creează un Agent.

Pasul 3 — Conectarea unui canal

Un Agent are nevoie de o modalitate de a trimite și primi mesaje. Șapte fluxuri de conectare pot fi gestionate prin API: WhatsApp Business, WhatsApp Web, Instagram și Messenger împreună (un flux Meta partajat), conturi personale de Instagram, Telegram, LINE și Viber. Celelalte canale — SMS, e-mail, widget-ul de chat și canale personalizate printre altele — sunt configurate în tabloul de bord, nu prin REST, iar odată ce sunt conectate, punctele finale de mesagerie, contact și rutare funcționează exact la fel pe acestea. GET /channels este sursa live de adevăr pentru ceea ce are conectat un anumit cont:

curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"

Setul complet de fluxuri de conectare/deconectare pentru fiecare canal este documentat în Ghidul canalelor. Mai jos vom parcurge WhatsApp Web cap-la-cap, deoarece prezintă cel mai interesant model: un flux de asociere prin cod QR pe care wrapper-ul tău trebuie să îl randeze și să îl interogheze.

Exemplu practic: asocierea WhatsApp Web prin cod QR

Asocierea WhatsApp Web este un dans în trei pași — pornire, preluarea codului QR, interogare până la conectare.

1. Pornește sesiunea de asociere. Introdu numărul pe care dorești să îl conectezi în format E.164.

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)

2. Preluarea codului QR și afișarea acestuia utilizatorului. Interoghează acest endpoint la fiecare 10–15 secunde. Răspunsul include payload-ul brut qr_code (randează-l tu ca imagine QR) și un qr_data_url gata de afișat.

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}

În interfața wrapper-ului tău, plasează qr_data_url direct într-un <img src="..."> și cere utilizatorului să îl scaneze din WhatsApp → Dispozitive conectate pe telefonul său. Dacă codul QR expiră (un răspuns 410), reia de la pasul 1 pentru a obține unul nou.

3. Interogarea stării până la conectare. După ce utilizatorul scanează, continuă să interoghezi endpoint-ul de stare până când raportează connected (serviciul poate raporta, de asemenea, open). Tratează disconnected și not_initialized ca erori terminale.

import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)

async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Atenție. Fiecare număr WhatsApp Web conectat implică o taxă de întreținere lunară recurentă până când îl deconectezi (DELETE /channels/whatsapp-web/connections/{phoneNumber}).

Direcționarea canalului către Agentul tău

Conectarea unui canal îl face funcțional; direcționarea acestuia îi spune platformei ce Agent AI ar trebui să răspundă la conversațiile noi primite pe acesta. Setează Punctul de Intrare implicit al canalului, numind Agentul pe care l-ai creat la Pasul 2:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'

Repetă apelul o dată per canal — un implicit de canal per canal. Pentru a lăsa un canal fără niciun Agent care să răspundă, apelează DELETE /entry-points/channel-defaults?channel=whatsapp_web; pentru a verifica dacă scara Punctelor de Intrare este activă pentru cont, apelează GET /entry-points/routing-status. Harta mai veche POST /channels/campaign este păstrată doar pentru rollback și nu mai este consultată pentru rutarea primită. Consultă ghidul Canale pentru celelalte tipuri de canale și pentru fluxul OAuth WhatsApp Business.

Pasul 4 — Importă-ți contactele

Odată ce un canal este activ, încarcă persoanele pe care dorești să le contactezi. Endpoint-ul de import acceptă până la 500 de înregistrări per apel. Fiecare înregistrare are nevoie de un phone_number în format internațional; orice altceva este opțional. Înregistrările cu numere invalide, canale neacceptate sau numere care există deja sunt omise — și fiecare omisiune este raportată cu indexul și motivul său, astfel încât să poți reîncerca doar eșecurile.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);

Python

res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")

Răspunsul îți spune exact ce s-a întâmplat:

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

Pentru crearea individuală, listare/căutare, liste, etichete și câmpuri personalizate, consultă Ghidul contactelor.

Pasul 5 — Trimite și citește mesaje

Trimite un mesaj

Cea mai simplă trimitere este agnostică față de canal: oferă identitatea contactului și corpul mesajului, iar platforma îl livrează pe orice canal se află contactul. Poți viza prin contact_id sau prin channel plus câmpul de identitate corespunzător (phone_number pentru WhatsApp/WhatsApp Web/SMS, instagram_id pentru Instagram și așa mai departe).

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]

Livrarea este asincronă — un 201 înseamnă că mesajul a fost acceptat și pus în coadă, nu încă livrat. (Contactele care au activat modul „nu deranja” sau modul privat sunt respinse cu un 422.)

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}

Citește o conversație

Pentru a citi mesajele primite, listează-le în funcție de contact, cele mai noi primele, cu paginare bazată pe cursor. Transmite next_cursor din răspunsul anterior ca cursor pentru următorul, pentru a parcurge istoricul.

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page

De asemenea, poți filtra după tipul de conținut (?filter=text|media|tool_use) sau direcție (?direction=inbound|outbound). Ghidul mesajelor acoperă atașamentele media, marcarea mesajelor ca citite și vizualizările mesajelor per sesiune.

Nu interoga pentru răspunsuri. Listarea mesajelor pe un cronometru funcționează, dar consumă cereri și adaugă latență. Pentru mesajele primite, folosește webhooks — acesta este Pasul 7.

Pasul 6 — Citirea analizei

Odată ce mesajele încep să circule, rezumatul analitic vă oferă numărători agregate pe un interval de date: trimise, livrate, citite, cu răspuns, rezervate, contacte create și credite cheltuite/reîncărcate. Obțineți atât totaluri pe interval, cât și o serie zilnică completată cu zero — perfectă pentru un grafic de tip tablou de bord. Opțional, puteți limita rezultatele la o singură campanie cu campaign_id (exemplele de mai jos folosesc un ID de campanie substituent, abc123campaign); omiteți parametrul pentru totaluri la nivel de cont.

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();

res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]

Intervalul este setat implicit la ultimele 30 de zile și este limitat la 366. Pentru înregistrări de utilizare credit cu credit și defalcări ale costurilor AI, consultați Ghidul de analiză.

Pasul 7 — Abonarea la webhook-uri pentru evenimente în timp real

Interogarea (polling) este utilă pentru un script rapid, dar o integrare reală ar trebui să fie bazată pe push. Webhook-urile permit platformei să apeleze serverul dumneavoastră în momentul în care se întâmplă ceva — un contact nou, un răspuns, o programare efectuată, o conversație încheiată.

Mai întâi, descoperiți numele exacte ale evenimentelor la care vă puteți abona:

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}

Apoi creați un abonament care indică un URL HTTPS pe serverul dumneavoastră. Folosiți șirurile de caractere exacte ale evenimentelor din apelul de mai sus.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'

JavaScript

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

URL-ul trebuie să utilizeze HTTPS și să fie accesibil public. De aici înainte, serverul dumneavoastră primește un POST pentru fiecare eveniment la care sunteți abonat. Puteți trimite o livrare de test, puteți verifica starea unui abonament și puteți reactiva un abonament care a fost dezactivat automat după eșecuri repetate — consultați Ghidul pentru Webhook-uri și pagina de Webhook-uri de la nivelul integrărilor pentru formatele de payload și verificare.

Punerea tuturor elementelor cap la cap

Iată întregul flux dintr-o privire:

Pas	Obiectiv	Apel cheie
1	Autentificare	`GET /health`
2	Creare + configurare asistent	`POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours`
3	Conectare canal și rutare	`POST /channels/whatsapp-web/connections` → scanare QR + stare → `PUT /entry-points/channel-defaults`
4	Încărcare contacte	`POST /contacts/import`
5	Trimitere și citire	`POST /contacts/send`, `GET /contacts/{id}/messages`
6	Măsurare	`GET /analytics/summary`
7	Reacție în timp real	`POST /webhooks`

Un wrapper minimal înseamnă doar aceste șapte apeluri integrate în propria interfață. De acolo, adăugați ghidurile pe resursă pe măsură ce aveți nevoie de mai multe:

Campanii · Contacte · Întrebări frecvente · Mesaje · Programări
Canale · Șabloane · Analiză · Webhook-uri · Chei API
Sunteți nou aici? Noțiuni de bază · Autentificare · Erori și paginare

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

Construiește o integrare cap-la-cap #

Pasul 1 — Obține o cheie API și fă prima ta cerere #

Pasul 2 — Crearea unui Agent AI #

Configurarea asistentului #

Pasul 3 — Conectarea unui canal #

Exemplu practic: asocierea WhatsApp Web prin cod QR #

Direcționarea canalului către Agentul tău #

Pasul 4 — Importă-ți contactele #

Pasul 5 — Trimite și citește mesaje #

Trimite un mesaj #

Citește o conversație #

Pasul 6 — Citirea analizei #

Pasul 7 — Abonarea la webhook-uri pentru evenimente în timp real #

Punerea tuturor elementelor cap la cap #

Construiește o integrare cap-la-cap

Pasul 1 — Obține o cheie API și fă prima ta cerere

Pasul 2 — Crearea unui Agent AI

Configurarea asistentului

Pasul 3 — Conectarea unui canal

Exemplu practic: asocierea WhatsApp Web prin cod QR

Direcționarea canalului către Agentul tău

Pasul 4 — Importă-ți contactele

Pasul 5 — Trimite și citește mesaje

Trimite un mesaj

Citește o conversație

Pasul 6 — Citirea analizei

Pasul 7 — Abonarea la webhook-uri pentru evenimente în timp real

Punerea tuturor elementelor cap la cap