API pública do ChatISP

Visão geral

A API pública é o canal de máquina do ChatISP: permite que outro sistema do provedor trabalhe com o atendimento sem abrir o painel. Ela funciona nas duas direções:

• Do seu sistema para o ChatISP: chamadas HTTPS autenticadas por chave para enviar mensagens (texto, modelo aprovado da API oficial e arquivo), listar e consultar conversas com o histórico, transferir, encerrar, etiquetar e anotar atendimentos, abrir atendimentos na fila, consultar e renomear contatos, abrir e movimentar ordens de serviço, marcar compromissos na agenda e ler os indicadores do atendimento.
• Do ChatISP para o seu sistema: webhooks de saída. O ChatISP faz um POST assinado para o endereço que você cadastrar quando uma mensagem chega ou sai, quando uma conversa nasce, muda de dono ou é encerrada, e quando uma OS é aberto ou atualizado. Veja Webhooks de saída.

As 37 operações

Toda a API usa um endereço único; a operação é escolhida pelo parâmetro r, no formato recurso/acao. A coluna Escopo mostra a permissão que a chave precisa ter (veja Permissões da chave); "qualquer chave" quer dizer que basta a chave estar ativa.

Na coluna Método, GET indica uma leitura: ela também aceita POST. As operações marcadas com POST alteram algo e só aceitam POST.

Casos de uso típicos de um provedor

Programas completos para vários desses casos estão em Exemplos práticos.

Requisitos

Instalação própria e ChatISP Cloud

A API é a mesma nas duas formas de uso; muda só o endereço.

• Instalação própria (servidor do provedor): o endereço é o domínio pelo qual você acessa o painel. Sem domínio configurado, o servidor responde com certificado autoassinado e o seu sistema teria de aceitá-lo explicitamente. Configure um domínio com Let's Encrypt em Servidor antes de colocar a integração em produção.
• ChatISP Cloud: o endereço é o do seu painel hospedado pela Ravi Systems, já com certificado válido.

Nos dois casos, o endereço exato aparece no card API do ChatISP, em Endereço da API.

Criar uma chave de API

A chave é a única credencial da API: não há usuário, senha nem sessão. Crie uma chave para cada integração, com só as permissões que ela usa e um limite de chamadas por minuto.

Passo a passo

1. No menu lateral, abra Integrações.
2. Localize o card API do ChatISP ("Chaves para outros sistemas usarem a API: mensagens, conversas, contatos, ordens de serviço, agenda e indicadores, cada chave com as suas permissões."). Logo abaixo do título aparece o Endereço da API, com o botão Documentação da API: anote o endereço, é a URL que a integração vai chamar.
3. Clique em Nova chave.
4. Preencha o Nome (até 120 caracteres) com algo que identifique a integração, por exemplo "ERP financeiro" ou "NOC". Esse nome aparece no histórico de tudo o que a chave fizer.
5. Ligue as permissões que a integração usa. Elas estão em três grupos: Atendimento, Ordens de serviço e agenda e Gestão. Numa chave nova, Enviar mensagens, Consultar conversas e Abrir atendimentos vêm ligadas; as demais vêm desligadas. A tabela completa está em Permissões da chave.
6. Ajuste o Limite por minuto ("Chamadas aceitas por minuto. 0 desliga o limite."). O padrão é 60 e o máximo é 10000.
7. Clique em Salvar. A janela Chave criada mostra a chave completa no campo Chave de API. Clique em Copiar e guarde-a no sistema que vai usar a API.

cisp_7f3a9c21d84e0b56a1f2c3d4e5f60718293a4b5c6d7e8f90

Toda chave começa com cisp_, seguido de 48 caracteres hexadecimais. A lista do card mostra só o começo (por exemplo cisp_7f3a9…) para você reconhecer qual é qual.

A lista de chaves

Revelar, editar e excluir

• Revelar mostra de novo a chave completa, com o botão Copiar, a qualquer momento, para quem tem a permissão Integrações.
• Editar muda nome, permissões, limite por minuto e o switch Ativa. A chave em si não muda: a integração segue funcionando com o mesmo valor, já com as permissões novas. Desligar Ativa suspende a chave na hora (HTTP 401 chave_invalida) sem apagá-la, e ela deixa de contar no limite do plano.
• Excluir pede confirmação ("Excluir esta chave? As integrações que a usam param de funcionar.") e revoga a chave imediatamente.

Permissões da chave (escopos)

Cada permissão da tela corresponde a um escopo, um código estável que a API usa para decidir o que a chave pode fazer. O código aparece no campo escopos de chave/info e no erro permissao, que informa qual escopo faltou.

Os escopos são independentes: Gerenciar ordens de serviço não inclui Consultar ordens de serviço, por exemplo. Uma integração que abre ordens de serviço e depois acompanha o andamento deles precisa dos dois.

