# heysteff API

> API REST de heysteff para mandar mensajes por WhatsApp (API oficial y QR), Instagram, Messenger, SMS y Gmail, sincronizar contactos, crear campañas, disparar flujos, cobrar con links de pago, pedir reseñas y recibir eventos por webhooks firmados. Base: https://app.heysteff.com/api/v1. Autenticación: `Authorization: Bearer sk_live_...`.

## Para agentes de código

- [llms-full.txt](https://app.heysteff.com/api/v1/llms-full.txt): la API completa en texto plano (autenticación, idempotencia, límites, errores, webhooks y cada operación con sus campos). Empieza por aquí.
- [openapi.json](https://app.heysteff.com/api/v1/openapi.json): especificación OpenAPI 3.1, generada desde los mismos schemas que validan la API.
- [AGENTS.md](https://developers.heysteff.com/AGENTS.md): reglas para programar contra la API (manejo de keys, idempotencia, firma de webhooks).
- [Skill de heysteff](https://developers.heysteff.com/skills/heysteff/SKILL.md): skill para Claude Code y otros agentes (API v1, SDK, CLI, MCP, webhooks, sandbox y errores). Instalar: `mkdir -p ~/.claude/skills/heysteff && curl -fsSL https://developers.heysteff.com/skills/heysteff/SKILL.md -o ~/.claude/skills/heysteff/SKILL.md`.
- [Skills instalables](https://developers.heysteff.com/docs/agentes-de-codigo#skill): `heysteff-integrate` (API key, enviar por cualquier canal, webhooks, clientes y links), `heysteff-automate` (flujos, campañas y plantillas) y `heysteff-observe` (entregas de webhooks, reintentos, logs y uso del plan), con scripts sin dependencias. Instalar: `npx skills add heysteff-com/agent-skills`.
- [Plugin para Claude Code](https://developers.heysteff.com/docs/agentes-de-codigo#plugin): MCP con la URL fija, las skills, `/heysteff:setup` y reglas de seguridad. Instalar: `/plugin marketplace add heysteff-com/agent-plugins` y `/plugin install heysteff@heysteff`.
- [install.sh](https://developers.heysteff.com/install.sh): instala la CLI (`curl -fsSL https://developers.heysteff.com/install.sh | bash`); después `heysteff login` abre el navegador para autorizar la CLI y guarda la API key (`heysteff setup` hace lo mismo y manda un mensaje de prueba).

## Documentación

- [heysteff para developers](https://developers.heysteff.com/): qué ofrece la API, cómo conectar tu propia IA, las herramientas (SDK, CLI, MCP, sandbox) y la comparación con la Cloud API de Meta directa.
- [Crear cuenta de developer](https://developers.heysteff.com/console/register): un espacio developer (con el agente de IA apagado hasta que lo enciendas) con un asistente de primeros pasos: sandbox o número, API key, primer mensaje y webhook. Entrar: https://developers.heysteff.com/console/login.

- [Inicio rápido](https://developers.heysteff.com/docs/): crear una API key, mandar el primer mensaje y recibir respuestas con un webhook.
- [Agentes de código y MCP](https://developers.heysteff.com/docs/agentes-de-codigo): pasos con API key, CLI y canal, un prompt listo para Claude Code, Codex o Cursor, cómo conectar tu propia IA (webhook `message:received` → tu modelo → `POST /v1/messages`) y los comandos para conectar el servidor MCP en cada cliente.
- [Autenticación](https://developers.heysteff.com/docs/autenticacion): API keys, scopes, rotación e IPs permitidas.
- [Sandbox](https://developers.heysteff.com/docs/sandbox): probar la API sin conectar un número, con una key `sk_test_` y el número compartido de heysteff.
- [Obtén un número](https://developers.heysteff.com/docs/numero): usar un número de EE. UU. de heysteff, ya verificado, que queda en tu propia cuenta de WhatsApp; Meta te cobra los mensajes con tu tarjeta. Desde tu código: `POST /v1/numbers` reserva uno y devuelve `connect_url` (el alta termina en la ventana de Meta), `GET /v1/numbers` lo lista, `DELETE /v1/numbers/{id}` suelta una reserva y `POST /v1/numbers/{id}/display-name` pide el nombre visible; también `heysteff numbers …` y `client.numbers.*` en el SDK.
- [Clientes y links de conexión](https://developers.heysteff.com/docs/clientes): para un SaaS cuyos clientes conectan su propio WhatsApp, Instagram, Messenger o Gmail. `POST /v1/customers` crea un cliente con tu `external_id`, `POST /v1/customers/{id}/setup-links` devuelve un link de un solo uso (`https://developers.heysteff.com/connect/hsl_…`) donde el cliente conecta UN canal, llega el webhook `customer.channel_connected` y mandas por cuenta de él con `POST /v1/messages` + `customer_id` (y lees solo sus conversaciones con `GET /v1/conversations?customer_id=`); el link se configura (idioma, colores, número propio / coexistencia / número de heysteff para WhatsApp, `reconnect_channel_id`) y hay un solo link activo por cliente y canal; `GET /v1/customers/{id}/usage` da el uso por canal y por día para cobrarle a tu cliente, y `POST /v1/inbox-embeds` (scope `inbox:embed`) crea el token de una bandeja embebible (`developers.heysteff.com/embed/inbox?token=…`) con las conversaciones del espacio, de un canal o de un cliente; también `heysteff customers …`, `client.customers.*`, `client.setupLinks.*` y `client.inboxEmbeds.*` en el SDK y las tools MCP `*_developer_customer`, `get_customer_usage` y `*_inbox_embed`.
- [Precios](https://developers.heysteff.com/precios): Developer Free (USD 0, 2.000 mensajes al mes, 1 número, 1 cliente, sin números extra), Developer (USD 25, 100.000 mensajes al mes, 3 números, hasta 10 clientes con links de conexión, excedente USD 0,002 por mensaje) y Developer Platform (USD 299, 1.000.000 de mensajes al mes, 50 números, clientes ilimitados, excedente USD 0,001 por mensaje, número extra USD 5 al mes). Los tres incluyen el agente de IA: con tu propia key del proveedor, o con un cupo de prueba de 200, 2.000 o 20.000 respuestas al mes; custom tools 2, 10 o ilimitadas; hallazgos en Developer y Developer Platform. Al agotar el cupo de Developer Free, la API responde `402 message_quota_exceeded`.
- [Tipos de mensaje](https://developers.heysteff.com/docs/mensajes): texto, imágenes, audio, video y documentos (subidos con `POST /v1/media`), plantillas de WhatsApp (listadas con `GET /v1/templates`, creadas con `POST /v1/templates` y borradas con `DELETE /v1/templates/{name}`), botones y listas (`content_type: "interactive"`, nativos en WhatsApp Cloud, quick replies en Instagram y Messenger, texto numerado en el resto), ubicaciones, reacciones, el estado de un mensaje (`GET /v1/messages/{id}`) y el recibo de lectura (`POST /v1/messages/{id}/read`).
- [Webhooks](https://developers.heysteff.com/docs/webhooks): crear, editar y borrar webhooks por API (`POST/PATCH/DELETE /v1/webhooks`), eventos (incluidos `message.delivered`, `message.read`, `message.failed`, `channel.connected`, `customer.channel_connected` y los del ciclo de vida: `conversation.created`, `conversation.inactive`, `conversation.ended`, `conversation.assigned`, `conversation.bot_toggled`, `contact.updated`, `contact.opted_out`, `contact.opted_in`, `channel.disconnected`, `channel.reconnected`, `channel.restricted`, `webhook.paused`), sobre de cada entrega, verificación de la firma, `X-Heysteff-Idempotency-Key`, agrupación de mensajes rápidos (`batch`), pausa automática, reintentos y registro de entregas (`GET /v1/webhooks/{id}/deliveries`, reintento con `POST /v1/webhook-deliveries/{id}/retry`) y prueba en local sin túnel con `heysteff listen --forward-to`.
- [WhatsApp Flows](https://developers.heysteff.com/docs/flows): formularios dentro del chat de WhatsApp Cloud. `GET/POST /v1/whatsapp-flows` (listar, crear), `POST /v1/whatsapp-flows/sync` (traerlos de Meta), `PUT /v1/whatsapp-flows/{id}/json` (subir el Flow JSON; responde los `validation_errors` de Meta), `POST /{id}/publish`, `POST /{id}/deprecate`, `DELETE /{id}` (solo borradores), `GET /{id}/preview` (link de vista previa) y `GET /v1/whatsapp-flows/responses`. Se mandan con `POST /v1/messages` y `content_type: "flow"` (solo WhatsApp Cloud; en otro canal 422 `whatsapp_cloud_only`) o con un botón FLOW de plantilla; la respuesta llega en `message:received` con `flow_response: { flow_token, data }` y, con `save_to_contact`, se guarda en el contacto. Scopes `flows:read` y `flows:write`.
- [Llamadas de WhatsApp](https://developers.heysteff.com/docs/llamadas): encender las llamadas de un número y su horario (`GET/PATCH /v1/whatsapp-numbers/{id}/calling`, scopes `calls:read`/`calls:write`), registro de llamadas (`GET /v1/calls`), eventos `call.started`, `call.ended` y `call.missed`, botón de llamar (`content_type: "voice_call"` o botón VOICE_CALL de plantilla) y pedido de permiso (`content_type: "call_permission_request"`). heysteff no contesta llamadas todavía (sin audio WebRTC/SIP).
- [Agente de IA](https://developers.heysteff.com/docs/agente): el agente de heysteff responde en todos los canales con tus instrucciones, archivos de contexto y custom tools. `GET/PATCH /v1/agent` lo enciende y apaga por espacio, canal (`channels`) y cliente (`customers`), y elige proveedor (anthropic, openai, deepseek, openrouter), modelo y temperatura; `PUT /v1/agent/keys` guarda tu key (BYOK). Sin key usa el cupo de prueba del plan; sin key ni cupo no responde y llega `agent.failed` con `ai_quota_exhausted`. Custom tools en `/v1/agent/tools`, hallazgos en `GET /v1/insights`, webhooks `agent.replied`, `agent.handoff`, `agent.failed` e `insight.detected`; también `client.agent.*` e `client.insights.get` en el SDK y las tools MCP `get_developer_agent`, `update_developer_agent`, `delete_developer_ai_key` y `get_developer_insights`.
- [Conecta tu propia IA](https://developers.heysteff.com/docs/conecta-tu-ia): tu modelo contesta con `POST /v1/messages` y, cuando no sabe, pasa la conversación a una persona con `POST /v1/conversations/{id}/escalate`; `bot_paused` en el webhook dice cuándo callar, y `POST /v1/conversations/{id}/bot` y `/resolve` la devuelven.
- [Errores y límites](https://developers.heysteff.com/docs/errores-y-limites): formato de error, límite de solicitudes, idempotencia y paginación.
- [SDK de TypeScript](https://developers.heysteff.com/docs/sdk): `@heysteff/sdk` 0.7.0 para Node, Deno, Bun y workers (ESM y CommonJS), con reintentos idempotentes, paginación, `createWebhookHandler` (receptor de webhooks tipado en una línea), `heysteff.events.stream()` (eventos en vivo) y errores con `category` y `retryable`.
- [Migrar desde otro proveedor](https://developers.heysteff.com/docs/migrar): equivalencias de endpoints, webhooks, firmas y conceptos desde Twilio, 360dialog, YCloud y Kapso, con los pasos para cambiarte.
- [Compatible con Meta](https://developers.heysteff.com/docs/meta-compatible): código hecho para la Cloud API de WhatsApp de Meta funciona cambiando solo la URL base a `https://app.heysteff.com/api/meta/whatsapp/v21.0` (cualquier versión `v<n>.<n>`) y el token por la API key (`Authorization: Bearer sk_live_…`). Cubre `POST /{phone_number_id}/messages` (todos los tipos, `status: "read"` con `typing_indicator`), `POST /{phone_number_id}/media`, `GET`/`DELETE /{media_id}`, `GET /{phone_number_id}`, el perfil de empresa y `GET/POST/DELETE /{waba_id}/message_templates`, con errores en la forma de Graph. `messages[0].id` es el id de heysteff (los estados traen el mismo). Webhooks con `format: "meta"` reciben el payload de la Cloud API firmado con `X-Hub-Signature-256` y el secreto del webhook. Estas rutas no están en openapi.json: su contrato es el de Meta.
- [CLI](https://developers.heysteff.com/docs/cli): `@heysteff/cli` 0.7.0, el comando `heysteff` (se instala con `install.sh`; `heysteff login` inicia sesión por el navegador y `heysteff login --key` pega una key) para mandar mensajes, listar conversaciones y plantillas, subir archivos, ver los eventos del espacio en vivo y reenviarlos firmados a tu servidor local sin túnel (`heysteff listen --forward-to`) y mandar un aviso firmado de ejemplo (`heysteff webhooks trigger`). También documenta los endpoints del inicio de sesión por el navegador (`POST /api/cli/device/code` y `POST /api/cli/device/token`) y el formato de `GET /v1/events/stream`.
- [Plantillas](https://developers.heysteff.com/docs/#plantillas): `npm create heysteff@latest` crea un proyecto listo con tu key en `.env.local`: `inbox` (bandeja omnicanal Next.js con contraseña, ventana de 24 h, plantillas, archivos, botones, leído, tomar/devolver al bot y modo por cliente con `HEYSTEFF_CUSTOMER_ID`; https://github.com/heysteff-com/omnichannel-inbox), `agent` (agente de IA con el AI SDK que recibe `message:received` firmado, contesta con Claude, respeta `bot_paused` y deriva con `escalate`; https://github.com/heysteff-com/ai-agent-starter) y `send` (un archivo que manda un mensaje). Código MIT.
- [Integraciones](https://developers.heysteff.com/docs/integraciones): `@heysteff/chat-adapter` (un solo adapter del Chat SDK de Vercel para WhatsApp, Instagram, Messenger, SMS y Gmail, que respeta `bot_paused`), `@heysteff/n8n-nodes-heysteff` (trigger que crea su webhook con `POST /v1/webhooks` y verifica la firma; nodo para mandar mensajes, marcar leído, contactos y links de conexión) y `@heysteff/connect` (abre un link de conexión en un popup y resuelve con `channel_id`, `customer_id` y `channel_type`; `<ConnectButton/>` en `@heysteff/connect/react`).
- [Referencia de la API](https://developers.heysteff.com/docs/referencia): referencia interactiva de cada endpoint.

## Paquetes y repos

Todo MIT, con la misma API para WhatsApp, Instagram, Messenger, SMS y correo. Cada README trae un prompt listo para tu agente. Tabla completa: https://developers.heysteff.com/docs/integraciones#paquetes (en inglés: https://developers.heysteff.com/en/docs/integrations#packages). Repos públicos: https://github.com/heysteff-com.

- `@heysteff/sdk`: SDK de TypeScript (Node 20+, Deno, Bun, workers). Instalar: `npm install @heysteff/sdk`. https://www.npmjs.com/package/@heysteff/sdk
- `@heysteff/cli`: el comando `heysteff`. Instalar: `npm install -g @heysteff/cli`. https://www.npmjs.com/package/@heysteff/cli
- `create-heysteff`: plantillas `inbox`, `agent` y `send`. Instalar: `npm create heysteff@latest`. https://www.npmjs.com/package/create-heysteff
- `@heysteff/chat-adapter`: adapter del Chat SDK de Vercel. Instalar: `npm install chat @heysteff/chat-adapter @chat-adapter/state-memory`. https://www.npmjs.com/package/@heysteff/chat-adapter
- `@heysteff/connect`: links de conexión en un popup. Instalar: `npm install @heysteff/connect`. https://www.npmjs.com/package/@heysteff/connect
- `@heysteff/n8n-nodes-heysteff`: nodos de n8n. Instalar: `npm install @heysteff/n8n-nodes-heysteff`. https://www.npmjs.com/package/@heysteff/n8n-nodes-heysteff · https://github.com/heysteff-com/n8n-nodes-heysteff
- `omnichannel-inbox`: plantilla de bandeja en Next.js. Instalar: `npm create heysteff@latest mi-bandeja -- --template inbox`. https://github.com/heysteff-com/omnichannel-inbox
- `ai-agent-starter`: plantilla de agente de IA. Instalar: `npm create heysteff@latest mi-agente -- --template agent`. https://github.com/heysteff-com/ai-agent-starter
- `agent-skills`: skills para agentes de código. Instalar: `npx skills add heysteff-com/agent-skills`. https://github.com/heysteff-com/agent-skills
- `agent-plugins`: plugin de Claude Code, Cursor y Codex. Instalar: `/plugin marketplace add heysteff-com/agent-plugins`. https://github.com/heysteff-com/agent-plugins

## English

- [Quickstart](https://developers.heysteff.com/en/docs/)
- [Templates (npm create heysteff)](https://developers.heysteff.com/en/docs/#templates)
- [Coding agents and MCP](https://developers.heysteff.com/en/docs/coding-agents)
- [Authentication](https://developers.heysteff.com/en/docs/authentication)
- [Sandbox](https://developers.heysteff.com/en/docs/sandbox)
- [Get a number](https://developers.heysteff.com/en/docs/get-a-number)
- [Customers and setup links](https://developers.heysteff.com/en/docs/customers)
- [Pricing](https://developers.heysteff.com/en/pricing)
- [Message types](https://developers.heysteff.com/en/docs/messages)
- [Webhooks](https://developers.heysteff.com/en/docs/webhooks)
- [WhatsApp Flows](https://developers.heysteff.com/en/docs/flows)
- [WhatsApp calls](https://developers.heysteff.com/en/docs/calls)
- [AI agent](https://developers.heysteff.com/en/docs/ai-agent)
- [Bring your own AI](https://developers.heysteff.com/en/docs/bring-your-own-ai)
- [Errors and limits](https://developers.heysteff.com/en/docs/errors-and-limits)
- [TypeScript SDK](https://developers.heysteff.com/en/docs/sdk)
- [Migrate from another provider](https://developers.heysteff.com/en/docs/migrate)
- [Compatible with Meta](https://developers.heysteff.com/en/docs/meta-compatible)
- [CLI](https://developers.heysteff.com/en/docs/cli)
- [Integrations](https://developers.heysteff.com/en/docs/integrations)
- [API reference](https://developers.heysteff.com/en/docs/reference)

## Otros recursos

- [Servidor MCP](https://developers.heysteff.com/docs/agentes-de-codigo#mcp): `https://mcp.heysteff.com/mcp` deja que la IA del comercio configure el workspace completo (agente, canales, flujos, campañas) con OAuth; el workspace se elige al autorizar.
- [heysteff](https://heysteff.com/llms.txt): qué es heysteff, planes y precios.
- Contacto: info@heysteff.com