SDK oficial — stevo-sdk

O stevo-sdk é o SDK oficial (TypeScript/JavaScript) da Stevo. Um pacote só, com tudo que a plataforma oferece — bem separado por área:

Área	Como acessa	O que faz
Gestão da conta	stevo.instances, stevo.links, stevo.ghl, stevo.billing, stevo.ghlAgency	instâncias, links de acesso, GHL, compras e GHL Agência
Stevo IA (v2)	stevo.ai	agentes, funil, chaves de provedor, FAQ, tools, follow-up, RAG, memória
Envio de mensagem	stevo.smv2(id) · stevo.oficial(id)	fala DIRETO com o servidor da instância (74 operações SM v2) ou o gateway Cloud API da Meta
Disparo em massa	stevo.dispatch	campanhas de WhatsApp com rotação de instâncias, agendamento e variações
StevoVoice	stevo.voice	chamadas de voz com IA (agendadas, em lote, sob demanda)

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

Renomeado

Este pacote era o stevo-gestao. Agora que cobre tudo (não só gestão), passou a se chamar stevo-sdk. Se você usa o antigo, troque para npm install stevo-sdk.

Prefere não escrever código? Use a IA + MCP

A mesma API tem um servidor MCP em https://openapi.stevo.chat/mcp. Plugue no n8n (nó MCP Client), Claude ou Cursor com a sua API key e a IA gerencia sua conta, envia mensagens, cria campanhas e agenda chamadas sem uma linha de código.

1. Crie sua API Key

No painel da Stevo: menu do perfil → API Keys → Nova API Key. Marque os scopes (permissões) que essa key vai ter — de instances:read (só leitura) até envio, disparo, voz, IA e billing. A key aparece uma única vez — guarde com segurança e nunca a exponha no navegador/front-end.

2. Instale e conecte

npm install stevo-sdk

import { Stevo } from 'stevo-sdk';

const stevo = new Stevo('stevo_sk_...'); // sua API key

const instancias = await stevo.instances.list();
console.log(`${instancias.filter((i) => i.connected).length} conectadas`);

3. Gestão da conta

// Criar instância numa vaga livre do plano (não compra vaga nova)
const nova = await stevo.instances.create({ name: 'minha-instancia' });
const oficial = await stevo.instances.create({ engine: 'official' }); // devolve onboarding_url

await stevo.instances.restart(id);        // reconectar (ler QR depois)
await stevo.instances.recreateTotal(id);  // DESTRUTIVO: zera tudo
await stevo.instances.recreateTotalBatch([id1, id2, id3]); // em massa (até 50)

// Links, GHL e compras
const link = await stevo.links.whiteLabel(id, { permanent: true });
await stevo.ghl.connect(id, { mode: 'oauth' });
const catalogo = await stevo.billing.plans();
if (catalogo.has_saved_card) await stevo.billing.purchase({ plan: 'stevo3' });

4. Enviando mensagens

Cada instância roda no seu próprio servidor, com token próprio — mas o SDK resolve isso sozinho a partir do instanceId:

// SM v2 (WhatsApp não-oficial) — 74 operações do servidor
const wa = await stevo.smv2(instanceId);
await wa.sendText({ body: { number: '5511999999999', text: 'Olá!' } });
await wa.sendMedia({ body: { number: '5511999999999', url: 'https://...', caption: 'Segue!' } });
const grupos = await wa.getGroupList();

// API Oficial Meta — formato Cloud API + templates HSM
const meta = await stevo.oficial(instanceIdOficial);
await meta.sendMessage({ to: '5511999999999', type: 'text', text: { body: 'Olá!' } });
const templates = await meta.listTemplates();

// Prefere passar as credenciais na mão? Também dá:
const wa2 = await stevo.smv2({ serverUrl: 'https://sm-x.stevo.chat', token: 'apikey-da-instancia' });

O client SM v2 tem 74 operações geradas do swagger oficial (grupos: Send Message, Chat, Group, Label, Newsletter, User, Instance, Community, Call, Message), todas com autocomplete. Referência: API StevoManager v2 · API Oficial.

5. Disparo em massa

Você passa os instance_ids que vão disparar — as credenciais dos servidores são resolvidas internamente (você nunca envia token):

