# Começando

> Faça a primeira chamada à API do FORSI Chat em 3 passos: crie a chave, guarde no servidor e mande uma mensagem de WhatsApp com cURL, JavaScript ou Python.

A API do FORSI Chat é uma API REST, em JSON e só por https. Com ela o seu sistema faz pelo código o que a sua equipe faz na tela: manda mensagens de WhatsApp, lê conversas e contatos, mexe no funil, na agenda e na equipe, puxa relatórios e recebe avisos por webhook assinado.

Endereço base: `https://chat.forsi.com.br/api/v1`

## Primeira chamada em 3 passos

1. Um dono ou gestor cria uma chave em **Configurações → API e webhooks → Nova chave** (planos com o módulo API). A chave aparece uma vez só.
2. Guarde a chave numa variável de ambiente do seu servidor. Ela é secreta: nunca coloque no site, no app ou no navegador.
3. Confira a chave com [`GET /me`](https://docs.forsi.com.br/api/conta/me) e mande a primeira mensagem:

```bash title="terminal"
export FORSI_CHAVE="fcv2_live_EXAMPLE"   # troque pela sua chave

curl "https://chat.forsi.com.br/api/v1/me" -H "Authorization: Bearer $FORSI_CHAVE"

curl -X POST "https://chat.forsi.com.br/api/v1/mensagens" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{
    "telefone": "+55 31 98888-7777",
    "tipo": "texto",
    "texto": "Olá! Sua consulta está confirmada para amanhã às 9h."
  }'
```

## O que acontece depois do envio

> **Figura: O caminho de uma mensagem enviada.** O seu sistema chama POST /mensagens. A API responde 202 na hora e põe a mensagem na fila (status pendente). A FORSI entrega à Meta (enviada); a Meta avisa quando chega ao aparelho (entregue) e quando a pessoa lê (lida). Se algo der errado, o status vira falhou, com o motivo. Cada mudança chega ao seu webhook como o evento mensagem.status; também dá para consultar com GET /mensagens/{id}.

A resposta `202` quer dizer que a mensagem entrou na fila, não que chegou. Para acompanhar o resto do caminho, cadastre um [webhook](https://docs.forsi.com.br/webhooks) com o evento `mensagem.status` ou consulte [`GET /mensagens/{id}`](https://docs.forsi.com.br/api/mensagens/ver-mensagem). Se a rede cair no meio do envio, repita com a mesma `Idempotency-Key`: a mensagem não sai duas vezes (veja [Idempotência](https://docs.forsi.com.br/idempotencia)).

## Convenções

- Toda requisição leva `Authorization: Bearer <chave>`. Corpo em JSON com `Content-Type: application/json`.
- Resposta de sucesso: `{"dados": ...}`. Listas: `{"dados": [...], "proximo": "..."}` (veja [Paginação](https://docs.forsi.com.br/paginacao)).
- Resposta de erro: `{"erro": {"codigo": "...", "mensagem": "...", "requisicao_id": "..."}}` (veja [Erros](https://docs.forsi.com.br/erros)).
- Ids são UUID. Datas e horas são ISO 8601 em UTC (`2026-10-04T13:05:12.481Z`). Dinheiro vem em centavos (`valor_centavos`).
- Campos novos podem aparecer nas respostas a qualquer momento: o seu código deve ignorar o que não conhece.

## Vai usar uma IA para construir a integração?

Mande para ela o link [https://docs.forsi.com.br/llms-full.txt](https://docs.forsi.com.br/llms-full.txt): é esta documentação inteira num arquivo só, com todos os endpoints, exemplos e regras. Para um índice curto, use [https://docs.forsi.com.br/llms.txt](https://docs.forsi.com.br/llms.txt). Cada página também tem uma versão em Markdown: é só pôr `.md` no fim do endereço (por exemplo, [https://docs.forsi.com.br/api/mensagens/enviar-mensagem.md](https://docs.forsi.com.br/api/mensagens/enviar-mensagem.md)). O contrato formal está em [https://docs.forsi.com.br/openapi.json](https://docs.forsi.com.br/openapi.json) (OpenAPI 3.1).

## Perguntas frequentes

### Qual plano preciso para usar a API?

Um plano com o módulo API. Sem ele, toda chamada responde `403 modulo_fora_do_plano`. Funil e agenda pedem também os módulos Funil e Agenda.

### Posso chamar a API direto do navegador ou do app de celular?

Não. A chave é segredo de servidor, e chamadas com cabeçalho `Origin` são recusadas com `403 origem_nao_permitida`. O navegador fala com o seu servidor; o seu servidor fala com a API.

### Recebi 202 no envio. A mensagem foi entregue?

Ainda não. `202` quer dizer que a mensagem entrou na fila. O status passa para `enviada`, `entregue` e `lida` (ou `falhou`, com o motivo), e cada mudança chega pelo webhook `mensagem.status`.

### Como mando mensagem para quem nunca falou comigo?

Com um modelo aprovado pela Meta (`tipo: "modelo"`). Na API oficial do WhatsApp, texto livre só sai dentro da janela de 24 horas desde a última mensagem do contato; fora dela, a resposta é `422 janela_fechada`. Veja os seus modelos em [`GET /modelos`](https://docs.forsi.com.br/api/modelos/listar-modelos).

---

Página: https://docs.forsi.com.br/comecando · Índice: https://docs.forsi.com.br/llms.txt · Tudo num arquivo: https://docs.forsi.com.br/llms-full.txt