Referencia

Integraciones

Tres paquetes sobre la misma API: un bot del Chat SDK que contesta en WhatsApp, Instagram, Messenger, SMS y Gmail con un solo adapter, nodos para n8n y un SDK de navegador para que tus clientes conecten sus canales en un popup. Son MIT y su código vive junto a la API.

Chat SDK de Vercel: @heysteff/chat-adapter#

Un solo adapter para todos los canales. Recibe los webhooks firmados, los convierte en mensajes del Chat SDK y cada thread.post() sale por el canal, número y destinatario de la conversación con el mismo POST /v1/messages.

npm install chat @heysteff/chat-adapter @chat-adapter/state-memory

import { Chat } from 'chat';
import { createMemoryState } from '@chat-adapter/state-memory';
import { createHeysteffAdapter, threadChannel } from '@heysteff/chat-adapter';

export const bot = new Chat({
  userName: 'mi-bot',
  adapters: { heysteff: createHeysteffAdapter() }, // HEYSTEFF_API_KEY y HEYSTEFF_WEBHOOK_SECRET
  state: createMemoryState(),
});

bot.onDirectMessage(async (thread, message) => {
  await thread.post(`Te escribo por ${threadChannel(thread)}: ${message.text}`);
});

// app/api/webhooks/heysteff/route.ts
import { after } from 'next/server';
import { bot } from '@/lib/bot';

export async function POST(request: Request) {
  return bot.webhooks.heysteff(request, { waitUntil: (task) => after(() => task) });
}

• Texto, archivos y botones: los archivos se suben con POST /v1/media; una tarjeta con Button sale como botones de respuesta (hasta 3) o lista (hasta 10) con content_type: "interactive", y el botón tocado llega a onAction.
• Una persona tomó la conversación: con bot_paused el bot no recibe los mensajes y thread.post lanza HeysteffBotPausedError sin mandar nada.
• Canal: thread.channelId es heysteff:<canal> y threadChannel(thread) devuelve whatsapp_cloud, instagram, facebook, sms o gmail.
• Historial y DM: fetchMessages usa GET /v1/conversations/{id}/messages; adapter.openDM("whatsapp_cloud:+56912345678") abre un thread para escribir primero.

n8n: @heysteff/n8n-nodes-heysteff#

Instálalo en Settings → Community Nodes con el nombre @heysteff/n8n-nodes-heysteff y crea la credencial heysteff API con tu API key.

• heysteff Trigger: al activar el workflow crea su webhook con POST /v1/webhooks y los eventos que elijas (message:received, customer.channel_connected, payment.paid…), lo borra al desactivarlo y verifica la firma de cada aviso. Puede ignorar las conversaciones que tomó una persona.
• heysteff: manda texto, plantillas, archivos o botones por cualquier canal; marca como leído; crea y busca contactos; crea clientes y sus links de conexión.

Links de conexión en un popup: @heysteff/connect#

Para un SaaS cuyos clientes conectan su propio canal (ver Clientes y links de conexión). connect() abre el link en un popup y resuelve con { channel_id, customer_id, channel_type }; rechaza si tu cliente cierra la ventana. Aunque lo llames dos veces, hay un solo popup.

npm install @heysteff/connect

import { connect } from '@heysteff/connect';

const { channel_id, customer_id, channel_type } = await connect({
  // Tu servidor crea el link con customers.createSetupLink.
  url: () => fetch('/api/connect-link', { method: 'POST' }).then((r) => r.text()),
});

import { ConnectButton } from '@heysteff/connect/react';

<ConnectButton url={createLink} onSuccess={(r) => save(r.channel_id)}>
  Conecta tu WhatsApp
</ConnectButton>

La página del link le avisa por postMessage solo al origen de la ventana que la abrió, y el SDK acepta el aviso solo desde el origen del link. Para tu backend la fuente de verdad sigue siendo el webhook customer.channel_connected.

Paquetes y repositorios#

Todo es MIT y usa la misma API: un mismo código para WhatsApp, Instagram, Messenger, SMS y correo. Cada README trae un prompt listo para pegar en Claude Code, Cursor, Codex o ChatGPT. Los repos públicos viven en github.com/heysteff-com.

En n8n también puedes instalarlo desde Settings → Community Nodes. En Claude Code, después del marketplace corre /plugin install heysteff@heysteff.