CONVIRO
Conviro API · v1 · stabili

Kurkite su Conviro.

Sujunkite klientų pokalbius, DI pagalbą, potencialius klientus ir automatizavimą per REST API bei webhookus.

Pagrindinis URL
api.conviro.io/v1/api
Autentifikacija
Bearer token
Atsakymas
ACK eilėje + webhook
zsh — conviro
$ curl -s https://api.conviro.io/v1/api/sessions/sess_3f2a/messages \
  -H "Authorization: Bearer cvr_live_***" \
  -d '{"content":"How do I return an order?"}'

# 201 Created — the AI reply follows via the message.new webhook
{
  "messageId": "6d1f0c6e-3b7a-...",
  "role": "system",
  "content": "Message received. Preparing a response...",
  "status": "queued"
}

Greitas startas

Jūsų pirmoji sėkminga užklausa

Sukurkite ribotą raktą, atverkite sesiją, siųskite žinutę ir asinchroninį atsakymą tvarkykite atskirai nuo patvirtinimo.

Išbandykite scenarinį demo be API rakto

5 užklausos per minutę vienam IP
curl -X POST https://useconviro.com/api/developers/demo \
  -H "Content-Type: application/json" \
  -d '{"content": "I want to return my last order"}'
  1. 1

    Sukurkite API raktą

    Eikite į Nustatymai → API raktai ir sukurkite raktą su chat:write apimtimi. Jis parodomas vieną kartą — saugokite jį savo slaptažodžių tvarkyklėje.

    API raktai prieinami nuo Pro plano.

    Gauti API raktą
  2. 2

    Išsiųskite žinutę

    Pavyzdžiai sukuria sesiją per POST /sessions ir Bearer raktu siunčia žinutę į POST /sessions/:id/messages.

  3. 3

    Apdorokite atsakymą

    Gaunate atgal messageId ir būseną „queued“. DI atsakymas sukuriamas asinchroniškai — prenumeruokite webhook message.new arba nuskaitykite sesiją per GET /sessions/:id.

const BASE = 'https://api.conviro.io/v1/api';
const key = process.env.CONVIRO_API_KEY;
if (!key) throw new Error('CONVIRO_API_KEY is not set');

const headers = {
  Authorization: `Bearer ${key}`,
  'Content-Type': 'application/json',
};

// 1. Open a session for one assistant.
const sessionRes = await fetch(`${BASE}/sessions`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ chatbotId: process.env.CONVIRO_CHATBOT_ID }),
});
if (!sessionRes.ok) throw await conviroError(sessionRes);
const session = await sessionRes.json();

