Juuruta AI-klienditoe agent 5 minutiga
REST API ja veebihaagid piletite lahendamiseks, müügivihjete kogumiseks ja inimestele üleandmiseks — toetatud sinu enda teadmusbaasi poolt, ilma et peaksid orkestratsiooni ise ehitama.
- Baas-URL
- api.conviro.io/v1
- Autentimine
- Bearer-token
- Vastus
- JSON · p50 ~450ms
$ curl -s 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"
}Kiirstart
Sinu esimene edukas päring
Kolm sammu. Kopeeritav ja kleebitav. Näed päris AI-vastust kuuekümne sekundi jooksul — või jäta registreerimine täiesti vahele ja proovi seda kohe oma terminalist.
Proovi ilma API-võtmeta — kohe
5 päringut/min IP kohtacurl -X POST https://conviro.io/api/developers/demo \
-H "Content-Type: application/json" \
-d '{"content": "I want to return my last order"}'- 1
Loo API-võti
Mine jaotisse Seaded → API-võtmed ja loo võti, millel on
Hangi API-võtichat:writeulatus. Seda näidatakse vaid korra — salvesta see oma saladusehaldurisse. - 2
Saada sõnum
Tee POST aadressile /sessions/:id/messages koos Bearer-tokeniga. Kasuta oma olemasolevat seansi id-d või loo esmalt uus käsuga POST /sessions.
- 3
Käsitle vastust
Saad tagasi
messageIdja oleku „queued“. Tehisintellekti vastus luuakse asünkroonselt — tellige webhook message.new või lugege seanssi käsuga GET /sessions/:id.
curl -X POST https://api.conviro.io/v1/api/sessions/SESSION_ID/messages \
-H "Authorization: Bearer cvr_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "Can I return an item I bought yesterday?"}'Vastus
{
"messageId": "6d1f0c6e-3b7a-4f0e-9a52-8c1e2d4b7a90",
"role": "system",
"content": "Message received. Preparing a response...",
"createdAt": "2026-04-14T10:22:03.412Z",
"status": "queued"
}Playground
Try it right now — no signup
Real HTTP requests to a rate-limited demo endpoint that returns scripted replies — no AI model is called, and the delay is artificial. The authenticated API answers asynchronously (see the quick start below).
Demoagent
POST /api/developers/demo
Simuleeritud demo — eelkirjutatud vastused ja tehisviivitus; tehisintellekti mudelit ei kutsuta. Päris API vastab asünkroonselt.
Tere 👋 Olen reaalajas demo. Proovi eelseadet, klõpsa ülal kasutusjuhul või kirjuta enda oma.
Mida API tagastas
{
"intent": "greeting",
"confidence": 1,
"model": "scripted-demo",
"message": {
"role": "assistant",
"content": "Tere 👋 Olen reaalajas demo. Proovi eelseadet, klõpsa ülal kasutusjuhul või kirjuta enda oma."
}
}Demo lõpp-punkti päringusagedus on piiratud: 5 req/min per IP. Päris API-võti saab vaikimisi 60 päringut minutis (seadistatav).
Kasutusjuhud
Mida meeskonnad tegelikult ehitavad
Klõpsa mis tahes kaardil, et seda mänguväljakul reaalajas käivitada — näed päris API-vastust sekundi jooksul.
Viitedokumentatsioon
API-pind
Lõpp-punktid, mida kõige rohkem kasutad. Baas-URL: https://api.conviro.io/v1/api
| Meetod | Tee | Nõutav ulatus | Kirjeldus |
|---|---|---|---|
| POST | /sessions | chat:write | Create a new chat session |
| GET | /sessions | chat:read | List sessions for incremental reconciliation (keyset cursor, metadata only — no transcripts) |
| GET | /sessions/:id/messages | chat:read | Paginated message history for a session (oldest first, keyset cursor) |
| GET | /sessions/:id | chat:read | Get session with last 50 messages |
| POST | /sessions/:id/messages | chat:write | Send a message and get AI response |
| POST | /sessions/:id/identify | chat:write | Identify the visitor in a session from your backend — no frontend change needed |
| POST | /knowledge | kb:write | Add a knowledge base item |
| DELETE | /knowledge/:id | kb:write | Delete a knowledge base item |
| GET | /analytics/summary | analytics:read | Get analytics summary |
| GET | /contacts | contacts:read | List contacts with pagination and filters |
| GET | /contacts/:id | contacts:read | Get single contact with stats |
| POST | /contacts | contacts:write | Create or find contact by email |
| PATCH | /contacts/:id | contacts:write | Update contact fields |
| GET | /lead-forms | chat:read | List active lead forms |
| GET | /appointments/slots | appointments:read | Open booking slots for a chatbot (optionally one local date / service) |
| POST | /appointments | appointments:write | Book an appointment directly (trusted backend — no OTP) |
| GET | /appointments | appointments:read | List appointments (newest first) |
| DELETE | /appointments/:id | appointments:write | Cancel an appointment (also removes the calendar event) |
| GET | /webhooks | webhooks:write | List webhook subscriptions |
| POST | /webhooks | webhooks:write | Subscribe to an event (creates a webhook subscription) |
| DELETE | /webhooks/:id | webhooks:write | Unsubscribe (deletes a webhook subscription) |
| POST | /consent/whatsapp | consent:write | Record a WhatsApp marketing opt-in collected on your checkout or form, with the text shown |
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.SDK-d
Teegid ja kliendid
Saadame ametlikke SDK-sid välja etappidena. REST API on väike, stabiilne ja lihtne ümber pakkida — sa ei pea ootama.
Node.js / TypeScript
Ametlik · varsti tulekul// @conviro/sdk — in private beta. The REST API
// already works great with fetch/axios today.PHP
Ametlik · varsti tulekul// composer require conviro/sdk — in private beta.
// Use the cURL example below in the meantime.Python
Kogukond# No official SDK yet — the REST API is small enough
# that plain `requests` or `httpx` works well.Go, Ruby, C#
Kasuta REST API-t otse// No SDK — any HTTP client works. The auth header
// is the only thing you need.Vead
Ennustatavad veakujud
Iga mitte-2xx vastus kasutab sama JSON-ümbrist. Lisa requestId kui võtad klienditoega ühendust.
| Olek | Nimi | Millal see juhtub |
|---|---|---|
| 400 | Bad Request | The request was rejected by the handler. `message` is a single string. |
| 400 | Bad 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. |
| 401 | Unauthorized | Missing or malformed Authorization header, or an invalid, revoked or expired key. Never retry: the credential will not become valid. |
| 403 | Forbidden | The 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. |
| 404 | Not Found | No 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. |
| 429 | Too Many Requests | Per-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. |
| 500 | Server Error | Something failed on our side. The message is always this fixed string — internal detail is logged, never returned. Retry with exponential backoff. |
Vastuse sisu
{
"statusCode": 401,
"error": "Unauthorized",
"message": "API key is missing or invalid.",
"requestId": "req_1H8z...",
"docsUrl": "https://conviro.io/developers#errors"
}Vea 429 korral järgi Retry-After päist. Vea 5xx korral korda eksponentsiaalse taandumisega kuni kolm korda.
Veebihaagid
Reaalajas sündmused, verifitseeritud
Allkirjastame iga kohaletoimetuse HMAC-SHA256-ga. Ebaõnnestunud kohaletoimetused korratakse kolm korda eksponentsiaalse taandumisega. Kaitselüliti paneb korduvalt ebaõnnestuvad lõpp-punktid 60 sekundiks karantiini.
Sündmused
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.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.
Andmesisu
{
"event": "session.closed",
"timestamp": "2026-04-14T10:22:03.412Z",
"data": {
"sessionId": "sess_3f2a...",
"chatbotId": "bot_123"
}
}Verifitseeri allkiri
// 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);
}Kuidas see toimib
Üks API-päring, terve töötluskonveier
Sina saadad sõnumi — meie hoolitseme liigitamise, otsingu, genereerimise ja suunamise eest. Saad tagasi ühe vastuse koos kõige vajalikuga, et otsustada, mis edasi saab.
Külastaja
Saadab sõnumi
Liigita
Kavatsus + kindlus
Teadmised
Toob teie KB-st
Genereeri
Vastus + soovitatud toimingud
Eskaleeri (võib-olla)
Madal kindlus → inimene
- Tüüpiline viiteaeg
- ~450ms p50
- Päringusageduse piirang
- 60 päringut minutis võtme kohta · seadistatav
- Kordusproovikindel
- Idempotentsed kordusproovid · veebihaagi taandumine
Valmis, kui sina oled
Esimene API-päring on 60 sekundi kaugusel
Loo API-võti, kopeeri kiirstardi katkend, näe päris vastust. Tasuta tase sisaldab piisavalt päringuid ehitamiseks ja testimiseks.