Build on aichat.md — conversational AI agents, on any channel.

Quick start

The agent on your website, in three steps:

1. Create an agent in the aichat.md dashboard and copy its widgetId (a UUID, from Agent → Channels → Chat Widget).
2. Paste the embed script before </body>.
3. Or, for your own UI, call POST /widget/chat.

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

Base URL & versions

Authentication

There are two levels of access:

Getting a token

Flow: register → verify-email → login. Endpoints that issue a token return { 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": "…" }   if 2FA is enabled
# → 228 { "email": "…" }                                  email not confirmed (a NEW code is resent automatically)

Authentication endpoints

2FA (TOTP) — management (all 🔒 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 (the device id from the list).

Then send the token on any authenticated route: Authorization: Bearer <accessToken>. Auth error: 401 { message: "🚫 Un-Authorized 🚫" }.

Conventions & pagination

Response shape

The convention is not uniform across the platform — check it per area:

Pagination

Large list endpoints accept page + limit (e.g. /conversations, /leads) or cursor + limit (e.g. /conversations/:id/messages). Where no cap is specified, limit has a safety maximum (e.g. usage/transactions ≤ 500).

Time zones, encryption, ids

Date-times are in the Chișinău time zone (Europe/Chisinau) unless specified otherwise. Agents and the widget use UUIDs; conversations/threads use numeric ids.

Errors & rate limits

Response codes

Rate limits — widget

Widget installation

Three embed methods. Pick one:

1. Bridge script — recommended (web component)

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

2. Loader — safe for Google Tag Manager (web component)

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

3. Static embed 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>

The look (color, name, avatar, message) is set from the dashboard or through the widget config API. The snippet can also be generated programmatically with POST /widget/embed-code { chatbot_id } → { success, html }.

Conversation — 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": "What services do you offer?" }]
  }'

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);

Response (200)

{
  "success": true,
  "message": "We offer manicure, pedicure and podiatry treatments…",
  "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", … } // camelCase duplicate
}

Streaming — token by token (SSE)

The response is Server-Sent Events: each event is a data: <JSON> line, with its type in the type field. 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();                     // keep the incomplete fragment
  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);
  }
}

Widget config — public read

The agent's public configuration (name, message, color, avatar, suggestions, products). The canonical endpoint is POST; the GET variant is an alias with ETag/304 caching. For setting the config (owner, with a token) see Agent widget config.

POST requires the body { widget_id }; GET takes widget_id from the path and adds ETag + Cache-Control: max-age=60 (send If-None-Match to get 304). Response: { success, config: { name, primary_color, welcome_message, placeholder, assistant_name, greeting_message, position, starter_prompts[], agent:{name,avatar,tone}, products[], cart_enabled } }.

Conversation history

The session's last 40 messages: { success, messages: [{ role, content, time }] }. Both parameters are required.

Order

Success: { success: true, order_id }. Rate limit 5/min/IP; 24h deduplication on phone+widget (409 duplicate_lead_24h).

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

Headless integration — the agent in your UI

Already have a chat on your website and only want the "brain"? You can integrate the full agent into your own interface — without our bundle, without an SDK, without cookies. The whole surface is a public JSON/SSE API, authenticated only by widgetId. In practice you call the same endpoints described above from your own code.

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": "Hi, do you deliver to Chișinău?" }]
  }'
# → { success, message, products, quick_replies, sources, actions, ... }

The pieces you need, all documented above:

Authentication & CORS

• Auth = widgetId only. No API key, no Bearer, no cookie, no identity HMAC.
• CORS on /widget reflects any origin (credentials: false) — your domain is accepted by default.
• The agent's allowed-origins list is checked at application level and is bypassed when there is no Origin header (server-side call). So if you call from your backend, you are never blocked. If you call directly from the browser, ask the agent's owner to add your domain to the allowed origins.

Memory / session

You own the sessionId (a stable string per user-conversation). The server persists every turn, but does not automatically re-inject the history into the prompt — for multi-turn, send the history yourself in messages[] (max 20 messages, 4000 characters/message, 3 images).

Recommended vs legacy

Agents

Create and manage agents programmatically. All routes require Bearer. An agent has: a name, instructions (system prompt), model, AI provider, tone, channels and config.

curl -X POST https://aichat.md/api/v1/agents \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "Salon assistant", "instructions": "You are the online assistant…", "model": "gpt-4o-mini", "tone": "friendly" }'

Agent widget config

