TypeScript — referência de recursos - Documentação Spark CRM

Esta página descreve a superfície atual do pacote sparkcrm, alinhada ao OpenAPI do gateway. A árvore de chamadas segue o padrão client.<recurso>.<método>(). Para autenticação, instalação e exemplos iniciais, veja Começar com TypeScript.

Visão geral do cliente

import SparkCRM from "sparkcrm";

const client = new SparkCRM({ apiKey: "sk_…" });

client.entrypoints   // canais (entrypoints)
client.forms         // formulários públicos
client.messaging     // mídia + chats
// client.webhooks   → apenas tipos exportados (sem métodos HTTP)

Entrypoints

Canais de entrada configurados na organização (WhatsApp Business, WhatsApp Lite, Instagram, Telegram).

`client.entrypoints.list(params?)`

HTTP: GET /v1/entrypoints

Parâmetro (`EntrypointListParams`)	Tipo	Descrição
`platform`	`"whatsapp"` \| `"whatsapp_lite"` \| `"instagram"` \| `"telegram"`	Filtra por plataforma

Retorno: EntrypointListResponse com entrypoints[] (id, name, platform, funnelStepId, displayName?, state? em WhatsApp Lite).

const all = await client.entrypoints.list();
const ig = await client.entrypoints.list({ platform: "instagram" });

`client.entrypoints.retrieve(id)`

HTTP: GET /v1/entrypoints/{id} Retorno: EntrypointRetrieveResponse com entrypoint discriminado por platform (campos extras como isCoexistence no WhatsApp Business, state no Lite).

const { entrypoint } = await client.entrypoints.retrieve("ep_…");

Forms (formulários)

Formulários de captação publicados com ID público de 16 caracteres. Conceito de produto: Formulários de captação.

`client.forms.retrieve(id)`

HTTP: GET /v1/forms/{id} Retorno: FormRetrieveResponse — form com name, description, flow (nós e conexões do canvas) e iframeEmbedAllowedOrigins.

const { form } = await client.forms.retrieve(publicFormId);

`client.forms.retrieveEmbedFramePolicy(id)`

HTTP: GET /v1/forms/{id}/embed-frame-policy Retorno: FormRetrieveEmbedFramePolicyResponse — lista de origens HTTPS permitidas para iframe (vazia = sem restrição por origem).

const policy = await client.forms.retrieveEmbedFramePolicy(publicFormId);

`client.forms.submitResponse(id, body)`

HTTP: POST /v1/forms/{id}/submit → 201

Campo (`FormSubmitResponseParams`)	Obrigatório	Descrição
`name`	sim	Nome do lead
`phone`	sim	Telefone (formato aceito pelo backend)
`answers`	não	Respostas das perguntas (`questionKey` + `value` string ou string[])

Retorno: FormSubmitResponseResponse — submissionId e outcomes[] com platform, leadId, chatId por destino WhatsApp.

const result = await client.forms.submitResponse(publicFormId, {
  name: "João",
  phone: "5581987654321",
  answers: [{ questionKey: "porte", value: "pequena" }],
});

Messaging

`client.messaging.uploadMedia(body)`

HTTP: POST /v1/messaging/media (multipart)

Campo	Descrição
`files`	Array de arquivos (`Uploadable`: `File`, `Blob`, buffer, stream conforme runtime)

Retorno: MessagingUploadMediaResponse — array por arquivo: { success: true, id, name, url } ou { success: false, name }. Use os id retornados em sendMessage (mediaIds ou audioId).

const results = await client.messaging.uploadMedia({
  files: [file],
});

`client.messaging.chats.listMessages(chatId, params?)`

HTTP: GET /v1/messaging/chats/{chatId}

Parâmetro	Descrição
`limit`	Tamanho da página (1–50; padrão 20)
`cursor`	Cursor para mensagens mais antigas

Retorno: ChatListMessagesResponse — records[] (mensagem completa com text, type, status, media, sender, etc.) e nextCursor?. Mensagens vêm mais recentes primeiro.

const page = await client.messaging.chats.listMessages(chatId, {
  limit: 30,
});

if (page.nextCursor) {
  const older = await client.messaging.chats.listMessages(chatId, {
    cursor: page.nextCursor,
  });
}

`client.messaging.chats.sendMessage(chatId, body)`

HTTP: POST /v1/messaging/chats/{chatId} → 204

