Presiona Enter.
Obtén tus datos.

Inicio rápido

Tres pasos desde cero hasta la primera respuesta. Cada solicitud está vinculada a un widget y se autentica con un token de portador.

1. Emitir una fichaPanel → Tokens de API: un nombre, una caducidad opcional y los alcances que necesita. Un token pertenece exactamente a un widget. El token de texto plano se muestra una vez; Smartbtn almacena sólo un hash unidireccional, por lo que un token perdido no se puede recuperar, sólo se puede revocar y volver a emitir.
2. Activar la API del widgetEn la configuración del widget, active «Permitir API de widget (JS y REST)». Emitir un token no activa este interruptor por usted.
3. Enviar la primera solicitudEl token solo va al encabezado Autorización, nunca a la URL.

# listar los chats del widget
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · paginación del cursor
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — en la última página
}

Autenticación

Tres caminos, según quién llame a quién. El acceso es denegado de forma predeterminada: sin alcance, sin llamada.

El cambio que la gente olvida

«Permitir API de widget (JS y REST)» en la configuración del widget abre tanto la API REST como la API JS del widget. La emisión de un token no lo habilita. Los alcances de una clave existente se pueden editar en el panel (tokens de API → clave → Editar alcances) sin volver a emitirla: las integraciones siguen funcionando.

Preajustes

Alcances

53 alcances de ruta, más uno condicional y otro reservado. Una solicitud tiene éxito solo si el token contiene el alcance de la ruta (o una alternativa enumerada).

Puntos finales

Toda la superficie pública en una sola lista. Filtre por recurso, busque por ruta, haga clic en una fila para copiar un rizo listo.

Las rutas son relativas a https://smartbtn.me/api. Las escrituras necesitan Content‑Type: application/json y X‑Smartbtn‑Idempotency‑Key. El grupo compat es una capa de compatibilidad para equipos que se mudan desde otra plataforma de chat.

Ganchos web

Un POST JSON firmado en su URL cada vez que ocurre un evento de suscripción. Administre las suscripciones a través de /v1/webhook‑subscriptions o en el panel de control.

{
  "id": "evt_01JAB3K9Q7",
  "type": "ticket.created",
  "data": {
    "button_guid": "b_3f9c2e",
    "ticket_number": 10482,
    "chat_id": 48211,
    "client_id": 9134,
    "reason": "human_request",
    "priority": "high",
    "sla_hours": 4,
    "source": "chat",
    "created_at": "2026-10-17T10:15:00+03:00"
  }
}

encabezados de entrega

Verificación de firma

