> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crmspark.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript — começar

> Instale o pacote sparkcrm no npm, configure a chave de API e faça a primeira chamada à API pública do Spark.

O cliente oficial [`sparkcrm`](https://www.npmjs.com/package/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](https://github.com/gepetojj/spark-typescript).

## Requisitos

* **TypeScript** ≥ 4.9 (recomendado para aproveitar os tipos exportados).
* **Node.js** 20 LTS ou superior, ou runtimes compatíveis: [Bun](https://bun.sh), [Deno](https://deno.com), 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

```sh theme={null}
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:

```ts theme={null}
import SparkCRM from "sparkcrm";

const client = new SparkCRM({
  apiKey: process.env.SPARK_API_KEY, // ou SPARK_API_KEY no ambiente
});
```

| Opção / variável                 | Função                                                         |
| -------------------------------- | -------------------------------------------------------------- |
| `apiKey` / `SPARK_API_KEY`       | Chave enviada no cabeçalho `X-API-Key` em todas as requisições |
| `baseURL` / `SPARK_CRM_BASE_URL` | URL base da API (padrão: `https://gateway.crmspark.com.br`)    |

<Warning title="Chave secreta">
  Use `sk_…` apenas no backend. Nunca exponha chave secreta em apps mobile, front-end público ou repositórios.
</Warning>

## Primeira chamada

Listar os entrypoints (canais) da organização:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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

### Criar ou atualizar um chat DM

```ts theme={null}
const { chatId, leadId } = await client.chats.upsert({
  entrypointId: "wep_…",
  phone: "5511987654321",
  name: "Maria Silva",
});
```

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:

```ts theme={null}
const { queued } = await client.chats.upsertBatch({
  entrypointId: "wep_…",
  batch: [
    { phone: "5511987654321", name: "Maria Silva" },
    { phone: "5511912345678" },
  ],
});
```

### Enviar mensagem de texto

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

### Enviar mídia

1. Faça upload:

```ts theme={null}
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](/conceitos/modelos-de-mensagem).

Enquanto o método tipado `sendTemplate` estiver sendo publicado em novas versões do pacote, use o helper HTTP do cliente:

```ts theme={null}
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](/api-reference/introduction) (`POST /v1/messaging/chats/{chatId}/templates`).

### Submeter formulário público

```ts theme={null}
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](/api-reference/webhooks). Detalhes em [TypeScript — webhooks e tipos](/sdks/typescript/webhooks-e-tipos).

## Onde ir depois

* [Referência de recursos](/sdks/typescript/referencia) — todos os métodos e tipos por módulo
* [Erros, retentativas e uso avançado](/sdks/typescript/configuracao-avancada)
* [Introdução à API](/api-reference/introduction) — chaves, limites e OpenAPI interativo