Pular para o conteúdo
FORSI Chat

Começando

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 e mande a primeira mensagem:
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#

O caminho de uma mensagem enviadaO 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}.o seu webhook recebemensagem.statusSeu sistemaPOST /v1/mensagens202 na hora, com o idFORSI Chatpõe na fila de enviopendenteentrega à MetaMeta (WhatsApp)leva até o aparelhoenviadaa Meta confirmaCelular do clientechega e depois é lidaentreguelidaDeu errado?em qualquer etapa, com o motivofalhou
O caminho de uma mensagem enviada

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

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).
  • Resposta de erro: {"erro": {"codigo": "...", "mensagem": "...", "requisicao_id": "..."}} (veja 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: é 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. 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). O contrato formal está em 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.