HMAC‑SHA256 del cuerpo sin formato (bytes tal como se recibieron, antes del análisis JSON) con su secreto de punto final; comparar en tiempo constante. El secreto se muestra una vez, cuando se crea la suscripción; gírelo con POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · Por ejemplo, el secreto es un marcador de posición.
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=v1:' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// PHP
$expected = 'sha256=v1:' . hash_hmac('sha256', file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SMARTBTN_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

Reintentos y orden

• Hasta 4 intentos (el primer envío más 3 reintentos), retroceso min(60, 2^attempt × 5) s: aproximadamente 10, 20, 40 s.
• No 2xx o un tiempo de espera cuentan como un intento fallido. Las entregas fallidas se pueden reenviar con POST /v1/webhook‑subscriptions/{id}/redeliver: la misma clave de idempotencia, nueva identificación de entrega.
• La entrega se realiza al menos una vez y no se realiza pedido. Las cargas útiles son mínimas: identificaciones, no registros completos; obtener detalles a través de la API REST.

JS API

Pase lo que ya sabe sobre el visitante directamente al agente. Solo se aceptan llamadas desde el dominio establecido en la configuración del widget.

smartbtn_widget_api.setContactInfo(info)

Establece los datos de contacto del visitante. El agente lo ve como si el visitante hubiera completado el formulario de introducción. El nombre, el teléfono y el correo electrónico juegan un papel especial en Smartbtn, por lo que se utiliza un método independiente.

Smartbtn_api.setClientInfo({
  name: "Alex Morgan",
  email: "email@example.com",
  phone: "+17584987855",
  description: "Description text"
});

smartbtn_widget_api.setCustomData(fields)

Cualquier dato adicional para el panel de información a la derecha de la aplicación del agente. Llámalo tantas veces como quieras: en un cuadro de diálogo abierto, el panel se actualiza en tiempo real. Los campos se muestran en orden de matriz.

Smartbtn_api.setClientCustomData([
  { title: "Order", content: "#10482 · 3 items", link: "https://shop.example/orders/10482" },
  { title: "Actions", content: "Open customer profile", link: "https://crm.example/c/9134" }
]);

smartbtn_widget_api.setSkin(skin, opts) · open() · close()

Cambie el tema del widget sobre la marcha sin recargar la página (classic, minimal, capsule, liquid) o controle la ventana de chat mediante programación. Para una personalización permanente por proyecto, pase los mismos campos a PATCH /v1/widget/settings.

// JS API · cambiar la máscara en la página en tiempo real
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Respuestas en ~1 s" });

// REST API · PATCH /v1/widget/settings (alcance widget:write)
{
  "skin": "minimal",
  "widget_header_align": "center",
  "widget_show_operator_avatars": false,
  "widget_show_tabs_bar": false,
  "chat_bg": "#FAF8F5",
  "capsule_title": "Smartbtn AI",
  "capsule_subtitle": "En línea 24 horas al día, 7 días a la semana"
}

Support‑agent API

Un agente de soporte automatizado trabaja en la cola de tickets y en los chats con los clientes: toma una conversación, responde como su operador de soporte humano y cierra el ticket. Apagado hasta que el propietario del widget lo active.

curl -X POST https://smartbtn.me/api/v1/support/chats/48211/reply \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $(uuidgen)" \
  -d '{"text":"Listo, el acceso ha sido restaurado."}'

API de IA

Todo lo que hace la sección de IA del tablero: asistentes, tus propias claves de proveedor, base de conocimientos, autoaprendizaje con reversión, deseos, problemas, señales de demanda y un asistente dentro de tu aplicación.

Límites de tarifas

Por token, dos contadores: las lecturas y las escrituras se cuentan por separado, por lo que el sondeo nunca consume el presupuesto de escritura.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "status": 429, "title": "Too Many Requests", "reason": "rate_limited" }

/v1/ai/assistant/tickets/status y /v1/ai/assistant/account‑link tienen sus propios contadores; la API del agente de soporte puede tener una anulación por widget.

Errores

Cada error es RFC‑7807 application/problem+json: un estado y motivo legibles por máquina, un detalle legible por humanos.

HTTP/1.1 403 · Content-Type: application/problem+json
{
  "type": "https://smartbtn.me/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Token lacks scope chats:write.",
  "required_scopes": [
    "chats:write"
  ],
  "hint": "Dashboard → API tokens → key → Edit scopes"
}

El cuerpo nombra los ámbitos requeridos y dónde otorgarlos. No es necesario volver a emitir la clave.

Idempotencia

Las redes fallan. Una clave hace que un reintento de escritura sea seguro: la misma operación nunca se aplica dos veces.

• Envíe X‑Smartbtn‑Idempotency‑Key en cada POST / PATCH / PUT / DELETE: un nuevo UUID para una nueva operación, la misma clave para un reintento de la misma.
• Operaciones marcadas x‑idempotencia: requerida en OpenAPI: sin clave → 400, la clave se reutiliza dentro de las 24 horas → 409 (no es un éxito en caché).
• ¿No estás seguro de que haya pasado? Lea el estado primero. Nunca cambie la clave automáticamente; Respete el reintento después.
• Un 502 de un proveedor ascendente libera la clave; vuelva a intentarlo con la misma clave.

KEY=$(uuidgen)
curl -X PATCH https://smartbtn.me/api/v1/widget/settings \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $KEY" \
  -d '{"language":"ru"}'
# error de red? repetir con la misma $KEY

Changelog

Cambios en la API pública y los webhooks en 2026. Todo lo siguiente es aditivo y permanece en v1.

complemento de WordPress

El widget en un sitio de WordPress sin tocar el código del tema.

Ejemplos de código

Enumere todos los chats con actividad desde su última encuesta, siguiendo el cursor hasta el final.

# primera pagina
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "updated_since=2026-10-17T09:00:00+03:00"

# next — con next_cursor de la respuesta
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"