Catálogos: liberados para qualquer chave

As rotas de catálogo (chave/info, conexoes/listar, departamentos/listar, atendentes/listar, modelos/listar, etiquetas/listar e motivos/listar) não exigem escopo: qualquer chave ativa pode chamá-las, mesmo com todas as permissões desligadas. Elas devolvem os ids que as outras rotas pedem (conexao_id, departamento_id, atendente_id, modelo_id, etiqueta_id, motivo_id); sem eles nenhuma integração conseguiria montar as chamadas. A tela lembra isso logo abaixo das permissões: "Conexões, departamentos, atendentes, modelos, etiquetas e motivos ficam disponíveis para qualquer chave ativa." Referência em Catálogos.

Quantas chaves criar

• Uma por integração, com nome claro: assim você limita, suspende ou revoga um sistema sem derrubar os outros, e o histórico das conversas mostra qual sistema fez cada ação.
• Separe leitura de escrita quando sistemas diferentes fazem cada coisa. Um painel de BI só precisa de Consultar conversas e Indicadores; o ERP que manda boletos só precisa de Enviar mensagens.

Endereço e autenticação

Todas as chamadas vão para o mesmo endereço, mostrado no card API do ChatISP:

https://<endereço do seu painel>/api_publica.php?r=<recurso>/<acao>

A chave vai no cabeçalho HTTP Authorization, no esquema Bearer. Nunca vai na URL nem no corpo:

Authorization: Bearer cisp_7f3a9c21d84e0b56a1f2c3d4e5f60718293a4b5c6d7e8f90

Não há login nem sessão: cada chamada é independente.

Primeira chamada

A rota chave/info é a ideal para validar endereço e chave: não exige permissão, não altera nada e mostra o que a chave pode fazer.

curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=chave/info" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

<?php
// Cliente mínimo reaproveitável nas outras rotas
function chatisp(string $rota, array $dados = [], string $metodo = 'GET'): array {
    $base  = 'https://atendimento.seuprovedor.com.br/api_publica.php';
    $chave = getenv('CHATISP_CHAVE');
    $url   = $base . '?r=' . $rota;
    $ch    = curl_init();
    $opcoes = [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $chave, 'Content-Type: application/json'],
    ];
    if ($metodo === 'POST') {
        $opcoes[CURLOPT_POST]       = true;
        $opcoes[CURLOPT_POSTFIELDS] = json_encode($dados);
    } elseif ($dados) {
        $url .= '&' . http_build_query($dados);
    }
    $opcoes[CURLOPT_URL] = $url;
    curl_setopt_array($ch, $opcoes);
    $corpo  = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $resposta = json_decode((string) $corpo, true) ?? ['ok' => false, 'error' => 'resposta_invalida'];
    $resposta['_http'] = $status;
    return $resposta;
}

$info = chatisp('chave/info');
if (!$info['ok']) {
    die("Erro {$info['_http']}: {$info['error']}\n");
}
echo $info['chave']['nome'], ': ', implode(', ', $info['chave']['escopos']), PHP_EOL;

import os, requests

BASE  = "https://atendimento.seuprovedor.com.br/api_publica.php"
CHAVE = os.environ["CHATISP_CHAVE"]

def chatisp(rota, dados=None, metodo="GET"):
    cab = {"Authorization": f"Bearer {CHAVE}"}
    if metodo == "POST":
        r = requests.post(BASE, params={"r": rota}, json=dados or {}, headers=cab, timeout=30)
    else:
        r = requests.get(BASE, params={"r": rota, **(dados or {})}, headers=cab, timeout=30)
    corpo = r.json()
    corpo["_http"] = r.status_code
    return corpo

info = chatisp("chave/info")
if not info["ok"]:
    raise SystemExit(f"Erro {info['_http']}: {info['error']}")
print(info["chave"]["nome"], info["chave"]["escopos"])

{
  "ok": true,
  "chave": {
    "id": 3,
    "nome": "ERP financeiro",
    "prefixo": "cisp_7f3a9…",
    "escopos": ["mensagens_enviar", "conversas_ler", "atendimentos_abrir"],
    "cota_minuto": 60
  },
  "servidor": {
    "api_versao": "1",
    "fuso_horario": "America/Sao_Paulo",
    "agora": "2026-10-01T09:30:12-03:00",
    "plano": "PREMIUM"
  }
}

Ordem de validação

Toda chamada passa por estas verificações, nesta ordem. A primeira que falhar define a resposta:

