heysteff para developers
La API de WhatsApp, Instagram, Messenger, SMS y email, con una bandeja para tu equipo.
Un endpoint para mandar, webhooks firmados para recibir y los datos de tu tienda en el mismo lugar. Tu código responde y, cuando hace falta una persona, tu equipo sigue la conversación desde la web o el celular.
Pruébala con una key sk_test_ y el número compartido del sandbox, sin conectar un número propio.
curl https://app.heysteff.com/api/v1/messages \
-H "Authorization: Bearer $HEYSTEFF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1042-en-camino" \
-d '{
"channel": "whatsapp_cloud",
"to": "+56912345678",
"content": "Hola Ana, tu pedido #1042 ya va en camino."
}'import { Heysteff } from '@heysteff/sdk';
const heysteff = new Heysteff(); // lee HEYSTEFF_API_KEY
const message = await heysteff.messages.send({
channel: 'whatsapp_cloud',
to: '+56912345678',
content: 'Hola Ana, tu pedido #1042 ya va en camino.',
});
console.log(message.id, message.status);npm install -g @heysteff/cli
heysteff login
heysteff messages send --channel whatsapp_cloud \
--to +56912345678 \
--text "Hola Ana, tu pedido #1042 ya va en camino."POST /v1/messages201 Created · "status": "pending"
- Baseapp.heysteff.com/api/v1
- AuthBearer sk_live_ · sk_test_
- EspecificaciónOpenAPI 3.1
- Límite120 solicitudes / 60 s
- WebhooksHMAC-SHA256 · 6 intentos
Trae tu propia IA
Tu modelo atiende. Nosotros ponemos el canal y la bandeja.
Conecta el modelo que ya usas sin escribir una integración con Meta. heysteff le entrega cada mensaje a tu servidor y manda lo que tu modelo responde.
El cliente escribe
Por WhatsApp, Instagram, Messenger, SMS o correo. Cada canal llega a la misma conversación del contacto.
Te avisamos
Un POST firmado a tu servidor con el evento
message:received. Si tu servidor no responde, reintentamos con espera creciente.Tu modelo decide
Lees el historial con
GET /v1/conversations/{id}/messagesy respondes conPOST /v1/messages, con unaIdempotency-Keypara no contestar dos veces.Una persona sigue
Cuando tu modelo no deba seguir, tu equipo responde desde la bandeja de heysteff, en la web o en la app móvil, con todo el historial a la vista.
Cuando tu modelo no sabe, POST /v1/conversations/{id}/escalate pasa la conversación a una persona en la bandeja y pausa el bot; los avisos siguientes llegan con bot_paused: true. POST /v1/conversations/{id}/bot y /resolve se la devuelven a tu IA. La guía Conecta tu propia IA trae el flujo completo, y Agentes de código un prompt para armarlo con tu agente de código.
O usa el agente de heysteff
Un agente de IA en todos los planes, pagado con tu propia key.
Si no quieres operar un modelo, enciende el agente: responde en todos tus canales con tus instrucciones y tus archivos de contexto, consulta tu backend con custom tools y le pasa la conversación a tu equipo cuando corresponde.
- Tu key, tu costoGuarda tu key de Anthropic, OpenAI, DeepSeek u OpenRouter y el proveedor te cobra los tokens directo. heysteff no les suma nada.
- Cupo de pruebaSin key, el agente responde con la key de heysteff: 200 respuestas al mes en Developer Free, 2.000 en Developer y 20.000 en Developer Platform.
- Custom toolsEl agente llama a tu API en plena conversación para ver un pedido, el stock o la agenda: 2 en Developer Free, 10 en Developer y sin tope en Developer Platform.
- Encendido donde quierasPor espacio, por canal, por cliente de tu SaaS o por conversación, desde la consola o con
PATCH /v1/agent. - Webhooks del agente
agent.replied,agent.handoffyagent.failedte dicen qué respondió, cuándo pasó la conversación a una persona y por qué no pudo responder. - HallazgosEn Developer y Developer Platform ves qué no supo responder el agente y qué clientes quedaron frustrados: en la consola, con
GET /v1/insightso con el webhook semanalinsight.detected.
La guía Agente de IA explica cómo encenderlo, los modelos y sus precios, los errores y los webhooks.
Ya resuelto
Lo que no tienes que construir
Lo que se come las semanas cuando conectas la Cloud API de Meta por tu cuenta ya viene hecho.
- Bandeja para personasTu equipo lee y responde cada conversación desde la web y la app móvil para Android e iOS, con notas internas, responsables y el historial completo.
- Plantillas de WhatsAppCréalas y revísalas en el panel, lístalas con
GET /v1/templatesy mándalas concontent_type: "template"fuera de la ventana de 24 horas. - BajasQuien responde STOP, BAJA o CANCELAR deja de recibir SMS de tu número, y las bajas de WhatsApp quedan registradas para tus campañas.
- Ritmo anti-bloqueoCon WhatsApp conectado por QR, cada envío pasa por un control de ritmo por número que espacia los mensajes para no gatillar una restricción.
- Webhooks que no se pierdenFirma HMAC-SHA256, 6 intentos con espera creciente, registro de cada entrega y reintento con
POST /v1/webhook-deliveries/{id}/retry. - Shopify y ventasCon la tienda conectada, la recuperación de carritos, las solicitudes de reseña y las ventas atribuidas funcionan en el mismo espacio y llegan como eventos a tu webhook.
Herramientas
Desde tu terminal, tu código o tu agente de IA.
API REST
JSON, una API key por integración con scopes, idempotencia en las escrituras y paginación por cursor. La especificación OpenAPI 3.1 sirve para generar un cliente en cualquier lenguaje.
SDK
@heysteff/sdk para TypeScript, sin dependencias: corre en Node 20+, Deno, Bun y Cloudflare Workers. Reintenta con la misma clave de idempotencia y verifica webhooks.
CLI
El comando heysteff: inicia sesión con tu key, manda mensajes, lista conversaciones y plantillas, y prueba tu webhook en localhost con un aviso firmado.
MCP
Un servidor MCP remoto con OAuth para que Claude Code, Codex o Cursor configuren tu espacio: agente, canales, flujos y campañas. Entra con tu sesión, nunca con una API key.
Sandbox
Una key sk_test_ manda por el número compartido de heysteff a los teléfonos que unes al sandbox, hasta 5. No le escribe a ningún cliente.
Plantillas
Empieza con una bandeja omnicanal en Next.js, un agente de IA que contesta con Claude o un envío mínimo. Código MIT, tu key queda en .env.local y la bandeja se despliega en Vercel con un clic.
Código abierto
Empieza desde nuestro GitHub.
Plantillas e integraciones con licencia MIT. Haz fork, pon tu API key y listo.
Bandeja omnicanal
Bandeja en Next.js para WhatsApp, Instagram, Messenger, SMS y email. Pide solo tu API key y se despliega en Vercel con un clic.
Agente de IA inicial
Un agente con Claude que contesta por cualquier canal y deriva a una persona cuando hace falta.
Plugin para agentes de código
MCP, skills y reglas de seguridad para Claude Code, Cursor y Codex.
Skills
Integrar, automatizar y observar heysteff desde tu agente de código.
Nodos de n8n
Trigger que crea su propio webhook y envío omnicanal desde tus flujos.
Comparación
heysteff o la Cloud API de Meta directa
Si solo necesitas mandar plantillas de WhatsApp desde un sistema, la Cloud API directa puede bastarte. Esto cambia cuando también hay personas, más canales y una tienda.
| Cloud API de Meta directa | Con heysteff | |
|---|---|---|
| Alta del número | Creas la app, el portafolio y la cuenta de WhatsApp Business, y registras el número tú. | Registro guiado de Meta desde el panel, o WhatsApp por QR. |
| Canales | Solo WhatsApp. Instagram y Messenger son otras APIs de Meta; SMS y correo, otros proveedores. | WhatsApp, Instagram, Messenger, SMS y correo con el mismo POST /v1/messages. |
| Recibir mensajes | Un webhook de Meta con un formato distinto por producto. | Un solo evento message:received para todos los canales, firmado, con registro de entregas. |
| Personas en la conversación | La bandeja la construyes tú. | Incluida, en la web y en la app móvil. |
| Datos de comercio | Fuera de alcance. | Shopify, carritos, reseñas y ventas atribuidas en el mismo espacio. |
| Costo de los mensajes | Meta cobra a tu cuenta de WhatsApp Business. | Igual: Meta cobra directo a tu cuenta y heysteff no le pone recargo. Aparte pagas tu plan de heysteff. |
| Alcance de la API | Toda la Graph API de WhatsApp. | La API v1 de heysteff. Lo que no está en la referencia todavía no se puede hacer por API. |
Empieza gratis con el sandbox.
Crea tu cuenta, genera una key sk_test_ y manda tu primer WhatsApp desde tu terminal. Los planes para developers están en la página de precios.
Preguntas
Preguntas técnicas
¿Necesito un número propio para probar?
No. Con una key sk_test_ los mensajes salen por el número compartido del sandbox, solo a los teléfonos que unes a tu espacio. Cuando quieras escribirle a clientes, conectas tu número en Configuración → Canales y usas una key sk_live_.
¿Puedo usar mi propio modelo de IA?
Sí. Recibes cada mensaje en tu servidor con el webhook message:received, se lo pasas a tu modelo y respondes con POST /v1/messages. Un espacio de developer nace con el agente de heysteff apagado, así no responden dos.
¿Cuánto cuesta el agente de IA de heysteff?
Viene en todos los planes. Con tu propia key del proveedor pagas los tokens directo a ese proveedor, sin recargo nuestro. Sin key, usas el cupo de prueba del plan; cuando se acaba, el agente deja de responder y llega el webhook agent.failed con ai_quota_exhausted. Detalle en Agente de IA.
¿Qué pasa fuera de la ventana de 24 horas de WhatsApp?
WhatsApp solo acepta texto libre dentro de las 24 horas siguientes al último mensaje del cliente. Fuera de esa ventana mandas una plantilla aprobada por Meta, con el mismo endpoint y content_type: "template".
¿Qué límites tiene la API?
Cada API key admite 120 solicitudes por ventana de 60 segundos; al pasarte responde 429 rate_limited. Los límites del plan, como los mensajes al mes, responden 402 plan_limit_exceeded. El detalle está en Errores y límites.
¿Cómo evito mandar un mensaje dos veces?
Manda un header Idempotency-Key con una clave por operación lógica. Si repites la solicitud con la misma clave, recibes la misma respuesta y no sale otro mensaje. El SDK lo hace solo en cada reintento.
¿Qué pasa si mi servidor se cae?
Cada entrega se reintenta a los 1, 2, 4, 8 y 16 minutos; después del sexto intento queda marcada como fallida. Las ves con GET /v1/webhooks/{id}/deliveries, las vuelves a mandar con POST /v1/webhook-deliveries/{id}/retry y puedes recuperar lo que pasó con GET /v1/events.
¿Cuánto cobra Meta por los mensajes?
Con WhatsApp por la API oficial, Meta cobra sus mensajes directo a la cuenta de WhatsApp Business de tu negocio y heysteff no les pone recargo. Los planes para developers están en la página de precios.