ChatISP public API

Overview

The public API is ChatISP's machine channel: it lets another system of the ISP work with customer service without opening the panel. It works in both directions:

• From your system to ChatISP: HTTPS calls authenticated by key to send messages (text, official API approved template and file), list and look up conversations with their history, transfer, close, tag and annotate service requests, open service requests in the queue, look up and rename contacts, open and move service orders, book appointments on the calendar and read the customer service metrics.
• From ChatISP to your system: outgoing webhooks. ChatISP makes a signed POST to the address you register when a message arrives or is sent, when a conversation is created, changes owner or is closed, and when a service order is opened or updated. See Outgoing webhooks.

The 37 operations

The whole API uses a single address; the operation is chosen by the r parameter, in the recurso/acao (resource/action) format. The Scope column shows the permission the key must have (see Key permissions); "any key" means the key only needs to be active.

In the Method column, GET indicates a read: it also accepts POST. Operations marked POST change something and only accept POST.

Typical ISP use cases

Complete programs for several of these cases are in Practical examples.

Requirements

Self-hosted installation and ChatISP Cloud

The API is the same in both forms of use; only the address changes.

• Self-hosted installation (the ISP's own server): the address is the domain you use to access the panel. Without a configured domain, the server responds with a self-signed certificate and your system would have to accept it explicitly. Configure a domain with Let's Encrypt in Server before putting the integration into production.
• ChatISP Cloud: the address is that of your panel hosted by Ravi Systems, already with a valid certificate.

In both cases, the exact address appears on the ChatISP API card, under API address.

Create an API key

The key is the API's only credential: there is no user, password or session. Create one key per integration, with only the permissions it uses and a per-minute call limit.

Step by step

1. In the side menu, open Integrations.
2. Find the ChatISP API card ("Keys for other systems to use the API: messages, conversations, contacts, service orders, calendar and metrics, each key with its own permissions."). Right below the title is the API address, with the API documentation button: write down the address, it is the URL the integration will call.
3. Click New key.
4. Fill in the Name (up to 120 characters) with something that identifies the integration, for example "Billing ERP" or "NOC". This name appears in the history of everything the key does.
5. Turn on the permissions the integration uses. They are in three groups: Customer service, Service orders and calendar and Management. On a new key, Send messages, Look up conversations and Open service requests come turned on; the others come turned off. The complete table is in Key permissions.
6. Adjust the Per-minute limit ("Calls accepted per minute. 0 turns the limit off."). The default is 60 and the maximum is 10000.
7. Click Save. The Key created window shows the full key in the API key field. Click Copy and store it in the system that will use the API.

cisp_7f3a9c21d84e0b56a1f2c3d4e5f60718293a4b5c6d7e8f90

Every key starts with cisp_, followed by 48 hexadecimal characters. The card list shows only the beginning (for example cisp_7f3a9…) so you can tell them apart.

The key list

Reveal, edit and delete

• Reveal shows the full key again, with the Copy button, at any time, to anyone with the Integrations permission.
• Edit changes the name, permissions, per-minute limit and the Enabled switch. The key itself does not change: the integration keeps working with the same value, now with the new permissions. Turning off Enabled suspends the key immediately (HTTP 401 chave_invalida) without deleting it, and it stops counting toward the plan limit.
• Delete asks for confirmation ("Delete this key? Integrations using it will stop working.") and revokes the key immediately.

Key permissions (scopes)

Each permission on the screen corresponds to a scope, a stable code the API uses to decide what the key can do. The code appears in the escopos field of chave/info and in the permissao error, which states which scope was missing.

Scopes are independent: Manage service orders does not include Look up service orders, for example. An integration that opens service orders and then follows their progress needs both.

Catalogs: available to any key

The catalog routes (chave/info, conexoes/listar, departamentos/listar, atendentes/listar, modelos/listar, etiquetas/listar and motivos/listar) require no scope: any active key can call them, even with all permissions turned off. They return the ids the other routes ask for (conexao_id, departamento_id, atendente_id, modelo_id, etiqueta_id, motivo_id); without them no integration could build its calls. The screen states this right below the permissions: "Connections, departments, agents, templates, tags and closing reasons are available to any active key." Reference in Catalogs.

How many keys to create

• One per integration, with a clear name: this way you can limit, suspend or revoke one system without taking down the others, and the conversation history shows which system performed each action.
• Separate reading from writing when different systems do each thing. A BI dashboard only needs Look up conversations and Metrics; the ERP that sends boletos only needs Send messages.

Address and authentication

All calls go to the same address, shown on the ChatISP API card:

https://<your panel address>/api_publica.php?r=<recurso>/<acao>

The key goes in the HTTP Authorization header, using the Bearer scheme. It never goes in the URL or in the body:

Authorization: Bearer cisp_7f3a9c21d84e0b56a1f2c3d4e5f60718293a4b5c6d7e8f90

There is no login or session: each call is independent.

First call

The chave/info route is ideal for validating the address and key: it requires no permission, changes nothing and shows what the key can do.

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

<?php
// Minimal client, reusable for the other routes
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("Error {$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"Error {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"
  }
}

Validation order

Every call goes through these checks, in this order. The first one that fails defines the response:

1. r missing or not in the recurso/acao format: HTTP 404 rota.
2. Authorization: Bearer ... header missing or malformed: HTTP 401 autenticacao.
3. Key nonexistent, deleted, inactive or not in the cisp_... format: HTTP 401 chave_invalida.
4. Plan without public API or license blocked: HTTP 403 plano.
5. The call is counted in the key's usage. If the per-minute limit was exceeded: HTTP 429 cota_excedida.
6. Body declared as JSON but invalid: HTTP 400 json_invalido.
7. Nonexistent route: HTTP 404 rota.
8. Write route called without POST: HTTP 405 metodo.
9. Key without the route's scope: HTTP 403 permissao, with the missing scope.
10. The operation validates its own parameters and runs.

Request format

Methods

• Read (list, look up, catalogs, metrics, download file): GET or POST.
• Write (send, transfer, close, create, move...): POST only. With another method, the response is HTTP 405 metodo with "esperado":"POST".

Where parameters go

The query string works with any method. When the same parameter comes in both the query and the body, the body wins. A body with Content-Type: application/json that is not a valid JSON object is refused with HTTP 400 json_invalido.

# form
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=Hi! Your technician is on the way."

# 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":"Hi! Your technician is on the way."}'

Parameter types

Response format

Every response is JSON (Content-Type: application/json; charset=utf-8, Cache-Control: no-store) with the same envelope on all routes:

The error field is always a stable code, without accents and never translated, designed for your system to decide what to do. The extra fields help fix the call: campo (which parameter), aceitos (allowed values), maximo, esperado, escopo, among others. Accented characters come unescaped ("Suporte técnico"), and so do slashes.

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"}

HTTP status

The HTTP status is real and consistent with the result: check both the status and the ok field.

Responses that are not JSON

Only mensagens/arquivo: on success it returns the file itself, with the file's Content-Type (images and PDF) or application/octet-stream (other types) and Content-Disposition with the original name. On error, it returns the normal JSON envelope.

Recurring objects

The message, conversation and contact routes always return the conversation and the message with the same fields (details in Conversations and Messages). Values you will find:

Pagination and cursor

Numbered pagination

The large listings (conversas/listar, contatos/listar, tickets/listar and agenda/listar) use page and limit:

The response includes the paginacao block:

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

total is the number of records matching the filters and paginas is how many pages exist with that limit (0 when there are no records). To go through everything, call until pagina reaches paginas. A page beyond the last one returns an empty list, without error.

Message history cursor

A conversation's history (conversas/mensagens) uses a cursor based on the message id, which does not shift when new messages arrive:

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

tem_mais says whether there are still messages in the requested direction. To keep scrolling back, pass cursor.antes_de as the next antes_de; to follow new ones, store cursor.depois_de and use it as depois_de in the next query. Messages always come in chronological order (oldest to newest).

Dates and time zone

Dates in the response

All output dates come in ISO 8601 with the server's time zone, for example 2026-10-01T09:12:40-03:00. Missing dates come as null. The server's time zone appears in chave/info (servidor.fuso_horario), along with its clock (servidor.agora), useful for checking the time difference with your system.

Dates in the request

Years outside 2000 to 2100, or text that is not a date, respond HTTP 400 data_invalida with the campo. Periods whose end is before the start, or longer than the route allows (366 days in metrics and calendar), respond periodo_invalido.

Phone numbers

Phone numbers follow the same rule as the panel screen. Punctuation, spaces and parentheses are ignored.

Rules for Brazilian numbers: area code from 11 to 99 (no zero) and, when the number has 11 digits, the third must be the mobile 9. Otherwise, the response is HTTP 400 telefone_invalido. Without the +, a number that does not fit as Brazilian is also refused, so that no message is sent to the wrong country.

In lookups by phone (conversations, contacts), ChatISP searches for the number with and without the ninth digit, because WhatsApp on some older phones still uses the 8-digit format. In responses, the phone comes with digits only and with the country code, in the format in which the conversation is recorded.

Error codes

Complete list of the possible values of error. Each reference page shows which errors each route can return.

Limits

Key per-minute limit

Each key has its own Per-minute limit (default 60, maximum 10000, 0 for no limit). The count is per clock minute of the server: it resets when the minute turns (at 10:41:00, at 10:42:00...), not in a sliding 60-second window.

With a limit set, every response includes the headers:

A key with limit 0 does not receive the X-RateLimit-* headers.

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}