1. r ausente ou fora do formato recurso/acao: HTTP 404 rota.
2. Cabeçalho Authorization: Bearer ... ausente ou malformado: HTTP 401 autenticacao.
3. Chave inexistente, excluída, inativa ou fora do formato cisp_...: HTTP 401 chave_invalida.
4. Plano sem API pública ou licença bloqueada: HTTP 403 plano.
5. A chamada é contada no uso da chave. Se passou do limite por minuto: HTTP 429 cota_excedida.
6. Corpo declarado como JSON, mas inválido: HTTP 400 json_invalido.
7. Rota inexistente: HTTP 404 rota.
8. Rota de escrita chamada sem POST: HTTP 405 metodo.
9. Chave sem o escopo da rota: HTTP 403 permissao, com o escopo que faltou.
10. A operação valida os próprios parâmetros e executa.

Formato da requisição

Métodos

• Leitura (listar, consultar, catálogos, indicadores, baixar arquivo): GET ou POST.
• Escrita (enviar, transferir, encerrar, criar, mover...): só POST. Com outro método, a resposta é HTTP 405 metodo com "esperado":"POST".

Onde vão os parâmetros

A query string vale em qualquer método. Quando o mesmo parâmetro vem na query e no corpo, o corpo vence. Um corpo com Content-Type: application/json que não seja um objeto JSON válido é recusado com HTTP 400 json_invalido.

# formulário
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=mensagens/enviar" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -d "telefone=44999990000" -d "texto=Olá! Seu técnico está a caminho."

# JSON
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=mensagens/enviar" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"telefone":"44999990000","texto":"Olá! Seu técnico está a caminho."}'

Tipos de parâmetro

Formato da resposta

Toda resposta é JSON (Content-Type: application/json; charset=utf-8, Cache-Control: no-store) com um envelope igual em todas as rotas:

O campo error é sempre um código estável, sem acento e sem tradução, pensado para o seu sistema decidir o que fazer. Os campos extras ajudam a corrigir a chamada: campo (qual parâmetro), aceitos (valores permitidos), maximo, esperado, escopo, entre outros. Acentos vêm sem escape ("Suporte técnico") e barras também.

HTTP 400  {"ok":false,"error":"parametro_invalido","campo":"estado","aceitos":["ia","fila","humano","encerrada","auto"]}
HTTP 403  {"ok":false,"error":"permissao","escopo":"tickets_gerir"}
HTTP 404  {"ok":false,"error":"nao_encontrado"}

Status HTTP

O status HTTP é real e coerente com o resultado: confira o status e o campo ok.

Respostas que não são JSON

Só mensagens/arquivo: em caso de sucesso devolve o próprio arquivo, com Content-Type do arquivo (imagens e PDF) ou application/octet-stream (demais tipos) e Content-Disposition com o nome original. Em caso de erro, devolve o envelope JSON normal.

Objetos que se repetem

As rotas de mensagens, conversas e contatos devolvem a conversa e a mensagem sempre com os mesmos campos (os detalhes estão em Conversas e Mensagens). Valores que você vai encontrar:

Paginação e cursor

Paginação numerada

As listagens grandes (conversas/listar, contatos/listar, tickets/listar e agenda/listar) usam página e limite:

A resposta traz o bloco paginacao:

"paginacao": {
  "pagina": 2,
  "limite": 50,
  "total": 137,
  "paginas": 3
}

total é a quantidade de registros que atendem aos filtros e paginas é quantas páginas existem com esse limite (0 quando não há registros). Para percorrer tudo, chame até pagina chegar em paginas. Página além da última devolve a lista vazia, sem erro.

Cursor do histórico de mensagens

O histórico de uma conversa (conversas/mensagens) usa cursor pelo id da mensagem, que não se desloca quando chegam mensagens novas:

"tem_mais": true,
"cursor": {
  "antes_de": 402801,
  "depois_de": 402850
}

tem_mais diz se ainda há mensagens na direção pedida. Para continuar rolando para trás, passe cursor.antes_de no próximo antes_de; para acompanhar as novas, guarde cursor.depois_de e use-o como depois_de na próxima consulta. As mensagens vêm sempre em ordem cronológica (da mais antiga para a mais nova).

Datas e fuso horário

Datas na resposta

Todas as datas de saída vêm em ISO 8601 com o fuso do servidor, por exemplo 2026-10-01T09:12:40-03:00. Datas ausentes vêm como null. O fuso do servidor aparece em chave/info (servidor.fuso_horario), junto com o relógio dele (servidor.agora), útil para conferir diferença de horário com o seu sistema.

Datas na requisição

Anos fora de 2000 a 2100 ou texto que não é data respondem HTTP 400 data_invalida com o campo. Períodos com fim antes do início, ou maiores que o permitido pela rota (366 dias em indicadores e agenda), respondem periodo_invalido.

Telefones

O telefone segue a mesma regra da tela do painel. Pontuação, espaços e parênteses são ignorados.

Regras dos números brasileiros: DDD de 11 a 99 (sem zero) e, quando o número tem 11 dígitos, o terceiro precisa ser o 9 do celular. Fora disso, a resposta é HTTP 400 telefone_invalido. Sem o +, um número que não se encaixa como brasileiro também é recusado, para não enviar mensagem ao país errado.

