SDK de TypeScript

npm install @heysteff/sdk

import { Heysteff } from '@heysteff/sdk';        // ESM
const { Heysteff } = require('@heysteff/sdk');   // CommonJS

import { Heysteff } from '@heysteff/sdk';

const heysteff = new Heysteff({ apiKey: process.env.HEYSTEFF_API_KEY });

const message = await heysteff.messages.send({
  channel: 'whatsapp_cloud',
  to: '+56912345678',
  content: 'Hola Ana, tu pedido ya va en camino',
});
console.log(message.id, message.status);

await heysteff.messages.send({
  channel: 'whatsapp_cloud',
  to: '+56912345678',
  content_type: 'interactive',
  interactive: {
    type: 'buttons',
    body: '¿Confirmas tu hora?',
    buttons: [{ id: 'si', title: 'Sí' }, { id: 'no', title: 'No' }],
  },
});
const msg = await heysteff.messages.get(messageId);     // msg.status: queued | sent | delivered | read | failed
await heysteff.messages.markRead(inboundMessageId);       // tildes azules / "visto"
await heysteff.messages.react({ message_id: inboundMessageId, emoji: '👍' });
const { secret } = await heysteff.webhooks.create({ url: 'https://api.tutienda.com/heysteff', events: ['message.read'] });
await heysteff.templates.create({ name: 'pedido_despachado', language: 'es', category: 'UTILITY', body_text: 'Hola {{1}}', body_examples: ['Ana'] });

import { readFile } from 'node:fs/promises';

const file = await heysteff.media.upload({
  file: await readFile('catalogo.pdf'),
  filename: 'catalogo.pdf',
  contentType: 'application/pdf',
});

await heysteff.messages.send({
  channel: 'whatsapp_cloud',
  to: '+56912345678',
  content_type: 'file',
  media: { url: file.url, filename: 'catalogo.pdf' },
  content: 'Te dejo el catálogo de noviembre',
});

const [template] = await heysteff.templates.list();

await heysteff.messages.send(
  {
    channel: 'whatsapp_cloud',
    to: '+56912345678',
    content_type: 'template',
    template: { name: 'pedido_despachado', language: 'es', body_params: ['Ana', '#1042'] },
  },
  { idempotencyKey: 'pedido-1042-despacho' },
);

await heysteff.conversations.get(id);
await heysteff.conversations.escalate(id, { reason: 'Pide un reembolso', urgency: 'high' });
await heysteff.conversations.pauseBot(id);
await heysteff.conversations.resumeBot(id);
await heysteff.conversations.resolve(id);

for await (const conversation of heysteff.conversations.listAll({ status: 'open' })) {
  console.log(conversation.id, conversation.contact_name);
}

import { HeysteffError } from '@heysteff/sdk';

try {
  await heysteff.messages.send({ channel: 'whatsapp_cloud', to: '+56912345678', content: 'Hola' });
} catch (err) {
  if (!(err instanceof HeysteffError)) throw err;
  if (err.code === 'wa_window_closed') {
    // Fuera de la ventana de 24 horas: manda una plantilla.
  } else if (err.category === 'permission') {
    console.error('A la key le falta un permiso:', err.message, err.fix);
  } else if (err.retryable) {
    // Vuelve a encolar el trabajo: el SDK ya agotó sus reintentos.
  } else {
    throw err;
  }
}

// app/webhooks/heysteff/route.ts
import { createWebhookHandler } from '@heysteff/sdk';

export const POST = createWebhookHandler({
  secret: process.env.HEYSTEFF_WEBHOOK_SECRET!,
  onEvent: async (event) => {
    if (event.event === 'message:received') {
      console.log(event.data.external_user_id, event.data.content);
    }
  },
});

import { Hono } from 'hono';
import { createWebhookHandler } from '@heysteff/sdk';

const handler = createWebhookHandler({ secret: process.env.HEYSTEFF_WEBHOOK_SECRET!, onEvent });
const app = new Hono();
app.post('/webhooks/heysteff', (c) => handler(c.req.raw));

import express from 'express';
import { createWebhookHandler } from '@heysteff/sdk';

const handler = createWebhookHandler({ secret: process.env.HEYSTEFF_WEBHOOK_SECRET!, onEvent });
const app = express();
// express.raw: la firma se calcula sobre el cuerpo crudo.
app.post('/webhooks/heysteff', express.raw({ type: 'application/json' }), handler.toExpress());

import { WEBHOOK_EVENT_NAMES, type WebhookEvent } from '@heysteff/sdk';

async function onEvent(event: WebhookEvent) {
  switch (event.event) {
    case 'message:received':
      if (!event.data.bot_paused) console.log(event.data.channel, event.data.content);
      break;
    case 'message.failed':
      console.log(event.data.message_id, event.data.error.code);
      break;
    case 'conversation.escalated':
      console.log('Pasó a una persona:', event.data.conversation_id);
      break;
  }
}

console.log(WEBHOOK_EVENT_NAMES); // ['message:received', 'message:sent', …]

import express from 'express';
import { verifyWebhook, WebhookVerificationError } from '@heysteff/sdk';

const app = express();

app.post('/webhooks/heysteff', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await verifyWebhook({
      payload: req.body, // el cuerpo crudo, no el JSON parseado
      headers: req.headers,
      secret: process.env.HEYSTEFF_WEBHOOK_SECRET!,
    });
    console.log(event.event, event.data);
    res.sendStatus(200);
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.sendStatus(400);
    throw err;
  }
});

const controller = new AbortController();
process.on('SIGINT', () => controller.abort());

for await (const event of heysteff.events.stream({
  events: ['message:received', 'message.read'],
  signal: controller.signal,
})) {
  if (event.event === 'message:received') console.log(event.data.content);
}

const { number, connect_url, connect_url_expires_at } = await heysteff.numbers.reserve();
// Alguien abre connect_url en un navegador y elige el número en Meta.
const { data, plan, offer } = await heysteff.numbers.list();
await heysteff.numbers.requestDisplayName(number.id, 'Tienda Aurora');
await heysteff.numbers.release(number.id); // 409 wa_pool_number_connected si ya está conectado

const customer = await heysteff.customers.create({ external_id: 'acme-42', name: 'Acme SpA' });
const { url } = await heysteff.customers.createSetupLink(customer.id, { allowed_channels: ['whatsapp_cloud'] });
// Tu cliente abre url y conecta su WhatsApp.
const channels = await heysteff.customers.listChannels(customer.id);
await heysteff.messages.send({ channel: 'whatsapp_cloud', customer_id: customer.id, to: '+56912345678', content: 'Hola' });
for await (const c of heysteff.customers.listAll()) console.log(c.external_id, c.channels_count);

const agent = await heysteff.agent.get(); // estado, cupo de prueba y keys (solo sus últimos 4)
await heysteff.agent.setKey({ provider: 'anthropic', api_key: process.env.ANTHROPIC_API_KEY! });
await heysteff.agent.update({ enabled: true, provider: 'anthropic', model: 'claude-haiku-5-5', channels: [{ id: channelId, enabled: false }] });
await heysteff.agent.tools.create({ slug: 'estado_pedido', name: 'Estado de un pedido', description: 'Busca un pedido por su número.', spec });
const { agent_gaps } = await heysteff.insights.get({ days: 7 });