Skip to main content
O cliente oficial sparkcrm oferece acesso tipado à API REST do Spark a partir de TypeScript ou JavaScript no servidor. O código-fonte e o changelog ficam no repositório gepetojj/spark-typescript.

​
Requisitos

  • TypeScript ≥ 4.9 (recomendado para aproveitar os tipos exportados).
  • Node.js 20 LTS ou superior, ou runtimes compatíveis: Bun, Deno, Cloudflare Workers, Vercel Edge, Nitro ≥ 2.6.
  • React Native não é suportado no momento.
  • Chave de API da organização (pk_… ou sk_…) com ambiente de desenvolvedores habilitado.

​
Instalação

npm install sparkcrm
Alternativas equivalentes: pnpm add sparkcrm, yarn add sparkcrm, bun add sparkcrm.

​
Configurar o cliente

Crie o cliente uma vez por processo (ou por requisição, em serverless) e reutilize: 
import SparkCRM from "sparkcrm";

const client = new SparkCRM({
  apiKey: process.env.SPARK_API_KEY, // ou SPARK_API_KEY no ambiente
});
Opção / variávelFunção
apiKey / SPARK_API_KEYChave enviada no cabeçalho X-API-Key em todas as requisições
baseURL / SPARK_CRM_BASE_URLURL base da API (padrão: https://gateway.crmspark.com.br)
Use sk_… apenas no backend. Nunca exponha chave secreta em apps mobile, front-end público ou repositórios.

​
Primeira chamada

Listar os entrypoints (canais) da organização: 
import SparkCRM from "sparkcrm";

const client = new SparkCRM({
  apiKey: process.env.SPARK_API_KEY,
});

const { entrypoints } = await client.entrypoints.list();

for (const ep of entrypoints) {
  console.log(ep.id, ep.platform, ep.name);
}
Filtrar por plataforma: 
const whatsappOnly = await client.entrypoints.list({
  platform: "whatsapp",
});

​
Tipos exportados

Cada método tem parâmetros e resposta tipados. Importe o namespace do pacote quando quiser anotar variáveis: 
import SparkCRM from "sparkcrm";

const client = new SparkCRM({ apiKey: process.env.SPARK_API_KEY! });

const response: SparkCRM.EntrypointListResponse =
  await client.entrypoints.list();
No editor, passe o mouse sobre client.entrypoints.list para ver docstrings geradas a partir da API.

​
Fluxos comuns

​
Enviar mensagem de texto

await client.messaging.chats.sendMessage(chatId, {
  text: "Olá! Recebemos seu contato.",
});

​
Enviar mídia

  1. Faça upload:
import { readFileSync } from "node:fs";

const results = await client.messaging.uploadMedia({
  files: [readFileSync("./foto.jpg")],
});

const uploaded = results.find((r) => r.success);
if (!uploaded || !uploaded.success) {
  throw new Error("Falha no upload");
}

await client.messaging.chats.sendMessage(chatId, {
  text: "Segue a imagem.",
  mediaIds: [uploaded.id],
});

​
Enviar modelo com variáveis

Variáveis manuais vão em commonVariables (var1, var2, …). Variáveis automáticas (dados do chat) são resolvidas pelo Spark — veja Modelos de mensagem. Enquanto o método tipado sendTemplate estiver sendo publicado em novas versões do pacote, use o helper HTTP do cliente: 
await client.post(`/v1/messaging/chats/${chatId}/templates`, {
  body: {
    templateId: "seu_template_id",
    commonVariables: {
      var1: "Promoção de maio",
    },
  },
});
O endpoint e o contrato estão na Referência da API (POST /v1/messaging/chats/{chatId}/templates).

​
Submeter formulário público

const result = await client.forms.submitResponse(publicFormId, {
  name: "Maria Silva",
  phone: "+5581999999999",
  answers: [
    { questionKey: "interesse", value: "produto_a" },
  ],
});

console.log(result.submissionId, result.outcomes);

​
Webhooks

O SDK não envia webhooks — ele exporta os tipos dos eventos (SparkCRM.MessagesReceivedWebhook, etc.) para você tipar o handler depois de verificar a assinatura Svix. Detalhes em TypeScript — webhooks e tipos.

​
Onde ir depois