const camp = await stevo.dispatch.createCampaign({
  instance_ids: [instanceId],
  name: 'Promo Julho',
  messages: ['Olá! Temos novidades para você 🎉'],
  recipients: [{ phone: '5511999999999', name: 'Maria' }],
  config: { minDelay: 5, maxDelay: 15 }, // segundos entre envios
  start: true,
});

await stevo.dispatch.getCampaign(camp.campaign_id); // status/progresso
await stevo.dispatch.pause(camp.campaign_id);
await stevo.dispatch.resume(camp.campaign_id);

Com mais de uma instância em instance_ids, a rotação é automática. messages aceita variações com mídia e botões.

6. StevoVoice — chamadas de voz com IA

Requer o StevoVoice assinado na instância:

// Uma chamada com agente de IA (ElevenLabs)
await stevo.voice.scheduleCall(instanceId, {
  to_number: '5511999999999',
  agent_id: 'agent_xyz',
  scheduled_at: '2026-07-20T14:00:00Z', // opcional (default: agora)
});

// Em lote, com intervalo entre chamadas
await stevo.voice.batchCalls(instanceId, {
  numbers: ['5511999999999', '5511888888888'],
  agent_id: 'agent_xyz',
  interval_seconds: 60,
});

const agendadas = await stevo.voice.listScheduled(instanceId);
await stevo.voice.cancelCall(callId);

7. Stevo IA (v2)

Configure agentes multi-provedor, funil de etapas, base de conhecimento e mais:

// Config base + chave do provedor (write-only: nunca é retornada)
await stevo.ai.updateSettings(instanceId, { enabled: true, timezone: 'America/Sao_Paulo' });
await stevo.ai.setProviderKeys(instanceId, { openai: 'sk-...' });

// Agente + funil
const agente = await stevo.ai.agents.create(instanceId, {
  name: 'Atendente',
  provider: 'openai',
  model: 'gpt-4o-mini',
  system_prompt: 'Você é um atendente cordial.',
  is_primary: true,
});
await stevo.ai.stages.create(agente.id, { name: 'Boas-vindas', objective: 'Coletar o nome' });

// FAQ, follow-up e conhecimento (RAG)
await stevo.ai.faq.create(instanceId, { question: 'Qual o horário?', answer: 'Das 9h às 18h.' });
await stevo.ai.followup.set(instanceId, { enabled: true, max_followups: 3 });

8. Tratamento de erros

Toda falha vira um StevoError com o status HTTP e um código de negócio:

import { StevoError } from 'stevo-sdk';

try {
  await stevo.billing.purchase({ plan: 'stevo3' });
} catch (e) {
  if (e instanceof StevoError && e.code === 'no_saved_card') {
    // conta sem cartão salvo — orientar a cadastrar no painel
  }
}

O SDK tenta de novo sozinho em rate limit (429) e erros de servidor. Ele não expõe segredos: chaves de provedor são write-only e o token dos servidores é tratado internamente.

9. Entregando pra sua IA implementar

Se quem vai escrever a integração é uma IA (Claude, Cursor, Copilot, ChatGPT...), cole este bloco no contexto dela:

Use o pacote npm stevo-sdk (TypeScript, tipos inclusos, Node 18+). Instancie new Stevo(apiKey) com a key stevo_sk_... da aba API Keys do painel Stevo. Recursos: instances, links, ghl, billing, ghlAgency, ai (gestão); stevo.smv2(instanceId) (servidor SM v2: sendText/sendMedia/getGroupList... 74 ops) e stevo.oficial(instanceId) (Cloud API Meta: sendMessage/listTemplates...) para ENVIAR mensagens — o SDK resolve as credenciais do servidor da instância sozinho; stevo.dispatch (campanhas de disparo com instance_ids) e stevo.voice (chamadas de voz com IA). Erros são StevoError com .status e .code. Referência completa: https://tutorial.stevo.chat/public-api-reference

Referências

• 📖 Referência da API de Gestão (endpoints, erros e scopes)
• 📖 API StevoManager v2 e API Oficial
• 📦 Pacote no npm
• 🤖 Servidor MCP: https://openapi.stevo.chat/mcp (mesma API key)