Construiește pe aichat.md — agenți AI conversaționali, pe orice canal.

Pornire rapidă

Agentul pe site, în trei pași:

1. Creează un agent în panoul aichat.md și copiază-i widgetId-ul (un UUID, din Agent → Canale → Chat Widget).
2. Lipește scriptul de embed înainte de </body>.
3. Sau, pentru UI propriu, apelează POST /widget/chat.

<script src="https://aichat.md/api/v1/widget/bridge/chatbot-script.js?chatflow_id=WIDGET_ID" defer></script>

URL de bază & versiuni

Autentificare

Există două niveluri de acces:

Obținerea unui token

Flux: register → verify-email → login. Endpoint-urile care emit token returnează { accessToken, refreshToken }.

curl -X POST https://aichat.md/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "tu@firma.md", "pass": "••••••••" }'

# → 200 { "accessToken": "eyJ…", "refreshToken": "eyJ…" }
# → 202 { "twofa_required": true, "pendingToken": "…" }   dacă 2FA e activ
# → 228 { "email": "…" }                                  email neconfirmat (un cod NOU e retrimis automat)

Endpoint-uri de autentificare

2FA (TOTP) — management (toate 🔒 Bearer)

POST /auth/2fa/setup (→ { secret, qrCode }) · /2fa/verify-enable (→ { backupCodes }) · /2fa/disable · /2fa/status · /2fa/backup-codes/regenerate · GET /2fa/trusted-devices · DELETE /2fa/trusted-devices/:id (id-ul device-ului din listă).

Apoi trimite token-ul pe orice rută autentificată: Authorization: Bearer <accessToken>. Eroare de auth: 401 { message: "🚫 Un-Authorized 🚫" }.

Convenții & paginare

Forma răspunsului

Convenția nu e uniformă pe toată platforma — verifică per zonă:

Paginare

List-endpoint-urile mari acceptă page + limit (ex. /conversations, /leads) sau cursor + limit (ex. /conversations/:id/messages). Unde nu e specificat un plafon, limit are un maxim de siguranță (ex. usage/transactions ≤ 500).

Fusuri, criptare, id-uri

Datele-oră sunt în fusul Chișinău (Europe/Chisinau) unde nu se specifică altfel. Agenții și widget-ul folosesc UUID; conversațiile/thread-urile folosesc id-uri numerice.

Erori & rate limits

Coduri de răspuns

Rate limits — widget

Instalare widget

Trei metode de embed. Alege una:

1. Script bridge — recomandat (web-component)

<script src="https://aichat.md/api/v1/widget/bridge/chatbot-script.js?chatflow_id=WIDGET_ID" defer></script>

2. Loader — sigur pentru Google Tag Manager (web-component)

<script async src="https://aichat.md/api/v1/widget/loader.js?widget-id=WIDGET_ID"></script>

3. Embed static v2 — iframe

<script src="https://aichat.md/api/v1/widget/v2/embed.js?id=WIDGET_ID"
  data-position="right" data-color="#0d9c93" data-lang="ro"></script>

Aspectul (culoare, nume, avatar, mesaj) se setează din panou sau prin API-ul de config widget. Snippet-ul se poate genera și programatic cu POST /widget/embed-code { chatbot_id } → { success, html }.

Conversație — chat

curl -X POST https://aichat.md/api/v1/widget/chat \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "1d00a200-8ad9-4bb3-a165-7cfa45960e1d",
    "sessionId": "sess-42",
    "messages": [{ "role": "user", "content": "Ce servicii aveți?" }]
  }'

const sessionId = localStorage.getItem("aichat_sid")
  ?? (localStorage.setItem("aichat_sid", crypto.randomUUID()), localStorage.getItem("aichat_sid"));
const res = await fetch("https://aichat.md/api/v1/widget/chat", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ widgetId: "WIDGET_ID", sessionId, messages: [{ role: "user", content: text }] })
});
const data = await res.json();
console.log(data.message, data.products);

Răspuns (200)

{
  "success": true,
  "message": "Avem manichiură, pedichiură și tratamente podologice…",
  "products": [{ "id","title","description","price","currency"?,"image_url"?,"product_url"?,"sku"?,"availability"? }],
  "sources": [{ "index","title","snippet","url"? }],
  "citations": [ … ], "media": [{ "type","url","title" }],
  "actions": [{ "label","url","type" }],
  "quick_replies": [{ "label","value" }],
  "metadata": { "schema": "aichat.rich.v1", "quickReplies", "products", "sources", … } // duplicat camelCase
}