The refused call was not executed: wait for Retry-After and try again. Refusals also count toward the minute, so retrying in a loop without waiting does not help.

Sizes and quantities

Pace of bulk sending

The API sends each message at the moment it is called. For notices to many subscribers, spread the sends over time instead of firing hundreds of simultaneous calls, and adjust the key's per-minute limit to that pace. For large lists with tracking of deliveries and replies, the Sending automation screen already handles the pace on its own.

API version

Every response, including error responses, carries the header:

X-ChatISP-Api-Versao: 1

The same value appears in chave/info, in the servidor.api_versao field. The current version is 1. Record the value in the integration's logs: it helps support identify which version your system talked to.

The routes, field names and error codes documented here are stable. The API may gain routes, optional parameters and new response fields without changing version; that is why your system should ignore unknown fields instead of rejecting the response. Old fields are kept for existing integrations: for example, atendimentos/abrir still returns conversa_id, protocolo, estado and ja_existia at the top level, in addition to the full conversa object.

Security and best practices

Checklist

• One key per integration, with a clear Name and only the scopes it needs.
• Store the key in an environment variable or in the server's secrets vault, never in versioned code or in logs.
• Always use HTTPS. On a self-hosted installation, configure a domain with a valid certificate before production.
• A per-minute limit compatible with actual usage: it also protects against a runaway loop in your system.
• Check ok and the HTTP status in every response; decide based on the error code.
• On 429, respect Retry-After. On a network error or HTTP 5xx, retry reads with increasing waits. Do not retry sends blindly: a message that timed out may have been delivered, and retrying duplicates the send to the customer. Check the history first with conversas/mensagens.
• Store the returned ids (conversa_id, mensagem_id, ticket_id) to match them with webhooks.
• Cache the catalogs (departments, agents, tags, closing reasons) and refresh them from time to time, instead of querying them on every call.
• Prefer webhooks to polling in a loop to find out what changed.
• Disable or delete the keys of integrations that were shut down. To replace a key, create the new one, update the integration and only then delete the old one.

What gets recorded

Actions performed through the API appear in the panel with the key's name: the "API" event in the conversation timeline, notes as "API (key name): ...", transfers and closings with "API: key name", and service order comments with "[API: key name]". Messages sent through the API go out with author sistema, without an agent signature.

Common problems

Postman and Insomnia collection

To test the API without writing code, download the ready-made collection with the 37 routes, already with the method, sample parameters and a description of each one:

Download the collection (chatisp-api.postman_collection.json)

1. In Postman, use Import and choose the file. In Insomnia, use Import in a collection; the Postman format is recognized.
2. In the collection variables, fill in base_url with your panel address (for example https://atendimento.seuprovedor.com.br, without a trailing slash) and chave with your cisp_... key.
3. First run Informações da chave (key information, chave/info) to confirm the address, key and scopes.
4. Use the catalogs to discover the real ids of your installation before testing the write routes.