Conviro API · v1 · stable

Lancez un agent IA en 5 minutes

Une API REST et des webhooks pour résoudre les tickets, capturer des leads et passer à un humain — avec votre propre base de connaissances, sans avoir à construire l'orchestration.

Commencer Référence API Obtenir une clé API

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

Démarrage rapide

Votre première requête réussie

Trois étapes. À copier-coller. Vous verrez une vraie réponse IA en soixante secondes — ou sautez l'inscription et essayez depuis votre terminal dès maintenant.

Essayez sans clé API — tout de suite

5 req/min par 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
Créez une clé API
Allez dans Paramètres → Clés API et créez une clé avec le chat:write scope. Il est affiché une seule fois — stockez-le dans votre gestionnaire de secrets.
Obtenir une clé API
2
Envoyez un message
POST sur /sessions/:id/messages avec un Bearer token. Utilisez votre session id existante ou créez-en un avec POST /sessions.
3
Traitez la réponse
Vous recevez requestId, latencyMs, la réponse IA, l'intent détecté, un score de confiance et les actions suggérées. Routez les réponses à faible confiance vers un humain.

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

Réponse

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 démo

POST /api/developers/demo

Simuler

Salut 👋 Je suis une démo en direct. Essayez un preset, cliquez sur un cas d'usage ou tapez le vôtre.

greetingconf 1.00

Ce que l'API a retourné

{
  "intent": "greeting",
  "confidence": 1,
  "model": "conviro-resolve-2",
  "message": {
    "role": "assistant",
    "content": "Salut 👋 Je suis une démo en direct. Essayez un preset, cliquez sur un cas d'usage ou tapez le vôtre."
  }
}

L'endpoint démo a un rate limit de 5 req/min per IP. Une vraie clé API obtient 60 rpm par défaut (configurable).

Cas d'usage

Ce que les équipes construisent vraiment

Cliquez sur une carte pour l'exécuter en direct dans le playground — vous verrez la vraie réponse API en moins d'une seconde.

Référence

Surface API

Les endpoints que vous utiliserez le plus. URL de base : https://api.conviro.io/v1/api

Référence complète

Méthode	Chemin	Scope requis	Description
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

SDKs

Bibliothèques et clients

Nous publions les SDKs officiels par phases. L'API REST est petite, stable et facile à wrapper — pas besoin d'attendre.

Node.js / TypeScript

Officiel · bientôt disponible

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

PHP

Officiel · bientôt disponible

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

Python

Communauté

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

Go, Ruby, C#

Utilisez l'API REST directement

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

Erreurs

Formats d'erreur prévisibles

Chaque réponse non-2xx utilise la même enveloppe JSON. Incluez requestId lorsque vous contactez le support.

Statut	Nom	Quand cela arrive
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.

Corps de la réponse

application/json

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

En 429, respectez l'en-tête Retry-After . En 5xx, réessayez avec backoff exponentiel jusqu'à trois fois.

Webhooks

Événements en temps réel, vérifiés

Nous signons chaque livraison avec HMAC-SHA256. Les livraisons échouées sont retentées trois fois avec backoff exponentiel. Un circuit breaker met en quarantaine les endpoints répétitivement défaillants pendant 60s.

Événements

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

Vérifier la signature

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

Comment ça marche

Un appel API, un pipeline complet

Vous postez un message — nous gérons classification, retrieval, génération et routage. Vous recevez une seule réponse avec tout ce qu'il faut pour décider la suite.

Visiteur
Envoie un message
Classifier
Intent + confiance
Connaissances
Récupérer depuis votre KB
Générer
Réponse + actions suggérées
Escalader (peut-être)
Faible confiance → humain

Latence typique: ~450ms p50
Rate limit: 60 rpm par clé · configurable
Retry-safe: Retries idempotents · backoff webhook

Quand vous êtes prêt

Votre premier appel API est à 60 secondes

Créez une clé API, copiez le snippet de démarrage rapide, voyez une vraie réponse. Le tier gratuit inclut assez d'appels pour construire et tester.

Obtenir une clé API Ouvrir le tableau de bord

Lancez un agent IA en 5 minutes

Votre première requête réussie

Créez une clé API

Envoyez un message

Traitez la réponse