Streaming — token cu token (SSE)

Răspunsul e Server-Sent Events: fiecare eveniment e o linie data: <JSON>, cu tipul în câmpul type. Body: { widgetId, messages | message, sessionId?, images? }.

const res = await fetch("https://aichat.md/api/v1/widget/v2/chat/stream", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ widgetId: "WIDGET_ID", sessionId, message: text })
});
const reader = res.body.getReader(), dec = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += dec.decode(value, { stream: true });
  const parts = buf.split("\n\n");
  buf = parts.pop();                     // păstrează fragmentul incomplet
  for (const block of parts) {
    if (!block.startsWith("data:")) continue;
    const ev = JSON.parse(block.slice(5));
    if (ev.type === "token") ui.append(ev.content);
  }
}

Config widget — citire publică

Configurația publică a agentului (nume, mesaj, culoare, avatar, sugestii, produse). Endpoint-ul canonic e POST; varianta GET e un alias cu cache ETag/304. Pentru setarea configului (owner, cu token) vezi Config widget al agentului.

POST cere body { widget_id }; GET ia widget_id din cale și adaugă ETag + Cache-Control: max-age=60 (trimite If-None-Match pentru 304). Răspuns: { success, config: { name, primary_color, welcome_message, placeholder, assistant_name, greeting_message, position, starter_prompts[], agent:{name,avatar,tone}, products[], cart_enabled } }.

Istoric conversație

Ultimele 40 de mesaje ale sesiunii: { success, messages: [{ role, content, time }] }. Ambii parametri sunt obligatorii.

Comandă

Succes: { success: true, order_id }. Rate-limit 5/min/IP; deduplicare 24h pe telefon+widget (409 duplicate_lead_24h).

{
  "widget_config_id": "WIDGET_ID",
  "customer_name": "Ana Pop",
  "customer_phone": "37360123456",
  "customer_address": "str. Ismail 33, Chișinău",
  "cart_items": [
    { "id": "sku-12", "title": "Set California", "price": 180, "qty": 2 }
  ],
  "total_amount": 360,
  "customer_notes": "fără wasabi"
}

Integrare headless — agentul în UI-ul tău

Ai deja un chat pe site și vrei doar „creierul"? Poți integra agentul complet în interfața ta — fără bundle-ul nostru, fără SDK, fără cookie. Toată suprafața e un API public JSON/SSE, autentificat doar prin widgetId. Practic apelezi aceleași endpoint-uri de mai sus din codul tău.

curl -sS https://aichat.md/api/v1/widget/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "widgetId": "WIDGET_ID",
    "sessionId": "user-42-conv-7",
    "messages": [{ "role": "user", "content": "Salut, aveți livrare la Chișinău?" }]
  }'
# → { success, message, products, quick_replies, sources, actions, ... }

Piesele de care ai nevoie, toate documentate mai sus:

Autentificare & CORS

• Auth = doar widgetId. Fără cheie API, fără Bearer, fără cookie, fără HMAC de identitate.
• CORS pe /widget reflectă orice origine (credentials: false) — domeniul tău e acceptat implicit.
• Lista de origini permise a agentului se verifică la nivel de aplicație și se ocolește când nu există header Origin (apel din server). Deci dacă chemi din backend-ul tău, nu ești blocat niciodată. Dacă apelezi direct din browser, cere owner-ului agentului să adauge domeniul tău în originile permise.

Memorie / sesiune

Tu deții sessionId-ul (string stabil per user-conversație). Serverul persistă fiecare tură, dar nu re-injectează automat istoricul în prompt — pentru multi-turn, trimite tu istoricul în messages[] (max 20 mesaje, 4000 caractere/mesaj, 3 imagini).

Recomandat vs legacy

Agenți

Creează și gestionează agenți programatic. Toate rutele cer Bearer. Un agent are: nume, instrucțiuni (system prompt), model, provider AI, ton, canale și config.

curl -X POST https://aichat.md/api/v1/agents \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "Asistent salon", "instructions": "Ești asistentul online…", "model": "gpt-4o-mini", "tone": "friendly" }'