// 2. Send the visitor's message.
const sendRes = await fetch(`${BASE}/sessions/${session.id}/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ content: 'Can I return an item I bought yesterday?' }),
});
if (!sendRes.ok) throw await conviroError(sendRes);

const ack = await sendRes.json();
console.log(ack.status); // "queued"

// The ASSISTANT REPLY IS NOT IN THAT RESPONSE. It is produced
// asynchronously. Receive it on the message.new webhook, or poll
// GET /v1/api/sessions/:id. Awaiting this call for the answer waits
// forever — the response is an acknowledgement, nothing more.

/** Parses whichever of the three error bodies came back. */
async function conviroError(res: Response): Promise<Error> {
  const body = await res.json().catch(() => ({}) as Record<string, unknown>);
  // Validation failures put an ARRAY in `message`; everything else a string.
  const raw = (body as { message?: string | string[] }).message;
  const message = Array.isArray(raw) ? raw.join('; ') : raw ?? res.statusText;
  const err = new Error(`Conviro ${res.status}: ${message}`);
  // Only the per-key 429 carries retryAfter, and it has no timestamp field.
  (err as Error & { retryAfter?: number }).retryAfter =
    (body as { retryAfter?: number }).retryAfter ??
    Number(res.headers.get('retry-after')) ||
    undefined;
  return err;
}

Atsakymas

201 Created · application/json
{
  "messageId": "6d1f0c6e-3b7a-4f0e-9a52-8c1e2d4b7a90",
  "role": "system",
  "content": "Message received. Preparing a response...",
  "createdAt": "2026-04-14T10:22:03.412Z",
  "status": "queued"
}

Interaktyvus API demo

Scenariniai atsakymai, tikros HTTP užklausos

Šis ribojamas endpointas grąžina deterministinius pavyzdžius ir imituotą delsą. DI modelis nekviečiamas. Produkcinė API atsakymus apdoroja asinchroniškai.

Scenarinis demo

Demonstracinis agentas

POST /api/developers/demo

Simuliuota demonstracija — iš anksto parengti atsakymai ir dirbtinė delsa; DI modelis nekviečiamas. Tikroji API atsako asinchroniškai.

Sveiki — grąžinu scenarinius pavyzdžius saugiam demo endpointo patikrinimui.

greetingconf 1.00

Ką grąžino API

{
  "intent": "greeting",
  "confidence": 1,
  "model": "scripted-demo",
  "message": {
    "role": "assistant",
    "content": "Sveiki — grąžinu scenarinius pavyzdžius saugiam demo endpointo patikrinimui."
  }
}

Demonstracinio galinio taško užklausų dažnis ribojamas iki 5 req/min per IP. Produkciniai limitai priklauso nuo rakto ir plano. Gavę 429 laikykitės Retry-After.

Naudojimo atvejai

Sujunkite procesus aplink kiekvieną pokalbį

Naudokite siauro leidimo operacijas ir įvykius. Kortelės paleidžia demo pavyzdžius; tikri rezultatai priklauso nuo duomenų ir konfigūracijos.

Kaip tai veikia

Patvirtinimas nėra DI atsakymas

Kvietimas tik patvirtina įtraukimą į eilę. Atsakymą gaukite per message.new arba vėliau skaitydami sesiją.

  1. Siųsti žinutę

    POST /sessions/:id/messages

  2. Gauti patvirtinimą

    201 · status: queued

  3. Apdoroti atsakymą

    Asinchroninis produkcinis srautas

  4. Gauti atsakymą

    message.new · GET /sessions/:id

Pradinis atsakymas
Eilės patvirtinimas
Atsakymo pristatymas
Webhook arba sesijos skaitymas
Užklausų limitai
Pagal raktą ir planą

Dokumentacija

API paviršius

Šios viešos operacijos gaunamos iš tos pačios sutarties, kuri tikrina API. Kanoninis bazinis URL: https://api.conviro.io/v1/api

Autentifikacija ir webhookai
MetodasKeliasReikalinga apimtis
POST/sessionschat:write
GET/sessionschat:read
GET/sessions/:id/messageschat:read
GET/sessions/:idchat:read
POST/sessions/:id/messageschat:write
POST/sessions/:id/identifychat:write
POST/knowledgekb:write
DELETE/knowledge/:idkb:write
GET/analytics/summaryanalytics:read
GET/contactscontacts:read
GET/contacts/:idcontacts:read
POST/contactscontacts:write
PATCH/contacts/:idcontacts:write
GET/lead-formschat:read or magento:module
GET/appointments/slotsappointments:read
POST/appointmentsappointments:write
GET/appointmentsappointments:read
DELETE/appointments/:idappointments:write
GET/webhookswebhooks:write
POST/webhookswebhooks:write
DELETE/webhooks/:idwebhooks:write
POST/consent/whatsappconsent:write
chat:readRead sessions and their messages, and list lead forms.
chat:writeCreate sessions, send messages, identify visitors.
kb:readRead knowledge base items. Minted, but required by no public operation today.
kb:writeCreate and delete knowledge base items, and drive the e-commerce sync endpoints.
analytics:readRead the workspace analytics summary.
webhooks:writeManage webhook subscriptions. Note this is required to LIST them as well as to change them — there is no webhooks:read scope, so a read-only integration still needs the write scope here.
contacts:readRead CRM contacts. Returns PII.
contacts:writeCreate and update CRM contacts — the records human agents work from.
leads:writeCreate a lead: drop a new inbound record at the top of the funnel. Deliberately narrower than contacts:write, so an automation posting form fills does not also get the power to rewrite existing people. Minted, but required by no public operation today.
appointments:readRead open slots and booked appointments.
appointments:writeBook and cancel appointments.
consent:writeRecord a WhatsApp marketing opt-in. Its own scope rather than riding on leads or contacts: a key that can post form fills should not also be able to assert that a person agreed to campaigns.
magento:moduleWhat the Conviro Magento module (1.4.0+) needs and nothing more: it registers its store, delivers the store event outbox, reads the admin stats cards and lists lead forms. It reads no conversation and writes no knowledge-base item through the public API. The module's browser-mediated connect mints a key with only this scope, limited to the chosen assistant.

Webhook'ai

Minimalios teisės. Tikrinkite kiekvieną įvykį.

API raktai naudoja Bearer autentifikaciją ir aiškius scope. Webhookai pasirašomi HMAC-SHA256, kad galėtumėte tikrinti neapdorotą body.

Riboto scope API raktai

Nuo Pro suteikite tik būtinus scope ir prireikus ribokite asistentus. Visas raktas parodomas vieną kartą.

Gauti API raktą

Neapdoroto body tikrinimas

Pastoviu laiku tikrinkite parašą ir laiką, atmeskite senas užklausas, greitai patvirtinkite ir tada apdorokite.

Įvykiai

  • message.newA message was added to a session, by the visitor or by the assistant.
  • session.startedA new conversation session was created.
  • session.closedA session was closed.
  • session.reopenedA closed conversation was reopened by staff with the explicit Reopen action (POST /sessions/:id/reopen).
  • session.escalatedA session was escalated to a human.
  • handoff.requestedA visitor asked for a human agent.
  • lead.capturedA lead was captured from a conversation.
  • lead.createdA lead record was created outside a chat — from an ad integration, a lead form, or an e-commerce order.
  • lead_form.submittedA lead form was submitted.
  • csat.submittedA CSAT rating was submitted.
  • csat.receivedThe same rating as csat.
  • ai.failedThe assistant could not produce an answer.
  • ticket.createdA support ticket was opened.
  • ticket.resolvedA support ticket was resolved.
  • contact.createdA CRM contact was created.
  • contact.updatedA CRM contact was updated.
  • contact.mergedTwo CRM contacts were merged.
  • contact.deletedA CRM contact was deleted.
  • appointment.bookedAn appointment was booked. Not listed in the dashboard event picker — subscribe with "*" or by name.
  • appointment.cancelledAn appointment was cancelled. Not listed in the dashboard event picker — subscribe with "*" or by name.
  • lead.hotA lead crossed the hot-lead threshold. Not listed in the dashboard event picker — subscribe with "*" or by name.
  • lead.updatedA lead record was corrected after capture. Not listed in the dashboard event picker — subscribe with "*" or by name.

Naudingoji apkrova

POST your-endpoint · application/json
{
  "event": "session.closed",
  "timestamp": "2026-04-14T10:22:03.412Z",
  "data": {
    "sessionId": "sess_3f2a...",
    "chatbotId": "bot_123"
  }
}

Patikrinkite parašą

node.js
// Node.js (Express) — verify a Conviro webhook
import crypto from 'crypto';

// The RAW body is required. express.json() parses and discards it, and
// JSON.stringify(req.body) does NOT reproduce the signed bytes — key
// order and whitespace both change the digest.
app.post('/conviro/webhook',
  express.raw({ type: 'application/json', limit: '1mb' }),
  (req, res) => {
    if (!verify(req.body, req.header('X-Webhook-Signature'))) {
      return res.status(401).end();
    }
    res.status(200).end();            // acknowledge within 10s
    void handle(JSON.parse(req.body.toString('utf8')));
  });

const TOLERANCE_SECONDS = 300;

function verify(rawBody, header) {
  if (!header) return false;

  // Header format: t=<unix_seconds>,v1=<hex_digest>
  const parts = new Map(header.split(',').map((p) => {
    const i = p.indexOf('=');
    return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
  }));
  const timestamp = parts.get('t');
  const signature = parts.get('v1');
  if (!timestamp || !signature) return false;

  // Replay window: without it, a captured payload is valid forever.
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;

  // The digest covers "<timestamp>.<rawBody>" — NOT the body on its own.
  const expected = crypto
    .createHmac('sha256', process.env.CONVIRO_WEBHOOK_SECRET)
    .update(timestamp + '.')
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(signature, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  // timingSafeEqual throws on a length mismatch, so check length first.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

SDK

Naudokite pažįstamą HTTP klientą

Conviro šiuo metu neturi oficialaus SDK. Šie kanoniniai pavyzdžiai naudoja standartines HTTP bibliotekas ir bendrą API sutartį.

const BASE = 'https://api.conviro.io/v1/api';
const key = process.env.CONVIRO_API_KEY;
if (!key) throw new Error('CONVIRO_API_KEY is not set');

const headers = {
  Authorization: `Bearer ${key}`,
  'Content-Type': 'application/json',
};

// 1. Open a session for one assistant.
const sessionRes = await fetch(`${BASE}/sessions`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ chatbotId: process.env.CONVIRO_CHATBOT_ID }),
});
if (!sessionRes.ok) throw await conviroError(sessionRes);
const session = await sessionRes.json();

// 2. Send the visitor's message.
const sendRes = await fetch(`${BASE}/sessions/${session.id}/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ content: 'Can I return an item I bought yesterday?' }),
});
if (!sendRes.ok) throw await conviroError(sendRes);