Atomic merge into channels.widget. Fields: theme_color, persona_name, persona_avatar_url, welcome_message, subtitle, placeholder, starter_prompts (max 4, ≤80 chars), position, enabled, pet_name, show_online_dot, theme_mode, quick_replies_enabled, auto_focus_input, allowed_origins, plus hide_branding and footer_text (PRO+ only). Unified alternative: PUT /agents/:id/widget-config (also accepts legacy camelCase keys).

Models & providers

An agent has a model (a text name, e.g. gpt-4o-mini) and an ai_provider (default azure). The available values depend on the account's plan — get the actual list with:

Response: { models, userPlanId }. Use a model from this list with POST /agents / PUT /agents/:id. (There is also the historical alias /asisstants/models, with a double "s".)

Tools (functions)

Give the agent capabilities — call an API, run code or a built-in function. Bound to an agent. All routes require Bearer.

The three types

The parameters field (the arguments seen by the model) is a list:

curl -X POST https://aichat.md/api/v1/agents/AGENT_ID/tools \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "check_stock",
    "description": "Checks a product's stock by code",
    "tool_type": "webhook",
    "webhook_url": "https://api.shop.md/stock?sku={{sku}}",
    "webhook_method": "GET",
    "parameters": [{ "name": "sku", "type": "string", "required": true }]
  }'

Conversations

The unified inbox across all channels. All routes require Bearer. Responses { success, data }.

Human handoff

Moves a conversation from the bot to a human operator and back. Bearer, responses { success, data }.

Notes · Tags · Canned · Export · Contacts · Pause-rules

Inbox tools. All Bearer.

Meta templates

Sends structured templates on Messenger (proxy to Facebook Graph). Bearer; all require recipient_id and return { success, message_id }.

Template library (CRUD) — /templates/library

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

Facebook Messenger

A page is connected through OAuth from the dashboard; the API binds a page to an agent. All require Bearer.

Instagram

All require Bearer.

Telegram

Shared bot (@aichat_connect_bot) — the customer does not enter a bot token. Connection: 6-digit code → in the bot → Telegram Business Connection (Premium) → business_connection_id. All require Bearer.

WhatsApp (Cloud API)

Connect in the dashboard

1. Create and activate an agent.
2. Open WhatsApp and start Embedded Signup if pilot access is available.
3. Authorize your own business, WABA and phone number. Do not paste access tokens into the dashboard.
4. Complete any verification and registration required by Meta; check the webhook subscription and assigned agent.
5. Send an inbound message from a dedicated authorized test phone and confirm the reply on the phone, not only in the inbox.

You need the required rights to the selected assets. A number can belong to only one aichat.md account. Meta test numbers can send only to recipients allowed in their test list.

Authenticated API

Prefix: /api/v1; valid session or Bearer. Onboarding operations remain gated by pilot access.

Messages and operator handoff

Free-form messages are restricted to the 24-hour window from the customer's last message. Outside that window, use an approved template and respect recipient opt-in. Operator takeover does not extend this window. Returning to AI must be intentional. Check agent pause and disconnection before resuming sends.

Meta acceptance, sent, delivered, read and failed are distinct states; read receipts also depend on recipient settings. AI-generated text is not delivery proof. Calling, coexistence and campaigns are not presented here as available features.

Troubleshooting

• 503 whatsapp_rollout_pending: the account has no pilot access.
• 401 signup_session_expired or 409 signup_session_already_used: restart connection for a fresh session.
• 409 whatsapp_number_already_connected_to_another_account: the asset belongs to another account.
• phone_verification_required / registration_pin_required: complete the indicated Meta step.
• Meta 131030: the recipient is not allowed for this test number. Do not automatically send to a different number.
• whatsapp_template_required: the free-form messaging window has closed.

Conversations are retained in the inbox. See the privacy policy and data deletion procedure. Disconnecting a channel does not automatically erase history.

Meta webhooks

For FB/IG/WhatsApp, messages come in through the Meta webhook — configured automatically on connection. You don't host anything.

Messenger / Instagram profile

Configures a page's messaging profile: "Get Started" button, persistent menu, greeting message, ice-breakers. /messenger-settings, Bearer. :platform = facebook or instagram.

Automation engine

