# 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: 1. Autentificare cu o cheie API 2. Crearea unui Agent AI și configurarea comportamentului asistentului său 3. Conectarea unui canal de mesagerie (folosim WhatsApp Web ca exemplu practic) și direcționarea acestuia către Agent 4. Importarea contactelor 5. Trimiterea și citirea mesajelor 6. Citirea analizei datelor 7. 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](../integrations/api-access.md) pentru a confirma că este activat și [Autentificare](authentication.md) 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](../integrations/api-access.md). 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** ```bash curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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](errors-and-pagination.md) 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** ```bash 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** ```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** ```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: ```json { "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: ```bash 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](faqs.md). > **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](campaigns.md). 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: ```bash 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](channels.md). 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. ```bash 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" }' ``` ```javascript await fetch(`${BASE}/channels/whatsapp-web/connections`, { method: "POST", headers, body: JSON.stringify({ phone_number: "+15551230000" }), }); ``` ```python 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. ```bash curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY" ``` ```json { "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 `` ș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. ```python 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) ``` ```javascript 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: ```bash 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](channels.md) 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** ```bash 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** ```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** ```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: ```json { "success": true, "imported": 2, "contact_ids": ["contactId1", "contactId2"], "skipped": [] } ``` Pentru crearea individuală, listare/căutare, liste, etichete și câmpuri personalizate, consultă [Ghidul contactelor](contacts.md). --- ## 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** ```bash 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** ```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** ```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`.) ```json { "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. ```bash curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY" ``` ```python 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](messages.md) 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. ```bash curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY" ``` ```javascript 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(); ``` ```python 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ă](analytics.md). --- ## 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: ```bash curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY" ``` ```json { "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** ```bash 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** ```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** ```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"] ``` ```json { "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](webhooks.md) și pagina de [Webhook-uri](../integrations/webhooks.md) 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](campaigns.md) · [Contacte](contacts.md) · [Întrebări frecvente](faqs.md) · [Mesaje](messages.md) · [Programări](appointments.md) - [Canale](channels.md) · [Șabloane](templates.md) · [Analiză](analytics.md) · [Webhook-uri](webhooks.md) · [Chei API](api-keys.md) - Sunteți nou aici? [Noțiuni de bază](getting-started.md) · [Autentificare](authentication.md) · [Erori și paginare](errors-and-pagination.md) Stuck on something this guide does not cover? Email [hi@youraiconnector.com](mailto:hi@youraiconnector.com).