Datos de referencia

Visión general

Antes de enviar un mensaje por un número específico, transferir a un departamento, asignar un agente o cerrar con un motivo, la integración necesita los ids de esos registros. Las siete rutas de esta página existen para eso:

• Alcance: ninguno. Cualquier clave activa puede llamarlas, incluso con todos los permisos desactivados.
• Método: GET (también se acepta POST).
• Paginación: no hay. Cada ruta devuelve la lista completa, que en un proveedor de internet suele tener desde unos pocos hasta algunas decenas de elementos.
• Conteo: las llamadas de catálogo cuentan en el uso y en el límite por minuto de la clave, como cualquier otra.

Información de la clave

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

$info = chatisp('chave/info');
$faltando = array_diff(['mensagens_enviar', 'tickets_gerir'], $info['chave']['escopos']);
if ($faltando) {
    die('Active en la clave: ' . implode(', ', $faltando) . PHP_EOL);
}

info = chatisp("chave/info")
faltando = {"mensagens_enviar", "tickets_gerir"} - set(info["chave"]["escopos"])
if faltando:
    raise SystemExit(f"Active en la clave: {', '.join(faltando)}")

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

Conexiones (números de WhatsApp)

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

// Un número = una línea: descarta el lado no principal de las gemelas
$numeros = array_filter(chatisp('conexoes/listar')['conexoes'], fn($c) => $c['principal']);
foreach ($numeros as $c) {
    echo "{$c['id']}  {$c['nome']}  {$c['telefone']}  {$c['estado']}\n";
}

# Un número = una línea: descarta el lado no principal de las gemelas
for c in chatisp("conexoes/listar")["conexoes"]:
    if c["principal"]:
        print(c["id"], c["nome"], c["telefone"], c["estado"])

{
  "ok": true,
  "conexoes": [
    {
      "id": 1,
      "nome": "Atendimento",
      "tipo": "qr",
      "estado": "conectada",
      "telefone": "5544999990000",
      "nome_conta": "Fibra Exemplo",
      "gemea_id": 2,
      "principal": true
    },
    {
      "id": 2,
      "nome": "Atendimento (API oficial)",
      "tipo": "api_oficial",
      "estado": "conectada",
      "telefone": "5544999990000",
      "nome_conta": "Fibra Exemplo",
      "gemea_id": 1,
      "principal": false
    },
    {
      "id": 4,
      "nome": "Comercial",
      "tipo": "qr",
      "estado": "desconectada",
      "telefone": "5544999991111",
      "nome_conta": "Fibra Exemplo Vendas",
      "gemea_id": null,
      "principal": true
    }
  ]
}

Número gemelo: QR y API oficial en el mismo número

Un mismo número de WhatsApp puede estar vinculado a ChatISP por los dos caminos al mismo tiempo: por código QR (la aplicación del celular) y por la API oficial de Meta (en el modo de coexistencia). En el panel, ese par aparece como un único canal; en la API, aparece como dos conexiones que apuntan una a la otra mediante gemea_id. Reglas que valen para la integración:

• Los dos lados son el mismo número. Para listar números, considere solo las conexiones con principal: true, como en el ejemplo anterior.
• Las conversaciones nuevas nacen en el lado principal, que es el del QR cuando existe. El conexao_id que aparece en las conversaciones y en los webhooks es, en general, el del lado principal.
• Envío: ChatISP elige el lado que entregará cada mensaje, como lo hace en el panel. Si uno de los lados cae, el otro sigue enviando: la llamada solo responde conexao_desconectada cuando ambos están fuera de servicio.
• Plantillas: solo el lado de la API oficial envía plantillas. En mensagens/enviar_modelo y en modelos/listar, puede informar el id de cualquiera de los lados: ChatISP usa el lado oficial del mismo número.
• Filtros: en conversas/listar, filtrar por el conexao_id de cualquier lado trae las conversaciones del número completo.

Cuándo informar conexao_id

Departamentos

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

// Mapa nombre => id de los departamentos activos
$deps = [];
foreach (chatisp('departamentos/listar')['departamentos'] as $d) {
    if ($d['ativo']) $deps[$d['nome']] = $d['id'];
}
$suporte = $deps['Suporte técnico'] ?? null;

deps = {d["nome"]: d["id"] for d in chatisp("departamentos/listar")["departamentos"] if d["ativo"]}
suporte = deps.get("Suporte técnico")

{
  "ok": true,
  "departamentos": [
    { "id": 1, "nome": "Suporte técnico", "ativo": true,  "padrao": true },
    { "id": 2, "nome": "Financeiro",      "ativo": true,  "padrao": false },
    { "id": 3, "nome": "Comercial",       "ativo": true,  "padrao": false },
    { "id": 5, "nome": "Retenção",        "ativo": false, "padrao": false }
  ]
}

Agentes

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

// Quién del departamento 1 está en línea y fuera de pausa ahora
$livres = array_filter(chatisp('atendentes/listar')['atendentes'], fn($a) =>
    $a['ativo'] && $a['online'] && !$a['em_pausa'] && in_array(1, $a['departamentos'], true));

# Quién del departamento 1 está en línea y fuera de pausa ahora
livres = [a for a in chatisp("atendentes/listar")["atendentes"]
          if a["ativo"] and a["online"] and not a["em_pausa"] and 1 in a["departamentos"]]

