Conviro API · v1 · stabilne

Wdróż agenta wsparcia AI w 5 minut

REST API i webhooki do rozwiązywania zgłoszeń, pozyskiwania leadów i przekazywania do ludzi — wspierane przez twoją bazę wiedzy, bez budowania orkiestracji.

Zacznij budować Dokumentacja API Pobierz klucz API

Bazowy URL: api.conviro.io/v1
Auth: Bearer token
Odpowiedź: JSON · p50 ~450ms

zsh — conviro

$ curl -s api.conviro.io/v1/api/sessions/sess_3f2a/messages \
  -H "Authorization: Bearer cvr_live_***" \
  -d '{"content":"How do I return an order?"}'

# 200 OK — 412ms
{
  "requestId": "req_1H8zKj9m2QrT",
  "latencyMs": 412,
  "intent": "refund.request",
  "confidence": 0.94,
  "model": "conviro-resolve-2",
  "message": { "content": "..." }
}

Szybki start

Twoje pierwsze udane żądanie

Trzy kroki. Wklejalne. Zobaczysz prawdziwą odpowiedź AI w ciągu sześćdziesięciu sekund — albo pomiń rejestrację i wypróbuj z terminala teraz.

Wypróbuj bez klucza API — od razu

5 żąd./min na IP

curl -X POST https://conviro.io/api/developers/demo \
  -H "Content-Type: application/json" \
  -d '{"content": "I want to return my last order"}'

1
Utwórz klucz API
Przejdź do Ustawienia → Klucze API i utwórz klucz z chat:write zakresem. Jest pokazywany raz — zapisz w menedżerze sekretów.
Pobierz klucz API
2
Wyślij wiadomość
POST do /sessions/:id/messages z tokenem Bearer. Użyj istniejącego session id lub utwórz za pomocą POST /sessions.
3
Obsłuż odpowiedź
Otrzymasz requestId, latencyMs, odpowiedź AI, wykryty intent, wynik pewności i sugerowane akcje. Kieruj odpowiedzi o niskiej pewności do człowieka.

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?"}'

Odpowiedź

200 OK · application/json

{
  "requestId": "req_1H8zKj9m2QrT",
  "latencyMs": 412,
  "sessionId": "sess_3f2a9e4b",
  "intent": "refund.request",
  "confidence": 0.94,
  "model": "conviro-resolve-2",
  "message": {
    "id": "msg_a12b7c",
    "role": "assistant",
    "content": "Items bought in the last 30 days can be returned. I've started the return for you.",
    "createdAt": "2026-04-14T10:22:03.412Z"
  },
  "suggestedActions": [
    { "type": "create_ticket", "label": "Open return" }
  ]
}

Playground

Try it right now — no signup

Real HTTP requests to a rate-limited demo endpoint. Every response shows requestId, latencyMs, intent, and confidence.

Live endpoint

Agent demo

POST /api/developers/demo

Symuluj

Cześć 👋 Jestem demem na żywo. Wypróbuj preset, kliknij use-case powyżej lub wpisz własny.

greetingconf 1.00

Co zwróciło API

{
  "intent": "greeting",
  "confidence": 1,
  "model": "conviro-resolve-2",
  "message": {
    "role": "assistant",
    "content": "Cześć 👋 Jestem demem na żywo. Wypróbuj preset, kliknij use-case powyżej lub wpisz własny."
  }
}

Demo-endpoint ma limit 5 req/min per IP. Prawdziwy klucz API otrzymuje domyślnie 60 rpm (konfigurowalne).

Przypadki użycia

Co zespoły naprawdę budują

Kliknij dowolną kartę, aby uruchomić ją na żywo w playground — zobaczysz prawdziwą odpowiedź API w mniej niż sekundę.

Referencja

Powierzchnia API

Endpointy, których będziesz używać najczęściej. Bazowy URL: https://api.conviro.io/v1/api

Pełna dokumentacja

Metoda	Ścieżka	Wymagany scope	Opis
POST	/sessions	`chat:write`	Create a new chat session
GET	/sessions/:id	`chat:read`	Retrieve a session with its messages
POST	/sessions/:id/messages	`chat:write`	Send a message and get AI response
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 a workspace analytics summary
POST	/webhooks	`webhooks:write`	Register a webhook endpoint

chat:readRead sessions and messages

chat:writeCreate sessions and send messages

kb:readRead knowledge base items