Campo (`ChatSendMessageParams`)	Descrição
`text`	Texto da mensagem
`mediaIds`	IDs de mídia do upload
`audioId`	Áudio único (sem `text` nem outras mídias)
`replyToId`	Responder a uma mensagem
`delay`	Atraso em segundos antes do envio
`instagramDelivery`	`"dm"` \| `"comment_reply"` \| `"private_reply"`
`instagramSourceMessageId`	ID da mensagem de origem no Instagram

await client.messaging.chats.sendMessage(chatId, {
  text: "Confirmado para amanhã às 10h.",
  replyToId: messageId,
});

Enviar modelo de mensagem (`templates`)

HTTP: POST /v1/messaging/chats/{chatId}/templates → 204 Corpo (espelha SendPublicTemplateBodyDto na API):

Campo	Obrigatório	Descrição
`templateId`	sim	ID do modelo no Spark
`commonVariables`	não	Variáveis manuais: `var1`, `var2`, …
`replyToId`	não	Responder em thread

Variáveis automáticas não vão no body — o Spark preenche com dados do chat. Veja Modelos de mensagem.

await client.post(`/v1/messaging/chats/${chatId}/templates`, {
  body: {
    templateId: "tpl_…",
    commonVariables: {
      var1: "Black Friday",
      var2: "20OFF",
    },
  },
});

Novas versões do sparkcrm podem expor client.messaging.chats.sendTemplate(chatId, body) com o mesmo contrato. Confira o api.md da versão instalada.

Tabela rápida de métodos

Método SDK	Verbo / caminho
`entrypoints.list`	`GET /v1/entrypoints`
`entrypoints.retrieve`	`GET /v1/entrypoints/{id}`
`forms.retrieve`	`GET /v1/forms/{id}`
`forms.retrieveEmbedFramePolicy`	`GET /v1/forms/{id}/embed-frame-policy`
`forms.submitResponse`	`POST /v1/forms/{id}/submit`
`messaging.uploadMedia`	`POST /v1/messaging/media`
`messaging.chats.listMessages`	`GET /v1/messaging/chats/{chatId}`
`messaging.chats.sendMessage`	`POST /v1/messaging/chats/{chatId}`
Envio de template	`POST /v1/messaging/chats/{chatId}/templates`

Requisições fora do catálogo tipado

O cliente expõe get, post, put, patch, delete com as mesmas opções de retry, timeout e cabeçalhos — útil para endpoints novos antes de uma release do SDK:

await client.get("/v1/entrypoints", { query: { platform: "telegram" } });

Parâmetros não documentados podem ser enviados com // @ts-expect-error ou via query / body / headers explícitos, conforme a documentação avançada.

Tipos principais exportados

Importe de sparkcrm ou use o namespace SparkCRM:

Área	Tipos úteis
Entrypoints	`EntrypointListResponse`, `EntrypointRetrieveResponse`, `EntrypointListParams`
Forms	`FormRetrieveResponse`, `FormSubmitResponseParams`, `FormSubmitResponseResponse`
Messaging	`ChatListMessagesResponse`, `ChatSendMessageParams`, `MessagingUploadMediaParams`, `MessagingUploadMediaResponse`
Webhooks	`SparkWebhookBody`, `MessagesReceivedWebhook`, `MessagesSentWebhook`, `ChatsCreatedWebhook`
Erros	`APIError`, `RateLimitError`, `AuthenticationError`, …

Lista completa no repositório: api.md.

​Visão geral do cliente

​Entrypoints

​client.entrypoints.list(params?)

​client.entrypoints.retrieve(id)

​Forms (formulários)

​client.forms.retrieve(id)

​client.forms.retrieveEmbedFramePolicy(id)

​client.forms.submitResponse(id, body)

​Messaging

​client.messaging.uploadMedia(body)

​client.messaging.chats.listMessages(chatId, params?)

​client.messaging.chats.sendMessage(chatId, body)

​Enviar modelo de mensagem (templates)

​Tabela rápida de métodos

​Requisições fora do catálogo tipado

​Tipos principais exportados

Visão geral do cliente

Entrypoints

`client.entrypoints.list(params?)`

`client.entrypoints.retrieve(id)`

Forms (formulários)

`client.forms.retrieve(id)`

`client.forms.retrieveEmbedFramePolicy(id)`

`client.forms.submitResponse(id, body)`

Messaging

`client.messaging.uploadMedia(body)`

`client.messaging.chats.listMessages(chatId, params?)`

`client.messaging.chats.sendMessage(chatId, body)`

Enviar modelo de mensagem (`templates`)

Tabela rápida de métodos

Requisições fora do catálogo tipado

Tipos principais exportados