Conviro API · v1 · stabiel

Lever een AI-supportagent in 5 minuten

Een REST API en webhooks voor het oplossen van tickets, leads vastleggen en doorverbinden naar mensen — ondersteund door je eigen knowledge base, zonder zelf de orchestratie te bouwen.

Beginnen met bouwen API-referentie API-sleutel ophalen

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

Snelstart

Je eerste succesvolle verzoek

Drie stappen. Plak-en-klaar. Je ziet binnen zestig seconden een echt AI-antwoord — of sla de signup over en probeer het nu vanuit je terminal.

Probeer zonder API-sleutel — nu meteen

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
Maak een API-sleutel
Ga naar Instellingen → API-sleutels en maak een sleutel met de chat:write scope. Het wordt eenmalig getoond — bewaar het in je secret manager.
API-sleutel ophalen
2
Stuur een bericht
POST naar /sessions/:id/messages met een Bearer token. Gebruik je bestaande session id of maak er eerst een met POST /sessions.
3
Behandel het antwoord
Je krijgt requestId, latencyMs, het AI-antwoord, de gedetecteerde intent, een confidence-score en voorgestelde acties. Routeer antwoorden met lage confidence naar een mens.

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

Antwoord

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

Demo-agent

POST /api/developers/demo

Simuleren

Hoi 👋 Ik ben een live demo. Probeer een preset, klik op een use-case hierboven of typ je eigen tekst.

greetingconf 1.00

Wat de API teruggaf

{
  "intent": "greeting",
  "confidence": 1,
  "model": "conviro-resolve-2",
  "message": {
    "role": "assistant",
    "content": "Hoi 👋 Ik ben een live demo. Probeer een preset, klik op een use-case hierboven of typ je eigen tekst."
  }
}

Het demo-endpoint heeft een rate limit van 5 req/min per IP. Een echte API-sleutel krijgt standaard 60 rpm (configureerbaar).

Use cases

Wat teams daadwerkelijk bouwen

Klik op een kaart om hem live in de playground uit te voeren — je ziet het echte API-antwoord binnen een seconde.

Referentie

API-oppervlak

De endpoints die je het meest zult gebruiken. Basis-URL: https://api.conviro.io/v1/api

Volledige referentie

Methode	Pad	Vereiste scope	Beschrijving
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

Bibliotheken & clients

We brengen officiële SDKs in fasen uit. De REST API is klein, stabiel en makkelijk te wrappen — je hoeft niet te wachten.

Node.js / TypeScript

Officieel · binnenkort

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

PHP

Officieel · binnenkort

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

Gebruik de REST API direct

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

Fouten

Voorspelbare foutformaten

Elke niet-2xx-respons gebruikt dezelfde JSON-envelope. Voeg requestId toe wanneer je contact opneemt met support.

Status	Naam	Wanneer het gebeurt
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.

Responsbody

application/json

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

Bij 429, respecteer de Retry-After -header. Bij 5xx opnieuw proberen met exponentiële backoff tot drie pogingen.

Webhooks

Realtime events, geverifieerd

We tekenen elke aflevering met HMAC-SHA256. Mislukte afleveringen worden drie keer geprobeerd met exponentiële backoff. Een circuit breaker zet herhaaldelijk falende endpoints 60s in quarantaine.

Events

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

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

Hoe het werkt

Eén API-call, een complete pipeline

Jij post een bericht — wij regelen classificatie, retrieval, generatie en routing. Je krijgt één antwoord met alles wat je nodig hebt om te beslissen wat er gebeurt.

Bezoeker
Stuurt een bericht
Classificeren
Intent + confidence
Kennis
Ophalen uit je KB
Genereren
Antwoord + voorgestelde acties
Escaleren (misschien)
Lage confidence → mens

Typische latentie: ~450ms p50
Rate limit: 60 rpm per sleutel · configureerbaar
Retry-safe: Idempotente retries · webhook back-off

Wanneer je klaar bent

Je eerste API-call is 60 seconden weg

Maak een API-sleutel, kopieer het snelstart-snippet, zie een echt antwoord. De gratis tier bevat genoeg calls om te bouwen en testen.

API-sleutel ophalen Dashboard openen

Lever een AI-supportagent in 5 minuten

Je eerste succesvolle verzoek

Maak een API-sleutel

Stuur een bericht

Behandel het antwoord