kb:writeCreate and delete knowledge base items

analytics:readRead analytics data

webhooks:writeManage webhook endpoints

SDK

Biblioteki i klienci

Wdrażamy oficjalne SDK etapowo. REST API jest małe, stabilne i łatwe do owinięcia — nie musisz czekać.

Node.js / TypeScript

Oficjalne · wkrótce

// @conviro/sdk — in private beta. The REST API
// already works great with fetch/axios today.

PHP

Oficjalne · wkrótce

// composer require conviro/sdk — in private beta.
// Use the cURL example below in the meantime.

Python

Społeczność

# No official SDK yet — the REST API is small enough
# that plain `requests` or `httpx` works well.

Go, Ruby, C#

Użyj REST API bezpośrednio

// No SDK — any HTTP client works. The auth header
// is the only thing you need.

Browse the cookbook WooCommerce pluginWorking snippets for embeds, webhooks, CRM bridges, and platform plugins.

Błędy

Przewidywalne formaty błędów

Każda odpowiedź inna niż 2xx używa tej samej koperty JSON. Dołącz requestId gdy kontaktujesz się ze wsparciem.

Status	Nazwa	Kiedy występuje
400	Bad Request	The request body or parameters are invalid.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	API key is valid but lacks the required scope.
404	Not Found	The requested resource does not exist.
429	Too Many Requests	Rate limit exceeded. Respect the Retry-After header.
500	Server Error	Something went wrong on our side. Retry with backoff.

Treść odpowiedzi

application/json

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key is missing or invalid.",
  "requestId": "req_1H8z...",
  "docsUrl": "https://conviro.io/developers#errors"
}

Przy 429 przestrzegaj Retry-After . Przy 5xx ponów z wykładniczym backoffem do trzech prób.

Webhooki

Zdarzenia w czasie rzeczywistym, zweryfikowane

Każdą dostawę podpisujemy HMAC-SHA256. Nieudane dostawy są ponawiane trzy razy z wykładniczym backoffem. Wyłącznik obwodu izoluje wielokrotnie zawodzące endpointy na 60s.

Zdarzenia

session.startedA new chat session is created
session.closedA chat session is closed
session.escalatedA session is handed off to a human agent
message.newA new message is sent in a session
lead.capturedA lead is captured from a chat
handoff.requestedA visitor requests a human agent
csat.submittedA CSAT rating is submitted
ticket.createdA support ticket is created
ticket.resolvedA support ticket is resolved
ai.failedAI response generation failed

Payload

POST your-endpoint · application/json

{
  "event": "session.closed",
  "deliveryId": "whk_4T2u...",
  "timestamp": "2026-04-14T10:22:03.412Z",
  "data": {
    "sessionId": "sess_3f2a...",
    "chatbotId": "bot_123",
    "visitorId": "v_789",
    "csatScore": 5,
    "messageCount": 12
  }
}

Zweryfikuj podpis

node.js

// Node.js — HMAC verification
import crypto from 'crypto';

const signature = req.headers['x-webhook-signature'];
const body = JSON.stringify(req.body);

const expected = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(body)
  .digest('hex');

if (signature !== expected) {
  return res.status(401).end();
}

Jak to działa

Jedno wywołanie API, pełny pipeline

Wysyłasz wiadomość — my obsługujemy klasyfikację, retrieval, generowanie i routing. Otrzymujesz jedną odpowiedź ze wszystkim, co potrzebne do podjęcia decyzji.

Odwiedzający
Wysyła wiadomość
Klasyfikuj
Intent + pewność
Wiedza
Pobierz z bazy wiedzy
Generuj
Odpowiedź + sugerowane akcje
Eskalacja (może)
Niska pewność → człowiek

Typowe opóźnienie: ~450ms p50
Rate limit: 60 rpm na klucz · konfigurowalne
Bezpieczne ponowienia: Idempotentne ponowienia · backoff webhooka

Gdy jesteś gotowy

Twoje pierwsze wywołanie API jest 60 sekund stąd

Utwórz klucz API, skopiuj snippet szybkiego startu, zobacz prawdziwą odpowiedź. Darmowy tier zawiera wystarczająco wywołań do budowania i testowania.

Pobierz klucz API Otwórz panel

Wdróż agenta wsparcia AI w 5 minut

Twoje pierwsze udane żądanie

Utwórz klucz API

Wyślij wiadomość

Obsłuż odpowiedź