Conviro API · v1 · estável

Lance um agente IA em 5 minutos

Uma API REST e webhooks para resolver tickets, capturar leads e transferir para humanos — suportada pela sua base de conhecimento, sem ter de construir a orquestração.

Começar a construir Referência API Obter chave API

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

Início rápido

O seu primeiro pedido bem-sucedido

Três passos. Copy-paste. Verá uma resposta IA real em sessenta segundos — ou salte o registo e teste do terminal agora.

Experimente sem chave API — agora mesmo

5 req/min por 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
Crie uma chave API
Vá a Definições → Chaves API e crie uma chave com o chat:write scope. Mostrado uma única vez — guarde-o no seu secret manager.
Obter chave API
2
Envie uma mensagem
POST para /sessions/:id/messages com um Bearer token. Use o seu session id existente ou crie um primeiro com POST /sessions.
3
Trate da resposta
Recebe requestId, latencyMs, a resposta IA, o intent detetado, uma pontuação de confiança e ações sugeridas. Encaminhe respostas de baixa confiança para um humano.

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

Resposta

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

Simular

Olá 👋 Sou uma demo ao vivo. Experimente um preset, clique num caso de uso acima ou escreva o seu.

greetingconf 1.00

O que a API devolveu

{
  "intent": "greeting",
  "confidence": 1,
  "model": "conviro-resolve-2",
  "message": {
    "role": "assistant",
    "content": "Olá 👋 Sou uma demo ao vivo. Experimente um preset, clique num caso de uso acima ou escreva o seu."
  }
}

O endpoint demo tem rate limit de 5 req/min per IP. Uma chave API real obtém 60 rpm por defeito (configurável).

Casos de uso

O que as equipas realmente constroem

Clique em qualquer cartão para executá-lo ao vivo no playground — verá a resposta API real em menos de um segundo.

Referência

Superfície API

Os endpoints que mais usará. URL base: https://api.conviro.io/v1/api

Referência completa

Método	Path	Scope necessário	Descrição
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

Bibliotecas e clientes

Estamos a lançar SDKs oficiais por fases. A API REST é pequena, estável e fácil de envolver — não tem de esperar.

Node.js / TypeScript

Oficial · em breve

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

PHP

Oficial · em breve

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

Python

Comunidade

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

Go, Ruby, C#

Use a API REST diretamente

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

Erros

Formatos de erro previsíveis

Cada resposta não-2xx usa o mesmo envelope JSON. Inclua requestId quando contactar o suporte.

Estado	Nome	Quando acontece
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 da resposta

application/json

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

Em 429, respeite o cabeçalho Retry-After . Em 5xx, repita com backoff exponencial até três tentativas.

Webhooks

Eventos em tempo real, verificados

Assinamos cada entrega com HMAC-SHA256. As entregas falhadas são repetidas três vezes com backoff exponencial. Um circuit breaker põe em quarentena os endpoints que falham repetidamente durante 60s.

Eventos

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

Verificar a assinatura

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

Como funciona

Uma chamada API, um pipeline completo

Você envia uma mensagem — nós tratamos da classificação, retrieval, geração e encaminhamento. Recebe uma única resposta com tudo o que precisa para decidir o próximo passo.

Visitante
Envia uma mensagem
Classificar
Intent + confiança
Conhecimento
Recuperar da sua KB
Gerar
Resposta + ações sugeridas
Escalar (talvez)
Baixa confiança → humano

Latência típica: ~450ms p50
Rate limit: 60 rpm por chave · configurável
Retry-safe: Retries idempotentes · backoff de webhook

Quando estiver pronto

A sua primeira chamada API está a 60 segundos

Crie uma chave API, copie o snippet de início rápido e veja uma resposta real. O tier gratuito inclui chamadas suficientes para construir e testar.

Obter chave API Abrir painel

Lance um agente IA em 5 minutos

O seu primeiro pedido bem-sucedido

Crie uma chave API

Envie uma mensagem

Trate da resposta