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)

Toate cer Bearer.

Un număr aparține unui singur cont: 409 whatsapp_number_already_connected_to_another_account.

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.
• Fiecare cont nou primește automat un trial de 14 zile cu 150 credite; după expirare rămâne pe free (0 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.