Pular para o conteúdo principal

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:

ÁreaSe accede conQué hace
Gestión de cuentastevo.instances, stevo.links, stevo.ghl, stevo.billing, stevo.ghlAgencyinstancias, links de acceso, GHL, compras, GHL Agencia
Stevo IA (v2)stevo.aiagentes, embudo, claves de proveedor, FAQ, tools, follow-up, RAG, memoria
Mensajeríastevo.smv2(id) · stevo.oficial(id)habla DIRECTO con el servidor de la instancia (74 operaciones SM v2) o el gateway Cloud API de Meta
Envío masivostevo.dispatchcampañas de WhatsApp con rotación de instancias, programación y variaciones
StevoVoicestevo.voicellamadas de voz con IA (programadas, en lote, bajo demanda)

📦 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
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 — 74 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!' } });

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 });

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​