const ack = await sendRes.json();
console.log(ack.status); // "queued"

// The ASSISTANT REPLY IS NOT IN THAT RESPONSE. It is produced
// asynchronously. Receive it on the message.new webhook, or poll
// GET /v1/api/sessions/:id. Awaiting this call for the answer waits
// forever — the response is an acknowledgement, nothing more.

/** Parses whichever of the three error bodies came back. */
async function conviroError(res: Response): Promise<Error> {
  const body = await res.json().catch(() => ({}) as Record<string, unknown>);
  // Validation failures put an ARRAY in `message`; everything else a string.
  const raw = (body as { message?: string | string[] }).message;
  const message = Array.isArray(raw) ? raw.join('; ') : raw ?? res.statusText;
  const err = new Error(`Conviro ${res.status}: ${message}`);
  // Only the per-key 429 carries retryAfter, and it has no timestamp field.
  (err as Error & { retryAfter?: number }).retryAfter =
    (body as { retryAfter?: number }).retryAfter ??
    Number(res.headers.get('retry-after')) ||
    undefined;
  return err;
}

Klaidos

Pirma tikrinkite būseną, tada body

Dauguma klaidų turi statusCode, message ir timestamp; rakto 429 naudoja retryAfter. Nemanykite, kad formatas visada vienodas.

