SDK oficial — `stevo-sdk`

stevo-sdk es el SDK oficial (TypeScript/JavaScript) de Stevo. Un solo paquete con todo lo que ofrece la plataforma, bien separado por área:

Área	Se accede con	Qué hace
Gestión de cuenta	`stevo.instances`, `stevo.links`, `stevo.ghl`, `stevo.billing`, `stevo.ghlAgency`	instancias, links de acceso, GHL, compras, GHL Agencia
Stevo IA (v2)	`stevo.ai`	agentes, embudo, claves de proveedor, FAQ, tools, follow-up, RAG, memoria
Mensajería	`stevo.smv2(id)` · `stevo.oficial(id)`	habla DIRECTO con el servidor de la instancia (114 operaciones SM v2) o el gateway Cloud API de Meta
Envío masivo	`stevo.dispatch`	campañas de WhatsApp con rotación de instancias, programación y variaciones
StevoVoice	`stevo.voice`	llamadas de voz y acceso a las grabaciones de la instancia

📦 npm: npm.im/stevo-sdk · Node.js 18+ · ESM + CommonJS + tipos

Renombrado

Este paquete era stevo-gestao. Ahora que cubre todo, se llama stevo-sdk. Cambia con npm install stevo-sdk.

¿Sin código? Usa IA + MCP

La misma API tiene un servidor MCP en https://openapi.stevo.chat/mcp. Conéctalo a n8n, Claude o Cursor con tu API key y la IA gestiona la cuenta, envía mensajes, crea campañas y programa llamadas sin una línea de código.

1. Crea tu API Key

En el panel de Stevo: menú del perfil → API Keys → Nueva API Key. Elige los scopes. La key se muestra una sola vez — guárdala con seguridad y nunca la expongas en el navegador/front-end.

2. Instala y conecta

npm install stevo-sdk

import { Stevo } from 'stevo-sdk';
const stevo = new Stevo('stevo_sk_...');
const instancias = await stevo.instances.list();

3. Gestión de cuenta

const inst = await stevo.instances.create({ name: 'mi-instancia' });
await stevo.instances.restart(id);
await stevo.instances.recreateTotalBatch([id1, id2]); // hasta 50

// Webhook de la instancia (el mismo de Configuración → Webhook en el panel)
await stevo.instances.setWebhook(id, { url: 'https://mi-sistema.com/webhook/stevo', events: ['MESSAGE', 'CONNECTION'] }); // SM v2
await stevo.instances.setWebhook(idOficial, { url: 'https://mi-sistema.com/webhook/oficial' }); // API Oficial
const webhook = await stevo.instances.getWebhook(id); // { engine, url, events }
await stevo.instances.deleteWebhook(id);
const link = await stevo.links.whiteLabel(id, { permanent: true });
const catalogo = await stevo.billing.plans();
if (catalogo.has_saved_card) await stevo.billing.purchase({ plan: 'stevo3' });

4. Mensajería

Cada instancia corre en su propio servidor con su propio token — el SDK lo resuelve a partir del instanceId:

// SM v2 — 114 operaciones del servidor
const wa = await stevo.smv2(instanceId);
await wa.sendText({ body: { number: '5511999999999', text: '¡Hola!' } });

// API Oficial Meta — formato Cloud API + plantillas HSM
const meta = await stevo.oficial(instanceIdOficial);
await meta.sendMessage({ to: '5511999999999', type: 'text', text: { body: '¡Hola!' } });
// Medios RECIBIDOS (el webhook solo trae el id: image.id, audio.id...) — sin token de Meta
const media = await meta.downloadMedia('1436196501752591'); // { data, mimeType, fileSize, sha256, fileName }

5. Envío masivo

Pasa los instance_ids que dispararán — las credenciales de los servidores se resuelven internamente (nunca envías un token):

const camp = await stevo.dispatch.createCampaign({
  instance_ids: [instanceId],
  name: 'Promo Julio',
  messages: ['¡Hola! Tenemos novedades para ti 🎉'],
  recipients: [{ phone: '5511999999999', name: 'María' }],
  config: { minDelay: 5, maxDelay: 15 },
  start: true,
});
await stevo.dispatch.pause(camp.campaign_id);

6. StevoVoice — llamadas de voz con IA

Requiere StevoVoice suscrito en la instancia:

