Conviro API · v1 · estable

Lanza un agente de soporte IA en 5 minutos

Una API REST y webhooks para resolver tickets, capturar leads y entregar a humanos — respaldado por tu propia base de conocimiento, sin que tengas que construir la orquestación.

Empezar a construir Referencia API Obtener clave API

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

Inicio rápido

Tu primera petición exitosa

Tres pasos. Para copiar y pegar. Verás una respuesta IA real en sesenta segundos — o sáltate el registro y pruébalo desde tu terminal ahora.

Pruébalo sin clave API — ahora mismo

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
Crea una clave API
Ve a Configuración → Claves API y crea una clave con el chat:write scope. Se muestra una sola vez — guárdalo en tu gestor de secretos.
Obtener clave API
2
Envía un mensaje
POST a /sessions/:id/messages con un Bearer token. Usa tu session id existente o créala primero con POST /sessions.
3
Maneja la respuesta
Recibes requestId, latencyMs, la respuesta IA, el intent detectado, una puntuación de confianza y acciones sugeridas. Enruta respuestas con baja confianza a un 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?"}'

Respuesta

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

Hola 👋 Soy una demo en vivo. Prueba un preset, haz clic en un caso de uso o escribe el tuyo.

greetingconf 1.00

Lo que devolvió la API

{
  "intent": "greeting",
  "confidence": 1,
  "model": "conviro-resolve-2",
  "message": {
    "role": "assistant",
    "content": "Hola 👋 Soy una demo en vivo. Prueba un preset, haz clic en un caso de uso o escribe el tuyo."
  }
}

El endpoint demo tiene un límite de 5 req/min per IP. Una clave API real obtiene 60 rpm por defecto (configurable).

Casos de uso

Lo que los equipos realmente construyen

Haz clic en cualquier tarjeta para ejecutarla en vivo en el playground — verás la respuesta real de la API en menos de un segundo.

Referencia

Superficie API

Los endpoints que más usarás. URL base: https://api.conviro.io/v1/api

Referencia completa

Método	Ruta	Scope requerido	Descripción
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

Librerías y clientes

Estamos lanzando SDKs oficiales por fases. La API REST es pequeña, estable y fácil de envolver — no tienes que esperar.

Node.js / TypeScript

Oficial · próximamente

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

PHP

Oficial · próximamente

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

Python

Comunidad

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

Go, Ruby, C#

Usa la API REST directamente

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

Errores

Formatos de error predecibles

Cada respuesta no 2xx usa el mismo envelope JSON. Incluye requestId cuando contactes con soporte.

Estado	Nombre	Cuándo ocurre
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.

Cuerpo de respuesta

application/json

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

En 429, respeta el header Retry-After . En 5xx, reintenta con backoff exponencial hasta tres veces.

Webhooks

Eventos en tiempo real, verificados

Firmamos cada entrega con HMAC-SHA256. Las entregas fallidas se reintentan tres veces con backoff exponencial. Un circuit breaker pone en cuarentena los endpoints que fallan 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
  }
}

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

Cómo funciona

Una llamada API, un pipeline completo

Tú envías un mensaje — nosotros gestionamos clasificación, retrieval, generación y enrutamiento. Recibes una sola respuesta con todo lo necesario para decidir qué hacer.

Visitante
Envía un mensaje
Clasificar
Intent + confianza
Conocimiento
Recuperar de tu KB
Generar
Respuesta + acciones sugeridas
Escalar (quizá)
Baja confianza → humano

Latencia típica: ~450ms p50
Rate limit: 60 rpm por clave · configurable
Retry-safe: Reintentos idempotentes · backoff de webhook

Cuando estés listo

Tu primera llamada API está a 60 segundos

Crea una clave API, copia el snippet de inicio rápido y verás una respuesta real. El plan gratuito incluye suficientes llamadas para construir y probar.

Obtener clave API Abrir panel

Lanza un agente de soporte IA en 5 minutos

Tu primera petición exitosa

Crea una clave API

Envía un mensaje

Maneja la respuesta