Event-driven rules (trigger → conditions → actions). Bearer, responses { 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 (one-to-many) — /broadcasts

GET / · POST / ({ message | templateId, filterTags?, scheduledAt? }) · GET /:id · POST /:id/send (queues) · DELETE /:id. Delivery is worker-driven; /send only changes the state to sending.

Keywords & Workflows

Keywords (keyword auto-reply) — /keywords

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

On POST /: only keyword is required. matchType ∈ exact|contains|starts_with|regex (default contains); responseType ∈ dm|comment|both (default dm).

Workflows — /workflows

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

Scheduled messages

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

Leads & tags

Conversations become leads, with tags and a kanban board. Bearer.

amoCRM

Synchronization with amoCRM. Bearer. Reads return "bare" objects ({pipelines}, {leads}); writes return { success }.

Bitrix24

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

Chat channel (Bitrix24 Open Channels) — separate from the CRM sync, registers an imbot at /bitrix: POST /bitrix ({ data: { botName, clientId, webhookUrl } }) · POST /bitrix/remove · GET /bitrix/getDataBitrix.

Google Sheets

The agent writes leads as rows in a sheet. On connection a builtin tool is attached. Bearer.

Altegio — online booking

Connects a salon's Altegio calendar. The customer only pastes the Company ID; 5 tools are attached (services, availability, create, cancel, reschedule). Bearer.

Response: { integrationId, companyId, salon, servicesCount, bookingEnabled, attached }. Status: GET /altegio/for-assistant/:agentId; disconnect: DELETE on the same route.

Telegram Leads · SMS · other integrations

Knowledge base (RAG)

Feed the agent with sources — text, documents, websites, Q&A pairs. Bearer, responses { success, data }.

Files & documents

Documents in an agent's index (pdf, doc, docx, txt, csv, json, md, markdown, rtf, log, text; ≤5 MB/file). Unlisted extensions are attempted, not rejected — only a missing extension → 400. Bearer.

Website scraping → searchable index

Extracts a website's content and makes it searchable (pages, products). /scrape, Bearer.

Analytics & Dashboard

Analytics — /analytics (Bearer; "bare" responses)

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

Dashboard — /api/v2/dashboard (recommended) or /api/v1/dashboard

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

Usage & credits

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

Voice (ElevenLabs)

Voice cloning and management. /create and /update use multipart/form-data. Bearer.

Credits — how they are calculated

The credit is the billing unit. The number of credits for an AI response depends ONLY on the model used — not on how many tokens were consumed. It is a flat per-message charge, per model.

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

Tool calls and RAG/knowledge add no credits — a message with 5 tool calls costs the same as a simple one.

Price per model

Media surcharges (FB/IG only)

On top of the model price: incoming voice message (transcription) +1; image generation +5/image; ElevenLabs TTS voice reply +20 (other TTS/STT +10).

Plans & limits

• Balance = limit − current (from UserSettings.tokens).
• On subscription activation: limit = max(limit, current + credite_plan).
• Top-up one-time: credite = floor(tokeni_cumpărați / 3).
• When exhausted (current ≥ limit) → 402 credits_exhausted.
• New accounts start with an initial credit balance; without an active subscription there are no recurring credits.

Reading the status (balance / usage)

The read endpoints are documented in Usage & credits (GET /usage/summary, GET /settings/credit-history) and Billing (GET /stripe/billing/overview, GET /stripe/billing/dashboard).

Account & profile

/users, Bearer.

Billing (Stripe)

/stripe, Bearer. (The /stripe/webhook webhook is public/signed — you do not call it.)

Chatbots — channel ↔ agent mapping

A "chatbot" links a channel (FB page, IG, widget…) to an agent. /chatbots, Bearer.

Teams & referral

Teams (multi-user) — /teams

Multiple operators on one account, with roles (admin/agent/viewer). Bearer.

Referral — /referrals

Referral program with promo codes and a Stripe Express account. Bearer.

999.md (Simpals)

Integration with the 999.md marketplace. /trei9, Bearer.

Forms & support

/storage. Support tickets and forms (some public, for contact pages).

Agent quality (audit)

Automatic audit of an agent's conversations, with scores and recommendations. Bearer.

Events & monitoring

Audit log · Changelog · Public content

Page posts (Facebook & Instagram)

Publish and schedule content on connected pages. Bearer; proxy to Meta Graph.

Facebook — /page-posts

Instagram — /ig-publish

FB/IG comments

Moderation and AI auto-reply on Facebook/Instagram comments, with an approval queue, templates and trigger rules. /comments, Bearer.

Settings & moderation

AI approval queue

Templates & trigger rules

Live comments (FB Live)

Support

Programmatic bug reporting: POST /api/v1/bug-report — multipart with up to 10 screenshots (screenshots), rate limit 5/min; attaches the user if you send a JWT, otherwise anonymous.