{
  "ok": true,
  "atendentes": [
    {
      "id": 7,
      "nome": "Ana Ribeiro",
      "perfil": "Atendente",
      "ativo": true,
      "departamentos": [1, 2],
      "online": true,
      "em_pausa": false
    },
    {
      "id": 4,
      "nome": "Carlos Mendes",
      "perfil": "Supervisor",
      "ativo": true,
      "departamentos": [1],
      "online": true,
      "em_pausa": true
    }
  ]
}

Plantillas de mensaje (API oficial)

curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=modelos/listar&conexao_id=2" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

// Solo las que la API puede enviar
$enviaveis = array_filter(chatisp('modelos/listar', ['conexao_id' => 2])['modelos'], fn($m) => $m['enviavel']);
foreach ($enviaveis as $m) {
    echo "{$m['id']}  {$m['nome']} ({$m['idioma']}): {$m['variaveis']} variable(s)\n";
}

modelos = chatisp("modelos/listar", {"conexao_id": 2})["modelos"]
for m in (m for m in modelos if m["enviavel"]):
    print(m["id"], m["nome"], m["idioma"], m["variaveis"])

{
  "ok": true,
  "modelos": [
    {
      "id": 12,
      "conexao_id": 2,
      "nome": "aviso_manutencao",
      "idioma": "pt_BR",
      "categoria": "UTILITY",
      "status": "APPROVED",
      "corpo": "Olá, {{1}}! Haverá manutenção programada na sua região em {{2}}, das {{3}}. Pedimos desculpas pelo transtorno.",
      "variaveis": 3,
      "cabecalho": null,
      "enviavel": true,
      "atualizado_em": "2026-09-28T14:02:11-03:00"
    },
    {
      "id": 15,
      "conexao_id": 2,
      "nome": "fatura_disponivel",
      "idioma": "pt_BR",
      "categoria": "UTILITY",
      "status": "APPROVED",
      "corpo": "Olá, {{1}}. Sua fatura de {{2}} está disponível. Vencimento: {{3}}.",
      "variaveis": 3,
      "cabecalho": "DOCUMENT",
      "enviavel": false,
      "atualizado_em": "2026-09-28T14:02:11-03:00"
    }
  ]
}

Etiquetas

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

$etiquetas = array_column(chatisp('etiquetas/listar')['etiquetas'], 'id', 'nome');
// marca la conversación como "Visita técnica" sin quitar las demás etiquetas
chatisp('conversas/etiquetas', ['conversa_id' => 18342, 'adicionar' => [$etiquetas['Visita técnica']]], 'POST');

etiquetas = {e["nome"]: e["id"] for e in chatisp("etiquetas/listar")["etiquetas"]}
# marca la conversación como "Visita técnica" sin quitar las demás etiquetas
chatisp("conversas/etiquetas", {"conversa_id": 18342, "adicionar": [etiquetas["Visita técnica"]]}, "POST")

{
  "ok": true,
  "etiquetas": [
    { "id": 3, "nome": "Visita técnica", "cor": "#f59e0b" },
    { "id": 1, "nome": "Cliente novo",   "cor": "#10b981" },
    { "id": 6, "nome": "Cancelamento",   "cor": "#ef4444" }
  ]
}

Motivos de cierre

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

$motivos = array_column(array_filter(chatisp('motivos/listar')['motivos'], fn($m) => $m['ativo']), 'id', 'nome');
chatisp('conversas/encerrar', ['conversa_id' => 18342, 'motivo_id' => $motivos['Problema resolvido']], 'POST');

motivos = {m["nome"]: m["id"] for m in chatisp("motivos/listar")["motivos"] if m["ativo"]}
chatisp("conversas/encerrar", {"conversa_id": 18342, "motivo_id": motivos["Problema resolvido"]}, "POST")

{
  "ok": true,
  "motivos": [
    { "id": 1, "nome": "Problema resolvido",  "ativo": true },
    { "id": 2, "nome": "Dúvida esclarecida",  "ativo": true },
    { "id": 4, "nome": "Cliente não respondeu", "ativo": true },
    { "id": 7, "nome": "Engano",              "ativo": false }
  ]
}

Guardar y actualizar los catálogos

Los catálogos cambian poco: departamentos, etiquetas y motivos solo cambian cuando alguien edita los registros en el panel. Buenas prácticas:

• Guárdelos en caché en su sistema y actualícelos a intervalos (por ejemplo, cada hora) o al iniciar la integración. Consultar el catálogo en cada envío gasta el límite por minuto sin necesidad.
• Prefiera ids a nombres. Los nombres pueden editarse en el panel en cualquier momento; el id sigue siendo el mismo. Si su configuración usa nombres (como en los ejemplos anteriores), resuelva el id al iniciar y avise cuando no se encuentre un nombre.
• Trate los errores de registro (departamento_invalido, atendente_invalido, motivo_invalido, etiqueta_invalida) como señal para recargar el catálogo: algo fue desactivado o eliminado en el panel.
• La presencia cambia todo el tiempo. Los campos online y em_pausa de atendentes/listar valen para el momento de la consulta; no los guarde en caché.
• El estado de la conexión también. Antes de un envío masivo, verifique en conexoes/listar si el número está conectada.