Conviro API · v1 · stable

Lancia un agente di supporto IA in 5 minuti

Una API REST e webhook per risolvere ticket, acquisire lead e passare a un umano — supportata dalla tua knowledge base, senza dover costruire l'orchestrazione.

Inizia a costruire Riferimento API Ottieni chiave API

URL base: api.conviro.io/v1
Auth: Bearer token
Risposta: 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": "..." }
}

Avvio rapido

La tua prima richiesta riuscita

Tre passi. Copy-paste. Vedrai una vera risposta IA entro sessanta secondi — oppure salta la registrazione e provalo dal terminale ora.

Prova senza chiave API — subito

5 req/min per 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
Crea una chiave API
Vai a Impostazioni → Chiavi API e crea una chiave con lo chat:write scope. Viene mostrato una sola volta — conservalo nel tuo secret manager.
Ottieni chiave API
2
Invia un messaggio
POST a /sessions/:id/messages con un Bearer token. Usa il tuo session id esistente o creane uno con POST /sessions.
3
Gestisci la risposta
Ricevi requestId, latencyMs, la risposta IA, l'intent rilevato, un punteggio di confidence e azioni suggerite. Instrada le risposte a bassa confidence verso un umano.

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

Risposta

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

Agente demo

POST /api/developers/demo

Simula

Ciao 👋 Sono una demo live. Prova un preset, clicca un use-case sopra o digita il tuo.

greetingconf 1.00

Cosa ha restituito l'API

{
  "intent": "greeting",
  "confidence": 1,
  "model": "conviro-resolve-2",
  "message": {
    "role": "assistant",
    "content": "Ciao 👋 Sono una demo live. Prova un preset, clicca un use-case sopra o digita il tuo."
  }
}

L'endpoint demo ha un rate limit di 5 req/min per IP. Una chiave API reale ottiene 60 rpm di default (configurabile).

Casi d'uso

Cosa costruiscono davvero i team

Clicca su una card per eseguirla nel playground — vedrai la vera risposta API entro un secondo.

Riferimento

Superficie API

Gli endpoint che userai di più. URL base: https://api.conviro.io/v1/api

Riferimento completo

Metodo	Path	Scope richiesto	Descrizione
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

Librerie e client

Stiamo rilasciando SDK ufficiali a fasi. L'API REST è piccola, stabile e facile da wrappare — non devi aspettare.

Node.js / TypeScript

Ufficiale · presto disponibile

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

PHP

Ufficiale · presto disponibile

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

Python

Community

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

Go, Ruby, C#

Usa l'API REST direttamente

// 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.

Errori

Formati di errore prevedibili

Ogni risposta non-2xx usa lo stesso envelope JSON. Includi requestId quando contatti il supporto.

Stato	Nome	Quando si verifica
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.

Corpo della risposta

application/json

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

Su 429, rispetta l'header Retry-After . Su 5xx, riprova con backoff esponenziale fino a tre tentativi.

Webhook

Eventi in tempo reale, verificati

Firmiamo ogni consegna con HMAC-SHA256. Le consegne fallite vengono ritentate tre volte con backoff esponenziale. Un circuit breaker mette in quarantena gli endpoint che falliscono ripetutamente per 60s.

Eventi

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
  }
}

Verifica la firma

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

Come funziona

Una chiamata API, un'intera pipeline

Tu invii un messaggio — noi gestiamo classificazione, retrieval, generazione e routing. Ricevi una singola risposta con tutto ciò che serve per decidere il prossimo passo.

Visitatore
Invia un messaggio
Classifica
Intent + confidence
Conoscenza
Recupera dalla tua KB
Genera
Risposta + azioni suggerite
Escalata (forse)
Bassa confidence → umano

Latenza tipica: ~450ms p50
Rate limit: 60 rpm per chiave · configurabile
Retry-safe: Retry idempotenti · webhook back-off

Quando sei pronto

La tua prima chiamata API è a 60 secondi

Crea una chiave API, copia lo snippet di avvio rapido, vedi una vera risposta. Il tier free include abbastanza chiamate per costruire e testare.

Ottieni chiave API Apri dashboard

Lancia un agente di supporto IA in 5 minuti

La tua prima richiesta riuscita

Crea una chiave API

Invia un messaggio

Gestisci la risposta