Nas consultas por telefone (conversas, contatos), o ChatISP procura o número com e sem o nono dígito, porque o WhatsApp de alguns celulares antigos ainda usa o formato de 8 dígitos. Nas respostas, o telefone vem só com dígitos e com o código do país, no formato em que a conversa está registrada.

Códigos de erro

Lista completa dos valores possíveis de error. Cada página da referência mostra quais erros cada rota pode devolver.

Limites

Limite por minuto da chave

Cada chave tem o seu Limite por minuto (padrão 60, máximo 10000, 0 sem limite). A contagem é por minuto do relógio do servidor: zera quando o minuto vira (às 10:41:00, às 10:42:00...), não numa janela móvel de 60 segundos.

Com limite definido, toda resposta traz os cabeçalhos:

Chave com limite 0 não recebe os cabeçalhos X-RateLimit-*.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Content-Type: application/json; charset=utf-8

{"ok":false,"error":"cota_excedida","cota_minuto":60}

A chamada recusada não foi executada: espere o Retry-After e repita. As recusas também contam no minuto, então repetir em laço sem esperar não adianta.

Tamanhos e quantidades

Ritmo de envio em massa

A API envia cada mensagem na hora em que é chamada. Para avisos a muitos assinantes, espalhe os envios no tempo em vez de disparar centenas de chamadas simultâneas, e ajuste o limite por minuto da chave a esse ritmo. Para listas grandes com acompanhamento de entregas e respostas, a tela Automação de envios já faz o ritmo sozinha.

Versão da API

Toda resposta, inclusive as de erro, traz o cabeçalho:

X-ChatISP-Api-Versao: 1

O mesmo valor aparece em chave/info, no campo servidor.api_versao. A versão atual é a 1. Registre o valor nos logs da integração: ele ajuda o suporte a identificar com qual versão o seu sistema conversou.

As rotas, os nomes de campo e os códigos de erro documentados aqui são estáveis. A API pode ganhar rotas, parâmetros opcionais e campos novos nas respostas sem mudar de versão; por isso o seu sistema deve ignorar campos desconhecidos em vez de recusar a resposta. Campos antigos são mantidos para quem já integrou: por exemplo, atendimentos/abrir segue devolvendo conversa_id, protocolo, estado e ja_existia no nível de cima, além do objeto conversa completo.

Segurança e boas práticas

Checklist

• Uma chave por integração, com Nome claro e só os escopos necessários.
• Guarde a chave em variável de ambiente ou cofre de segredos do servidor, nunca no código versionado nem em logs.
• Use sempre HTTPS. Em instalação própria, configure domínio com certificado válido antes da produção.
• Limite por minuto compatível com o uso real: ele também protege contra um laço descontrolado no seu sistema.
• Confira ok e o status HTTP em toda resposta; decida pelo código de error.
• Em 429, respeite o Retry-After. Em erro de rede ou HTTP 5xx, repita leituras com espera crescente. Não repita envios às cegas: uma mensagem que deu timeout pode ter sido entregue, e repetir duplica o envio ao cliente. Antes, confira o histórico com conversas/mensagens.
• Guarde os ids devolvidos (conversa_id, mensagem_id, ticket_id) para cruzar com os webhooks.
• Faça cache dos catálogos (departamentos, atendentes, etiquetas, motivos) e atualize de tempos em tempos, em vez de consultá-los a cada chamada.
• Prefira webhooks a consultar em laço para saber o que mudou.
• Desative ou exclua as chaves de integrações desligadas. Para trocar uma chave, crie a nova, atualize a integração e só então exclua a antiga.

O que fica registrado

As ações feitas pela API aparecem no painel com o nome da chave: o evento "API" na linha do tempo da conversa, as notas como "API (nome da chave): ...", as transferências e encerramentos com "API: nome da chave", e os comentários de OS com "[API: nome da chave]". As mensagens enviadas pela API saem como autor sistema, sem assinatura de atendente.

Problemas frequentes

Coleção para Postman e Insomnia

Para testar a API sem escrever código, baixe a coleção pronta com as 37 rotas, já com método, parâmetros de exemplo e descrição de cada uma:

Baixar a coleção (chatisp-api.postman_collection.json)

1. No Postman, use Import e escolha o arquivo. No Insomnia, use Import em uma coleção; o formato do Postman é reconhecido.
2. Nas variáveis da coleção, preencha base_url com o endereço do seu painel (por exemplo https://atendimento.seuprovedor.com.br, sem barra no final) e chave com a sua chave cisp_....
3. Rode primeiro Informações da chave (chave/info) para confirmar endereço, chave e escopos.
4. Use os catálogos para descobrir os ids reais da sua instalação antes de testar as rotas de escrita.