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
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:
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:
Filtrar por plataforma:
Tipos exportados
Cada método tem parâmetros e resposta tipados. Importe o namespace do pacote quando quiser anotar variáveis:
No editor, passe o mouse sobre client.entrypoints.list para ver docstrings geradas a partir da API.
Fluxos comuns
Criar ou atualizar um chat DM
Para muitos contatos no mesmo canal, enfileire o lote. A resposta só confirma quantos itens foram aceitos — o processamento é em background e não devolve IDs:
Enviar mensagem de texto
Enviar mídia
- Faça upload:
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:
O endpoint e o contrato estão na Referência da API (POST /v1/messaging/chats/{chatId}/templates).
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