Config widget al agentului

Merge atomic în channels.widget. Câmpuri: theme_color, persona_name, persona_avatar_url, welcome_message, subtitle, placeholder, starter_prompts (max 4, ≤80 char), position, enabled, pet_name, show_online_dot, theme_mode, quick_replies_enabled, auto_focus_input, allowed_origins, plus hide_branding și footer_text (doar PRO+). Alternativă unificată: PUT /agents/:id/widget-config (acceptă și chei camelCase legacy).

Modele & provideri

Un agent are un model (nume text, ex. gpt-4o-mini) și un ai_provider (implicit azure). Valorile disponibile depind de planul contului — ia lista reală cu:

Răspuns: { models, userPlanId }. Folosește un model din această listă la POST /agents / PUT /agents/:id. (Există și aliasul istoric /asisstants/models, cu doi „s".)

Tool-uri (funcții)

Dă agentului capacități — să cheme un API, să ruleze cod sau o funcție încorporată. Legate de un agent. Toate rutele cer Bearer.

Cele trei tipuri

Câmpul parameters (argumentele văzute de model) e o listă:

curl -X POST https://aichat.md/api/v1/agents/AGENT_ID/tools \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "verifica_stoc",
    "description": "Verifică stocul unui produs după cod",
    "tool_type": "webhook",
    "webhook_url": "https://api.magazin.md/stoc?sku={{sku}}",
    "webhook_method": "GET",
    "parameters": [{ "name": "sku", "type": "string", "required": true }]
  }'

Conversații

Inbox-ul unificat pe toate canalele. Toate rutele cer Bearer. Răspunsuri { success, data }.

Preluare umană (handoff)

Trece o conversație de la bot la un operator uman și înapoi. Bearer, răspunsuri { success, data }.

Note · Etichete · Canned · Export · Contacte · Pause-rules

Unelte de inbox. Toate Bearer.

Template-uri Meta

Trimite template-uri structurate pe Messenger (proxy către Facebook Graph). Bearer; toate cer recipient_id și întorc { success, message_id }.

Librărie de template-uri (CRUD) — /templates/library

GET /library · GET /library/most-used · GET /library/variables · POST /library/validate · GET /library/:id (+/preview) · POST /library ({ name, templateType, content }, tipuri: text/quick_replies/buttons/generic/carousel/media) · PUT /library/:id · POST /library/:id/duplicate · DELETE /library/:id.

Facebook Messenger

Conectarea unei pagini se face prin OAuth din panou; API-ul leagă o pagină de un agent. Toate cer Bearer.

Instagram

Toate cer Bearer.

Telegram

Bot partajat (@aichat_connect_bot) — clientul nu introduce un token de bot. Conectare: cod de 6 cifre → în bot → Telegram Business Connection (Premium) → business_connection_id. Toate cer Bearer.

WhatsApp (Cloud API)

Conectare din panou

1. Creează și activează agentul.
2. Deschide canalul WhatsApp și începe Embedded Signup, dacă accesul pilot este disponibil.
3. Autorizează propriul business, WABA și număr. Nu introduce tokenuri în panou.
4. Finalizează verificarea și înregistrarea cerută de Meta; verifică abonarea webhookului și agentul asociat.
5. Trimite un mesaj de pe un telefon dedicat autorizat și confirmă răspunsul pe telefon, nu numai în inbox.

Ai nevoie de drepturile necesare asupra activelor selectate. Un număr poate aparține unui singur cont aichat.md. Numerele Meta de test pot trimite numai către destinatarii autorizați în lista lor.

API autentificat

Prefix: /api/v1; sesiune validă sau Bearer. Operațiile de onboarding rămân supuse accesului pilot.

Mesaje și preluare de operator

Mesajele libere sunt limitate la fereastra de 24 de ore de la ultimul mesaj al clientului. În afara ei folosește un șablon aprobat și respectă acordul destinatarului. Preluarea de operator nu prelungește această fereastră. Revenirea la AI trebuie făcută explicit. Pauza agentului și deconectarea trebuie verificate înainte de reluarea trimiterilor.

