Pular para o conteúdo

API pública e webhooks A chave no cabeçalho.
O evento na sua URL.

A API pública responde na sua própria instalação, autenticada por chave no cabeçalho Authorization: Bearer: 37 operações sobre mensagens, conversas, contatos, tickets, agenda e indicadores. Na volta, nove eventos saem por webhook assinado. Tudo a partir do plano Premium.

Referência completa da API Onde a API entra nos planos
  • 37 operações
  • 9 eventos de webhook
  • A partir do Premium

O endereço da API é o da sua instalação (no ChatISP Cloud, o do seu painel). A referência completa, com cada operação, parâmetros, respostas, erros e exemplos em curl, PHP e Python, é pública e fica na documentação.

Chamada real, dados fictícios requisição 
POST /api_publica.php?r=mensagens/enviar HTTP/1.1
Host: atendimento.seuprovedor.com.br
Authorization: Bearer cisp_<a-sua-chave>
Content-Type: application/json

{ "telefone": "44999990000",
  "texto": "Visita técnica confirmada: amanhã, 9h." }

{ "ok": true, "conversa_id": 1234,
  "protocolo": "20261001-0042", "mensagem_id": 98765, ... }
Autenticação

Uma chave.
Um cabeçalho.

A API pública responde em /api_publica.php?r=recurso/acao, no domínio da sua instalação. Cada chamada leva a chave no cabeçalho Authorization: Bearer; as respostas são JSON com status HTTP de verdade, códigos de erro estáveis e datas em ISO 8601.

As chaves são administradas no painel, em Integrações: criar, editar, ativar, desativar, revelar o valor e excluir. Desativar não é excluir: a integração para de responder e o cadastro continua lá, com a contagem de utilização que já tinha.

Autenticação, formato e erros na referência
Endereço
/api_publica.php?r=recurso/acao. O host é o da sua instalação.
Autenticação
Chave cisp_ no cabeçalho Authorization: Bearer.
Formato
Parâmetros por query, formulário ou JSON. Resposta em JSON, paginação numerada e cursor no histórico de mensagens.
Permissões
Dez escopos marcados chave a chave, em três grupos: atendimento, tickets e agenda, gestão.
Ritmo
Cota de chamadas por minuto por chave, com os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining.
Quantas chaves
Três no Premium, dez no Gold, sem limite no Enterprise. Basic e Normal não têm API pública.
O que a API cobre

O que a tela faz,
o seu sistema também.

As operações chamam as mesmas regras que o painel usa: a transferência entra na fila do mesmo jeito, o ticket avisa a mesma equipe e o indicador é o mesmo número da tela de Relatórios.

Catálogos

Conexões, departamentos, atendentes, modelos aprovados, etiquetas e motivos: os ids que o resto pede.

Mensagens

Texto, modelo aprovado da API oficial e arquivo (multipart ou base64). Baixar o arquivo de qualquer mensagem.

Conversas

Listar com filtros e sincronização incremental, histórico por cursor, transferir, encerrar, etiquetar, nota interna, abrir atendimento.

Contatos

Um contato por número, com e sem o nono dígito juntos, o histórico de protocolos e o nome que a equipe salvou.

Tickets

Abrir pelo NOC ou pelo ERP, mover de etapa, atribuir, comentar e ler a linha do tempo.

Agenda

Marcar visita técnica ou retorno, com confirmação ao cliente, e concluir ou cancelar.

Indicadores

O resumo da tela de Relatórios para um período de até um ano, pronto para o seu BI.

Webhooks

Nove eventos assinados com HMAC, reenvio com espera crescente e identificador de entrega para não processar duas vezes.

Exemplos prontos

Receitas completas em PHP, Python e Node: aviso de manutenção, ERP, NOC, portal do assinante e CRM.
Permissões da chave

Uma chave por integração.
Só o que ela usar.

Os escopos são independentes. Uma chave que só envia mensagem não lê conversa; uma chave que só lê indicadores não toca no atendimento. Os catálogos (conexões, departamentos, atendentes, modelos, etiquetas e motivos) valem para qualquer chave ativa.

Atendimento

Enviar mensagens (texto, modelo aprovado e arquivo), consultar conversas e o histórico, abrir atendimentos, gerenciar conversas (transferir, encerrar, etiquetar, anotar) e contatos.

Tickets e agenda

Consultar e gerenciar tickets (abrir, mover de etapa, atribuir, comentar) e a agenda da equipe (marcar, concluir e cancelar compromissos).

Gestão

Indicadores do atendimento num período: volumes, tempos em horário útil, satisfação e números por departamento e por atendente.

Cada chave carrega a própria cota de chamadas por minuto e a própria contagem de utilização. Dá para ver quanto cada integração consome sem desligar nada. O valor da chave pode ser revelado outra vez no painel, então uma chave perdida não obriga a refazer a integração inteira.

Webhooks de saída

Nove eventos.
Assinados e com reenvio.

Você cadastra a URL, escolhe os eventos e guarda o segredo. Cada entrega vai com a assinatura HMAC em X-ChatISP-Assinatura; se a sua URL falhar, o ChatISP tenta de novo com espera crescente. Os eventos saem do que acontece no painel, na IA e na própria API.

  • mensagem recebida
  • mensagem enviada
  • entrega e leitura
  • conversa criada
  • conversa atribuída
  • conversa transferida
  • conversa encerrada
  • ticket aberto
  • ticket atualizado