await stevo.voice.scheduleCall(instanceId, { to_number: '5511999999999', agent_id: 'agent_xyz' });
await stevo.voice.batchCalls(instanceId, { numbers: ['5511...', '5511...'], agent_id: 'agent_xyz', interval_seconds: 60 });

// Grabaciones de llamadas nativas — requiere voice:read
const pagina = await stevo.voice.listRecordings(instanceId, {
  limit: 50,
  direction: 'outbound',
  has_audio: true,
});
const grabacion = await stevo.voice.getRecording(instanceId, pagina.recordings[0].id);
const respuesta = await stevo.voice.downloadRecording(instanceId, grabacion.id);
const mp3 = await respuesta.arrayBuffer();

// Atajo posllamada: acepta UUID, nombre visible o instance_name
const ultima = await stevo.voice.getLatestRecording('well-pessoal-teste', {
  call_id: 'id-de-la-llamada', // opcional, recomendado para llamadas simultáneas
});

Receta lista: descargar la última grabación mediante REST

No necesitas conocer previamente el UUID de la instancia ni el ID de la grabación. Crea una API Key con el scope voice:read e informa el nombre:

curl --get 'https://openapi.stevo.chat/v1/voice/recordings/latest' \
  --header 'Authorization: Bearer stevo_sk_TU_CLAVE' \
  --data-urlencode 'instance=nombre-de-instancia'

La respuesta incluye la instancia resuelta, la última grabación y su download_url autenticada. Copia esa URL y haz un segundo GET con la misma clave. -L es obligatorio porque la API devuelve un redirect 307 al MP3:

curl -L \
  --header 'Authorization: Bearer stevo_sk_TU_CLAVE' \
  'https://openapi.stevo.chat/v1/instances/UUID_INSTANCIA/voice/recordings/UUID_GRABACION/download' \
  --output llamada.mp3

Para listar el historial, usa data.instance.id devuelto en la primera llamada:

curl --get 'https://openapi.stevo.chat/v1/instances/UUID_INSTANCIA/voice/recordings' \
  --header 'Authorization: Bearer stevo_sk_TU_CLAVE' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'has_audio=true'

En automatizaciones, pasa también call_id a latest si varias llamadas pueden terminar al mismo tiempo. La grabación aparece después de finalizar la llamada y completar la carga; reintenta brevemente ante un 404. Si el nombre es ambiguo, usa el UUID.

7. Stevo IA (v2)

await stevo.ai.setProviderKeys(instanceId, { openai: 'sk-...' }); // write-only
const agente = await stevo.ai.agents.create(instanceId, { name: 'Agente', provider: 'openai', model: 'gpt-4o-mini', is_primary: true });
await stevo.ai.stages.create(agente.id, { name: 'Bienvenida', objective: 'Recolectar el nombre' });

8. Manejo de errores

Toda falla es un StevoError con el status HTTP y un code de negocio (no_saved_card, insufficient_scope, not_found...). El SDK reintenta automáticamente en 429 y errores de servidor, y nunca expone secretos.

9. Entrégaselo a tu IA

Usa el paquete npm stevo-sdk (TypeScript, tipos incluidos, Node 18+). Instancia new Stevo(apiKey) con la key stevo_sk_... de la pestaña API Keys del panel Stevo. Recursos: instances, links, ghl, billing, ghlAgency, ai (gestión); stevo.smv2(instanceId) y stevo.oficial(instanceId) para ENVIAR mensajes (el SDK resuelve las credenciales del servidor de la instancia); stevo.dispatch (campañas masivas con instance_ids) y stevo.voice (llamadas de voz con IA). Los errores son StevoError con .status y .code. Referencia completa: https://tutorial.stevo.chat/public-api-reference

Referencias

📖 Referencia de la API de Gestión · SM v2 · API Oficial
📦 Paquete en npm
🤖 Servidor MCP: https://openapi.stevo.chat/mcp

1. Crea tu API Key​

2. Instala y conecta​

3. Gestión de cuenta​

4. Mensajería​

5. Envío masivo​

6. StevoVoice — llamadas de voz con IA​

Receta lista: descargar la última grabación mediante REST​

7. Stevo IA (v2)​

8. Manejo de errores​

9. Entrégaselo a tu IA​

Referencias​