BūsenaPavadinimasKada tai įvyksta
400Bad RequestThe request was rejected by the handler. `message` is a single string. A 4xx may additionally carry `error`, `code`, `reason` or `state`: a machine-readable name, always one identifier (lower_snake or UPPER_SNAKE). Branch on that name when it is present, never on `message`; most errors carry none.
400Bad Request (validation)Body validation failed. Same status and same keys as bad_request, but `message` is an ARRAY of strings, one per failed constraint. Parse it as `string | string[]` or the most common 400 in the API will crash your error handler. Unknown fields also land here: the global pipe runs with forbidNonWhitelisted, so an undeclared field is a 400 rather than being ignored — except on the two contacts endpoints that bind no DTO class, where unknown fields pass through silently.
401UnauthorizedMissing or malformed Authorization header, or an invalid, revoked or expired key. Never retry: the credential will not become valid.
403ForbiddenThe key is valid but lacks the scope, or is restricted to assistants that do not include the one referenced. Scopes are evaluated with OR: holding ANY of the listed scopes is enough. Fix the key, do not retry.
404Not FoundNo such resource in your workspace. A resource that exists in another tenant is a 404 here, not a 403 — the tenant filter is applied before the lookup, so cross-tenant ids are indistinguishable from absent ones. That is deliberate.
429Too Many RequestsPer-key rate limit exceeded. THIS BODY IS DIFFERENT: it carries `retryAfter` and NO `timestamp`, because the guard writes it directly to the response and never reaches the global filter. A `Retry-After: 60` header is set. The separate plan-level limiter produces a 429 with a different message and no `retryAfter`. Retry after the header says, with backoff.
500Server ErrorSomething failed on our side. The message is always this fixed string — internal detail is logged, never returned. Retry with exponential backoff.
{
  "statusCode": 401,
  "message": "Invalid or expired API key",
  "timestamp": "2026-09-20T10:22:03.412Z"
}

Laikykitės Retry-After ir eksponentinio laukimo. Vieši rašymai neturi idempotencijos rakto; pakartojimą apsaugokite patys.

Pasiruošę, kai tik jūs

Sujunkite Conviro su savo sistemomis

Sukurkite workspace, pasirinkite Pro ar aukštesnį planą ir prieš produkciją sugeneruokite ribotą API raktą.

Gauti API raktą