Acceptarea mesajului de Meta, sent, delivered, read și failed sunt stări diferite; citirea depinde și de setările destinatarului. Nu considera textul generat de AI drept mesaj livrat. Calling, coexistence și campaniile nu sunt prezentate aici ca funcții disponibile.

Erori utile

• 503 whatsapp_rollout_pending: contul nu are acces pilot.
• 401 signup_session_expired sau 409 signup_session_already_used: reîncepe conectarea pentru o sesiune nouă.
• 409 whatsapp_number_already_connected_to_another_account: activul este deja legat de alt cont.
• phone_verification_required / registration_pin_required: finalizează pasul Meta indicat.
• Meta 131030: destinatarul nu este permis pentru numărul de test. Nu retrimite automat către alt număr.
• whatsapp_template_required: fereastra mesajelor libere s-a închis.

Conversațiile sunt păstrate în inbox. Consultă politica de confidențialitate și procedura de ștergere. Deconectarea canalului nu șterge automat istoricul.

Webhook-uri Meta

Pentru FB/IG/WhatsApp, mesajele intră prin webhook-ul Meta — configurat automat la conectare. Nu găzduiești tu nimic.

Profil Messenger / Instagram

Configurează profilul de mesagerie al unei pagini: buton „Începe", meniu persistent, mesaj de întâmpinare, ice-breakers. /messenger-settings, Bearer. :platform = facebook sau instagram.

Automation engine

Reguli event-driven (declanșator → condiții → acțiuni). Bearer, răspunsuri { success, data }.

Sequences & Broadcasts

Sequences (drip) — /sequences

GET / · GET /:id · POST / ({ name, steps[] }) · PUT /:id · DELETE /:id · PATCH /:id/activate · POST /:id/enroll ({ recipientId, pageId }) · GET /:id/enrollments.

Broadcasts (1-la-mulți) — /broadcasts

GET / · POST / ({ message | templateId, filterTags?, scheduledAt? }) · GET /:id · POST /:id/send (pune în coadă) · DELETE /:id. Livrarea e worker-driven; /send doar schimbă starea în sending.

Keywords & Workflows

Keywords (auto-reply pe cuvinte) — /keywords

GET / · GET /:id · POST / · PUT /:id · PATCH /:id/toggle · DELETE /:id · POST /match-preview ({ integrationId, text }).

La POST /: obligatoriu doar keyword. matchType ∈ exact|contains|starts_with|regex (implicit contains); responseType ∈ dm|comment|both (implicit dm).

Workflows — /workflows

GET / · GET /:id · POST / ({ name, steps[], triggerConfig }) · PUT /:id · DELETE /:id · PATCH /:id/activate.

Mesaje programate

/schedule, Bearer. POST /create ({ chat_id, name, description, dateTime, service } + repeat?) · POST /update ({ id, … }) · POST /delete ({ id }) · GET /by-conversation?chat_id=&service=.

Lead-uri & etichete

Conversațiile devin lead-uri, pe etichete și board kanban. Bearer.

amoCRM

Sincronizare cu amoCRM. Bearer. Reads întorc obiecte „goale" ({pipelines}, {leads}); writes { success }.

Bitrix24

Sincronizare CRM — POST /bitrix-crm/connect ({ webhookUrl }) · GET /bitrix-crm/status · GET /bitrix-crm/statuses · DELETE /bitrix-crm/disconnect. Toate Bearer.

Canal de chat (Bitrix24 Open Channels) — separat de sync-ul CRM, înregistrează un imbot la /bitrix: POST /bitrix ({ data: { botName, clientId, webhookUrl } }) · POST /bitrix/remove · GET /bitrix/getDataBitrix.

Google Sheets

Agentul scrie lead-urile ca rânduri într-o foaie. La conectare se atașează un tool builtin. Bearer.

Altegio — programări online

Conectează calendarul Altegio al unui salon. Clientul lipește doar Company ID; se atașează 5 tool-uri (servicii, disponibilitate, creare, anulare, mutare). Bearer.

Răspuns: { integrationId, companyId, salon, servicesCount, bookingEnabled, attached }. Stare: GET /altegio/for-assistant/:agentId; deconectare: DELETE pe aceeași rută.

Telegram Leads · SMS · alte integrări

Bază de cunoștințe (RAG)

Alimentează agentul cu surse — text, documente, site-uri, întrebări-răspuns. Bearer, răspunsuri { success, data }.

