API Documentation

Integrá Botssy con tus sistemas. Accedé a conversaciones, clientes, mensajes y más a través de nuestra API REST.

Base URL: https://app.botssy.com/api/v1

Overview

La API de Botssy te permite acceder y gestionar los datos de tu cuenta de forma programática. Podés listar conversaciones, enviar mensajes, gestionar clientes, y recibir eventos en tiempo real mediante webhooks.

REST API

JSON sobre HTTPS, endpoints intuitivos y paginados

API Keys

Autenticación con Bearer token y permisos granulares

Webhooks

Eventos en tiempo real firmados con HMAC-SHA256

Autenticación

Todas las requests requieren un API key en el header Authorization. Los keys se crean desde el dashboard en Settings → API.

bash

curl -X GET https://app.botssy.com/api/v1/conversations \
  -H "Authorization: Bearer bsk_live_tu_api_key_aqui"

Formato del API key:

bsk_live_ — Producción
bsk_test_ — Testing
El key solo se muestra una vez al crearlo. Guardalo de forma segura.

Permisos

Cada API key tiene permisos granulares. Asigná solo los que necesitás:

read:conversationswrite:conversationsread:messageswrite:messagesread:customerswrite:customersread:botsread:agentsread:analyticsread:webhooks

Rate Limits

Los límites se aplican por API key y se resetean diariamente a las 00:00 UTC.

Plan	Requests/día
Free	Sin acceso API
Starter	1,000
Growth	5,000
Pro	10,000
Business	50,000

Al exceder el límite, la API responde con HTTP 429.

Conversations

GET/conversationsread:conversations

Listar conversaciones

Query params: status, limit (max 100), offset

json

{
  "data": [
    {
      "id": 123,
      "userPhone": "+5491162328014",
      "channel": "whatsapp",
      "status": "in_progress",
      "createdAt": "2026-03-25T10:00:00Z",
      "customer": {
        "id": 456,
        "name": "Juan Pérez",
        "phone": "+5491162328014"
      },
      "Bot": { "id": 1, "name": "Soporte" },
      "_count": { "messages": 12 }
    }
  ],
  "pagination": { "total": 150, "limit": 50, "offset": 0 }
}

GET/conversations/:idread:conversations

Detalle de conversación

GET/conversations/:id/messagesread:messages

Mensajes de una conversación

Query params: limit (max 500), offset

Messages

POST/conversations/:id/messageswrite:messages

Enviar mensaje

bash

curl -X POST https://app.botssy.com/api/v1/conversations/123/messages \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "Hola, ¿en qué puedo ayudarte?"}'

json

{
  "id": 1003,
  "conversationId": 123,
  "role": "assistant",
  "content": "Hola, ¿en qué puedo ayudarte?",
  "timestamp": "2026-03-25T10:06:00Z",
  "mediaId": null
}

Customers

GET/customersread:customers

Listar clientes

Query params: search (nombre, teléfono o email), limit, offset

json

{
  "data": [
    {
      "id": 456,
      "name": "Juan Pérez",
      "phone": "+5491162328014",
      "email": "juan@ejemplo.com",
      "tags": ["vip"],
      "company": "Empresa SRL",
      "notes": "Cliente preferencial",
      "customFields": { "plan": "premium" },
      "lastMessage": "2026-03-25T10:00:00Z",
      "acceptsMarketing": true,
      "_count": { "conversations": 8 }
    }
  ],
  "pagination": { "total": 512, "limit": 50, "offset": 0 }
}

GET/customers/:idread:customers

Detalle de cliente

POST/customerswrite:customers

Crear cliente

bash

curl -X POST https://app.botssy.com/api/v1/customers \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "María García", "phone": "+5491155667788", "email": "maria@ejemplo.com"}'

PATCH/customers/:idwrite:customers

Actualizar cliente

Bots & Agents

GET/botsread:bots

Listar bots

GET/bots/:idread:bots

Detalle de bot (incluye agentes y canales)

GET/agentsread:agents

Listar agentes

json