Entrega real, dados fictícios webhook: o que chega na sua URL 
POST /a-sua-url HTTP/1.1
Content-Type: application/json; charset=utf-8
X-ChatISP-Evento: mensagem_recebida
X-ChatISP-Entrega: 5821
X-ChatISP-Assinatura: sha256=<HMAC do corpo com o seu segredo>

{ "evento": "mensagem_recebida",
  "emitido_em": "2026-10-01T09:14:02-03:00",
  "dados": { "conversa_id": 1234, "protocolo": "20261001-0042",
    "telefone": "5544999990000", "estado": "fila",
    "mensagem": { "id": 98766, "tipo": "texto",
      "conteudo": "Minha internet caiu" } } }

Os campos de cada evento, o código de verificação da assinatura em PHP, Node e Python e as regras de reenvio estão na referência dos webhooks.

O caminho de volta

Quando é o ChatISP
que precisa chamar você.

Nem toda integração é o seu sistema chamando o ChatISP. Do outro lado existe o cadastro de sistemas externos: você descreve as operações do seu serviço em JSON e o ChatISP passa a chamá-las.

A etapa Consultar sistema do editor de fluxo executa uma dessas operações com parâmetros e trata a resposta e a falha. O campo que voltou pode ser usado nas mensagens seguintes, e o atendimento assistido também alcança essas operações.

É por aqui que as 22 operações do Financeiro da Ravi Systems funcionam na instalação da própria Ravi Systems: como sistema externo cadastrado, não como integração nativa do ChatISP. O seu ERP entra pelo mesmo caminho e dá o mesmo trabalho.

As etapas do editor de fluxo

O cadastro de um sistema externo

  • Nome e URL base o endereço para onde o ChatISP vai falar
  • Cabeçalhos adicionais e tempo limite definidos no cadastro daquele sistema
  • Autenticação sem credencial, Bearer, Basic ou um cabeçalho próprio
  • Operações descritas em JSON método, caminho, parâmetros e respostas
  • Ativação e alcance cada sistema é ligado à parte e pode ficar disponível para a IA
  • Tela de teste execute a operação com parâmetros e veja o resultado
Disponibilidade

Começa no Premium.

Basic e Normal não têm API pública nem webhooks. Do Premium para cima, o que muda é quantas chaves você mantém ao mesmo tempo.

A tabela completa de planos
Duas linhas da tabela de planos do ChatISP. Os demais limites estão na página de planos.
Recurso Basic Normal Premium Gold Enterprise
API pública e webhooks Não Não Sim Sim Sim
Chaves de API Nenhuma Nenhuma 3 10 Sem limite
Como ligar

Do zero à
primeira chamada.

Três coisas no painel e uma na sua ferramenta de testes, antes de escrever qualquer linha de integração.

  1. Crie a chave

    Em Integrações, API do ChatISP: dê um nome e marque só os escopos que aquela integração usa. O valor pode ser revelado de novo depois, e a chave pode ser desativada sem ser excluída.

  2. Importe a coleção

    A coleção do Postman (o Insomnia também importa) traz as 37 operações prontas: preencha o endereço do painel e a chave e chame chave/info.

  3. Cadastre o webhook

    Nome, URL, os eventos que interessam e a situação ativa. Guarde o segredo: é com ele que você valida a assinatura que chega em X-ChatISP-Assinatura.

  4. Dispare o teste

    O painel tem um comando de teste do webhook e mostra o resultado do último disparo. Dá para confirmar que o seu endereço respondeu antes de depender dele.

A referência da API traz cada operação com parâmetros, respostas, códigos de erro e exemplos em curl, PHP e Python, além de receitas completas para provedor: aviso de manutenção, cliente bloqueado no ERP, ticket aberto pelo NOC, portal do assinante e sincronização com CRM. As outras camadas de integração estão aqui.

Continue por aqui

Integrações

Três camadas: contexto do assinante, financeiro no atendimento e conexão com outros sistemas.

 Fluxos de autoatendimento

Menus, horários, consultas a sistemas e saída para humano desenhados na tela.

 Segurança e dados

O mapa inteiro: o que fica no seu servidor e as três situações em que algo sai.

 Planos e preços

Cinco planos, mensal ou anual com 35% de desconto em pagamento único.

Leia também

Tecnologia e dados

Onde ficam os dados do assinante quando o atendimento é por WhatsApp

Quase todo fornecedor diz que os dados estão seguros. Bem poucos dizem em qual servidor eles estão.

7 min de leitura Tecnologia e dados

Onde a inteligência artificial ajuda de verdade num provedor

Entre o discurso de que a IA resolve tudo e o medo de que ela estrague o atendimento, existe um conjunto pequeno e bem definido de tarefas em que ela é ótima.

8 min de leitura Operação do atendimento

Por que o suporte melhora quando a rede aparece na conversa

A primeira pergunta do suporte quase sempre é a mesma. E quase sempre já tem resposta antes de alguém perguntar.

7 min de leitura
Próximo passo

Antes de escrever
a primeira linha.

Conte qual sistema você quer ligar ao ChatISP e em que direção. A equipe diz qual caminho resolve: a API pública, os webhooks ou o cadastro de sistema externo.

Download Falar com a equipe primeiro

O teste começa na instalação e não gera obrigação de contratar.