Fișiere & documente

Documente în indexul unui agent (pdf, doc, docx, txt, csv, json, md, markdown, rtf, log, text; ≤5 MB/fișier). Extensiile nelistate sunt încercate, nu respinse — doar lipsa extensiei → 400. Bearer.

Scraping site → index căutabil

Extrage conținutul unui site și îl face căutabil (pagini, produse). /scrape, Bearer.

Analytics & Dashboard

Analytics — /analytics (Bearer; răspunsuri „goale")

GET /messages-per-day?days= ([{ date, incoming, outgoing }]) · GET /top-agents?days= · GET /overview ({ messagesToday, messagesThisWeek, activeThreads, total_contacts, … }).

Dashboard — /api/v2/dashboard (recomandat) sau /api/v1/dashboard

Toate GET, Bearer, cache scurt, rate-limit 60/min: /stats?period= · /trend?days= · /pages · /leads/recent?limit= · /alerts · /comments-stats?period= · /cost-detail?period=.

Consum & credite

/usage, Bearer. Query period = 1d/7d/30d/all (implicit 30d).

Voce (ElevenLabs)

Clonare și management de voci. /create și /update folosesc multipart/form-data. Bearer.

Credite — cum se calculează

Creditul e unitatea de facturare. Numărul de credite pe un răspuns AI depinde DOAR de modelul folosit — nu de câți tokeni s-au consumat. E o taxare flat pe mesaj, per model.

credite_pe_mesaj = pret_flat_al_modelului  (+ suprataxe media, doar FB/IG)

Apelurile de tool și RAG/cunoștințe nu adaugă credite — un mesaj cu 5 tool-calls costă cât unul simplu.

Preț per model

Suprataxe media (doar FB/IG)

Peste prețul modelului: mesaj vocal primit (transcriere) +1; generare imagine +5/imagine; răspuns vocal TTS ElevenLabs +20 (alt TTS/STT +10).

Planuri & limite

• Sold = limit − current (din UserSettings.tokens).
• La activarea abonamentului: limit = max(limit, current + credite_plan).
• Top-up one-time: credite = floor(tokeni_cumpărați / 3).
• La epuizare (current ≥ limit) → 402 credits_exhausted.
• La înregistrare contul primește un sold inițial de credite; fără abonament activ nu există credite recurente.

Citirea stării (sold / consum)

Endpoint-urile de citire sunt documentate în Consum & credite (GET /usage/summary, GET /settings/credit-history) și Facturare (GET /stripe/billing/overview, GET /stripe/billing/dashboard).

Cont & profil

/users, Bearer.

Facturare (Stripe)

/stripe, Bearer. (Webhook-ul /stripe/webhook e public/semnat — nu-l apelezi tu.)

Chatbots — mapare canal ↔ agent

Un „chatbot" leagă un canal (FB page, IG, widget…) de un agent. /chatbots, Bearer.

Echipe & referral

Echipe (multi-user) — /teams

Mai mulți operatori pe un cont, cu roluri (admin/agent/viewer). Bearer.

Referral — /referrals

Program de recomandare cu coduri promo și cont Stripe Express. Bearer.

999.md (Simpals)

Integrare cu marketplace-ul 999.md. /trei9, Bearer.

Formulare & suport

/storage. Tichete de suport și formulare (unele publice, pentru pagini de contact).

Calitate agent (audit)

Audit automat al conversațiilor unui agent, cu scoruri și recomandări. Bearer.

Events & monitoring

Jurnal audit · Changelog · Conținut public

Postări pe pagini (Facebook & Instagram)

Publică și programează conținut pe paginile conectate. Bearer; proxy către Meta Graph.

Facebook — /page-posts

Instagram — /ig-publish

Comentarii FB/IG

Moderare și auto-reply AI pe comentariile de Facebook/Instagram, cu coadă de aprobare, template-uri și reguli de declanșare. /comments, Bearer.

Setări & moderare

Coadă de aprobare AI

Template-uri & reguli de declanșare

Comentarii live (FB Live)

Suport

Raportare bug programatică: POST /api/v1/bug-report — multipart cu până la 10 capturi (screenshots), rate-limit 5/min; atașează userul dacă trimiți un JWT, altfel anonim.