[
  {
    "id": 1,
    "name": "Soporte General",
    "description": "Atiende consultas generales",
    "isActive": true,
    "bots": [{ "id": 1, "name": "Bot Principal" }]
  }
]

Analytics

GET/analytics/overviewread:analytics

Métricas generales

json

{
  "totalConversations": 500,
  "conversationsThisMonth": 45,
  "totalCustomers": 512,
  "activeConversations": 8,
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-25T14:30:00Z"
  }
}

GET/status

Estado de la API y tu cuenta

Webhooks

Recibí eventos en tiempo real cuando algo sucede en tu cuenta. Configurá webhooks desde Settings → API → Webhooks o por API.

Seguridad

Cada webhook incluye headers de seguridad para verificar la autenticidad:

Header	Descripción
`X-Botssy-Signature`	HMAC-SHA256 del payload
`X-Botssy-Timestamp`	Timestamp Unix en ms
`X-Botssy-Event`	Nombre del evento

Verificar firma

javascript

const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  const data = timestamp + "." + JSON.stringify(payload);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(data)
    .digest('hex');
  return signature === expected;
}

// En tu endpoint:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-botssy-signature'];
  const ts = req.headers['x-botssy-timestamp'];

  if (!verifyWebhook(req.body, sig, ts, 'whsec_tu_secreto')) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;
  console.log(`Event: ${event}`, data);
  res.json({ ok: true });
});

Formato del payload

json

{
  "event": "message.received",
  "timestamp": 1711353600000,
  "data": {
    "id": 1001,
    "conversationId": 123,
    "role": "user",
    "content": "Hola, necesito ayuda",
    "timestamp": "2026-03-25T10:05:00Z"
  }
}

Webhook Events

Evento	Descripción	Payload
`conversation.created`	Nueva conversación iniciada	Conversation
`conversation.updated`	Cambio de estado en conversación	Conversation
`conversation.resolved`	Conversación marcada como resuelta	Conversation
`message.received`	Mensaje recibido del cliente	Message
`message.sent`	Mensaje enviado (bot u operador)	Message
`customer.created`	Nuevo cliente creado	Customer
`customer.updated`	Datos del cliente actualizados	Customer
`operator.joined`	Operador se unió a conversación	operatorId, conversationId
`operator.left`	Operador dejó conversación	operatorId, conversationId

Gestión de Webhooks por API

GET/api-management/webhooks

Listar webhooks

GET/api-management/webhooks/events

Eventos disponibles

POST/api-management/webhooks

Crear webhook

bash

curl -X POST https://app.botssy.com/api-management/webhooks \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi Webhook",
    "url": "https://mi-servidor.com/webhook",
    "events": ["message.received", "conversation.created"]
  }'

PATCH/api-management/webhooks/:id

Actualizar webhook

POST/api-management/webhooks/:id/toggle

Activar/desactivar

POST/api-management/webhooks/:id/test

Enviar webhook de prueba

GET/api-management/webhooks/:id/logs

Ver logs de entregas

POST/api-management/webhooks/:id/regenerate-secret

Regenerar secreto

DELETE/api-management/webhooks/:id

Eliminar webhook

Errores

Código	Significado
`400`	Bad Request — Parámetros inválidos
`401`	Unauthorized — API key faltante, inválida o expirada
`403`	Forbidden — Sin permisos o plan sin acceso API
`404`	Not Found — Recurso no encontrado
`429`	Too Many Requests — Rate limit excedido
`500`	Internal Server Error — Error del servidor

json

{
  "statusCode": 403,
  "message": "Insufficient API permissions. Required: read:conversations"
}

SDKs & Swagger

Explorá la API interactivamente con Swagger o integrá con tu stack preferido.

Swagger / OpenAPI

Documentación interactiva con todos los endpoints. Probá requests en vivo.

app.botssy.com/api

Ejemplo rápido

Obtené tus conversaciones en 3 líneas:

javascript

const res = await fetch('https://app.botssy.com/api/v1/conversations', {
  headers: { 'Authorization': 'Bearer bsk_live_...' }
});
const { data } = await res.json();

¿Necesitás ayuda? hello@botssy.com