Conversas e atendimentos

Lista paginada de conversas, com filtros combináveis (todos se somam com E). Sem filtro nenhum, devolve todas as conversas, das mais recentes para as mais antigas.

Permissão: Consultar conversas.

Datas aceitam ISO 8601 (2026-10-01T08:00:00-03:00), AAAA-MM-DD ou AAAA-MM-DD HH:MM:SS; sem fuso, valem no fuso do servidor. Data que não faz sentido: 400 data_invalida com campo.

# fila do departamento 2 agora, as que esperam há mais tempo primeiro
curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/listar&estado=fila&departamento_id=2&ordem=antigas" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

# encerradas ontem com a etiqueta 3, página 2
curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/listar&estado=encerrada&etiqueta_id=3&encerradas_desde=2026-09-30&criadas_ate=2026-09-30&pagina=2" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

<?php
// percorre todas as páginas das conversas abertas
$pagina = 1;
do {
    $url = 'https://atendimento.seuprovedor.com.br/api_publica.php?' . http_build_query([
        'r' => 'conversas/listar', 'abertas' => 1, 'limite' => 100, 'pagina' => $pagina,
    ]);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE')],
    ]);
    $r = json_decode(curl_exec($ch), true);
    curl_close($ch);
    foreach ($r['conversas'] as $c) {
        echo $c['protocolo'], ' ', $c['estado'], ' ', $c['atendente'], PHP_EOL;
    }
    $pagina++;
} while ($pagina <= $r['paginacao']['paginas']);

import os, requests

r = requests.get("https://atendimento.seuprovedor.com.br/api_publica.php", params={
    "r": "conversas/listar",
    "estado": "fila,humano",
    "atendente_id": 7,
    "limite": 100,
}, headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]}, timeout=30)

dados = r.json()
print(dados["paginacao"]["total"], "conversas com o atendente 7")
for c in dados["conversas"]:
    print(c["protocolo"], c["nome"], c["nao_lidas"])

{
  "ok": true,
  "conversas": [
    {
      "id": 18360,
      "protocolo": "20261001-0055",
      "conexao_id": 1,
      "telefone": "5544988887777",
      "nome": "João Pereira",
      "estado": "fila",
      "aguardando_cliente": false,
      "departamento_id": 2,
      "departamento": "Financeiro",
      "atendente_id": null,
      "atendente": "",
      "nao_lidas": 2,
      "motivo_encerramento": "",
      "resumo": null,
      "criada_em": "2026-10-01T10:31:08-03:00",
      "ultima_mensagem_em": "2026-10-01T10:31:40-03:00",
      "encerrada_em": null
    }
  ],
  "paginacao": { "pagina": 1, "limite": 50, "total": 1, "paginas": 1 }
}

Erros específicos: parametro_invalido (estado, ordem, limite ou página fora do aceito, com campo), data_invalida, telefone_invalido.

Devolve uma conversa completa (com etiquetas) e as últimas mensagens dela, em ordem cronológica. Serve para mostrar no CRM o andamento de um protocolo, conferir se o cliente respondeu a um aviso ou buscar o contexto depois de um webhook.

Permissão: Consultar conversas.

Com mais de um identificador, vale o primeiro na ordem conversa_id/id, protocolo, telefone. Para mais de 100 mensagens, ou para paginar o histórico, use conversas/mensagens.

# por protocolo, com as 3 últimas mensagens
curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/consultar&protocolo=20261001-0042&mensagens=3" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

# a conversa mais recente de um telefone, sem mensagens
curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/consultar&telefone=44999990000&mensagens=0" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

<?php
$url = 'https://atendimento.seuprovedor.com.br/api_publica.php?' . http_build_query([
    'r' => 'conversas/consultar', 'protocolo' => '20261001-0042', 'mensagens' => 3,
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE')],
]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $r['conversa']['estado'], ' com ', $r['conversa']['atendente'] ?: 'ninguém', PHP_EOL;
foreach ($r['mensagens'] as $m) {
    echo $m['criada_em'], ' [', $m['autor'], '] ', $m['conteudo'] ?: ($m['transcricao'] ?? ''), PHP_EOL;
}

import os, requests

r = requests.get("https://atendimento.seuprovedor.com.br/api_publica.php", params={
    "r": "conversas/consultar", "protocolo": "20261001-0042", "mensagens": 3,
}, headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]}, timeout=30)

if r.status_code == 404:
    print("Protocolo não existe")
else:
    for m in r.json()["mensagens"]:
        print(m["criada_em"], m["autor"], m["conteudo"])

{
  "ok": true,
  "conversa": {
    "id": 18342,
    "protocolo": "20261001-0042",
    "conexao_id": 1,
    "telefone": "5544999990000",
    "nome": "Maria Souza",
    "estado": "humano",
    "aguardando_cliente": false,
    "departamento_id": 1,
    "departamento": "Suporte técnico",
    "atendente_id": 7,
    "atendente": "Carlos Lima",
    "nao_lidas": 0,
    "motivo_encerramento": "",
    "resumo": null,
    "criada_em": "2026-10-01T09:12:40-03:00",
    "ultima_mensagem_em": "2026-10-01T09:20:03-03:00",
    "encerrada_em": null,
    "etiquetas": []
  },
  "mensagens": [
    {
      "id": 402850, "conversa_id": 18342, "direcao": "recebida", "autor": "cliente", "autor_nome": "",
      "tipo": "texto", "conteudo": "Minha internet caiu desde cedo", "transcricao": null, "arquivo": null,
      "status": "entregue", "erro": null, "responde_a": null, "editada": false, "apagada": false,
      "criada_em": "2026-10-01T09:12:40-03:00"
    },
    {
      "id": 402852, "conversa_id": 18342, "direcao": "enviada", "autor": "ia", "autor_nome": "",
      "tipo": "texto", "conteudo": "Olá, Maria! Vou verificar a sua conexão agora mesmo.", "transcricao": null, "arquivo": null,
      "status": "lida", "erro": null, "responde_a": null, "editada": false, "apagada": false,
      "criada_em": "2026-10-01T09:12:52-03:00"
    },
    {
      "id": 402866, "conversa_id": 18342, "direcao": "enviada", "autor": "atendente", "autor_nome": "Carlos Lima",
      "tipo": "texto", "conteudo": "Maria, identifiquei a falha. Um técnico vai até você hoje à tarde.", "transcricao": null, "arquivo": null,
      "status": "entregue", "erro": null, "responde_a": 402850, "editada": false, "apagada": false,
      "criada_em": "2026-10-01T09:20:03-03:00"
    }
  ]
}

Erros específicos: identificador_obrigatorio (nenhum dos três identificadores), telefone_invalido, nao_encontrado (404: id ou protocolo inexistente, ou telefone sem nenhuma conversa).

Percorre o histórico inteiro de uma conversa, em páginas, por cursor de id de mensagem. O cursor não pula nem repete mensagens quando chegam mensagens novas no meio da leitura, ao contrário de uma paginação numerada. As mensagens vêm sempre em ordem cronológica (da mais antiga para a mais nova) e sem as notas internas.

Permissão: Consultar conversas.

Dois jeitos de usar

• Ler tudo de trás para a frente (exportar o histórico): primeira chamada sem cursor (as mais recentes); enquanto tem_mais for true, chame de novo com antes_de igual a cursor.antes_de.
• Acompanhar o que chega (espelhar a conversa no seu sistema): guarde o cursor.depois_de e, na próxima vez, chame com depois_de; enquanto tem_mais for true, continue com o novo cursor.depois_de.

# as 50 mais recentes
curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/mensagens&conversa_id=18342" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

# a página anterior
curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/mensagens&conversa_id=18342&antes_de=402850" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

# o que chegou depois da mensagem 402866
curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/mensagens&protocolo=20261001-0042&depois_de=402866" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

<?php
// exporta o histórico completo, do mais antigo para o mais novo
function chatisp(array $params): array {
    $ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php?' . http_build_query($params));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE')],
    ]);
    $r = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $r;
}

$historico = [];
$params = ['r' => 'conversas/mensagens', 'conversa_id' => 18342, 'limite' => 100];
do {
    $r = chatisp($params);
    $historico = array_merge($r['mensagens'], $historico);
    $params['antes_de'] = $r['cursor']['antes_de'];
} while ($r['tem_mais']);

import os, requests

URL = "https://atendimento.seuprovedor.com.br/api_publica.php"
CAB = {"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]}

def novas_mensagens(conversa_id, ultimo_id):
    """Busca tudo o que chegou depois de ultimo_id e devolve o novo cursor."""
    while True:
        r = requests.get(URL, headers=CAB, timeout=30, params={
            "r": "conversas/mensagens", "conversa_id": conversa_id,
            "depois_de": ultimo_id, "limite": 100}).json()
        for m in r["mensagens"]:
            print(m["autor"], m["conteudo"])
        ultimo_id = r["cursor"]["depois_de"]
        if not r["tem_mais"]:
            return ultimo_id

{
  "ok": true,
  "conversa_id": 18342,
  "mensagens": [
    { "id": 402852, "conversa_id": 18342, "direcao": "enviada", "autor": "ia", "...": "..." },
    { "id": 402866, "conversa_id": 18342, "direcao": "enviada", "autor": "atendente", "...": "..." }
  ],
  "tem_mais": true,
  "cursor": { "antes_de": 402852, "depois_de": 402866 }
}

Erros específicos: identificador_obrigatorio, nao_encontrado, parametro_invalido (limite fora de 1 a 100, com maximo; cursor que não é número inteiro).

Leva uma conversa aberta para um departamento, para um atendente ou para os dois, exatamente como o botão Transferir do painel. Exemplos: o ERP detecta que o cliente está inadimplente e manda a conversa para o Financeiro; o CRM direciona clientes corporativos para o gerente de conta.

Permissão: Gerenciar conversas.

O que acontece

• Em todos os casos a conversa sai da automação: se estava com a IA ou num fluxo, eles param de responder.
• O compartilhamento da conversa com outros atendentes é desfeito; quem recebe decide com quem dividir.
• A API não confere se o atendente faz parte do departamento: a combinação é responsabilidade da integração.
• O cliente não recebe mensagem da transferência. A única exceção possível é o Aviso de tempo de espera, quando ele está ligado em Configurações e a conversa entra na fila com todos os atendentes ocupados.
• Sai o webhook conversa_transferida (e conversa_atribuida quando a distribuição automática entrega a conversa a alguém).

curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/transferir" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"protocolo": "20261001-0042", "departamento_id": 2, "motivo": "cliente inadimplente"}'

<?php
$ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/transferir');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['conversa_id' => 18342, 'atendente_id' => 7, 'motivo' => 'cliente corporativo']),
]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $r['conversa']['estado'], ' com ', $r['conversa']['atendente'], PHP_EOL;

import os, requests

r = requests.post("https://atendimento.seuprovedor.com.br/api_publica.php",
    params={"r": "conversas/transferir"},
    headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
    json={"conversa_id": 18342, "departamento_id": 2, "atendente_id": 9},
    timeout=30)
print(r.status_code, r.json()["conversa"]["estado"])

A resposta traz a conversa já atualizada, com etiquetas:

{
  "ok": true,
  "conversa": {
    "id": 18342,
    "protocolo": "20261001-0042",
    "estado": "fila",
    "departamento_id": 2,
    "departamento": "Financeiro",
    "atendente_id": null,
    "atendente": "",
    "...": "demais campos do objeto conversa",
    "etiquetas": []
  }
}

Se a distribuição automática entregar a conversa na hora, o estado já vem humano, com o atendente escolhido por ela.

Erros específicos: parametro_obrigatorio (sem departamento nem atendente; campo igual a departamento_id|atendente_id), departamento_invalido, atendente_invalido (inexistente, inativo ou excluído), conversa_encerrada (409), identificador_obrigatorio, nao_encontrado.

Encerra uma conversa aberta, como o botão Encerrar do painel. Exemplo: o sistema de ordens de serviço fecha a OS e encerra o chamado do WhatsApp com o motivo certo.

Permissão: Gerenciar conversas.

O que acontece com o cliente

Com enviar_mensagem verdadeiro (padrão), o encerramento pela API faz o mesmo que pelo painel:

1. Mensagem de chamado encerrado: o texto configurado em Configurações (com {protocolo} e {nome} preenchidos) é enviado, desde que tenha havido atendimento de verdade: o cliente participou da conversa, ou a IA ou um atendente falou com ele. Com o campo vazio nas Configurações, nada é enviado.
2. Pesquisa de satisfação: se Enviar pesquisa ao encerrar conversas atendidas estiver ligado (veja Pesquisa), a pergunta é enviada quando a IA ou um atendente respondeu ao cliente na conversa. A nota que o cliente responder entra nos relatórios.

Com enviar_mensagem=false, nenhuma das duas sai. Use, por exemplo, ao encerrar em lote conversas antigas ou de teste.

O que acontece por trás

• O estado passa a encerrada, com o motivo; a conversa sai de fluxo e IA; uma espera de retorno aberta é fechada.
• Se o cliente escreveu algo, a IA escreve o resumo do chamado em segundo plano (consulte a conversa de novo alguns minutos depois).
• OS abertas a partir desse chamado têm o resumo refeito cobrindo a conversa inteira.
• Sai o webhook conversa_encerrada, com motivo igual ao nome do motivo escolhido (ou à identificação da chave, sem motivo).

# encerra com motivo, enviando mensagem de encerramento e pesquisa
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -d "r=conversas/encerrar" -d "protocolo=20261001-0042" -d "motivo_id=1"

# encerra em silêncio
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -d "r=conversas/encerrar" -d "conversa_id=18342" -d "enviar_mensagem=0"

<?php
$ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/encerrar');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['protocolo' => '20261001-0042', 'motivo_id' => 1]),
]);
$r = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status === 409) {
    // conversa_encerrada: já estava encerrada; trate como sucesso
}

import os, requests

r = requests.post("https://atendimento.seuprovedor.com.br/api_publica.php",
    params={"r": "conversas/encerrar"},
    headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
    json={"conversa_id": 18342, "motivo_id": 1, "enviar_mensagem": False},
    timeout=30)
c = r.json()["conversa"]
print(c["estado"], c["motivo_encerramento"], c["encerrada_em"])

{
  "ok": true,
  "conversa": {
    "id": 18342,
    "protocolo": "20261001-0042",
    "estado": "encerrada",
    "motivo_encerramento": "Resolvido",
    "resumo": null,
    "encerrada_em": "2026-10-01T11:05:12-03:00",
    "...": "demais campos do objeto conversa"
  }
}

Erros específicos: motivo_invalido (inexistente ou inativo), conversa_encerrada (409: já estava encerrada; em reprocessamentos, trate como sucesso), parametro_invalido (enviar_mensagem com valor que não é booleano), identificador_obrigatorio, nao_encontrado.

Muda as etiquetas de uma conversa (aberta ou encerrada). As etiquetas são cadastradas em Cadastros e listadas por etiquetas/listar. Exemplos: marcar VIP quando o ERP identifica um plano empresarial; marcar Inadimplente para o Financeiro filtrar no kanban.

Permissão: Gerenciar conversas.

Envie ao menos um dos três. Podem vir juntos: a API parte de etiquetas (ou das atuais, sem ele), soma adicionar e tira remover. As listas aceitam JSON ([1, 3]), formulário (adicionar[]=1&adicionar[]=3) ou texto separado por vírgula (adicionar=1,3). Ids repetidos são ignorados.

# acrescenta as etiquetas 1 e 3 e tira a 2
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/etiquetas" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"conversa_id": 18342, "adicionar": [1, 3], "remover": [2]}'

# limpa todas
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -d "r=conversas/etiquetas" -d "conversa_id=18342" -d "etiquetas="

<?php
$ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/etiquetas');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['protocolo' => '20261001-0042', 'etiquetas' => [1]]),
]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);
echo implode(', ', array_column($r['conversa']['etiquetas'], 'nome')), PHP_EOL;

import os, requests

r = requests.post("https://atendimento.seuprovedor.com.br/api_publica.php",
    params={"r": "conversas/etiquetas"},
    headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
    json={"conversa_id": 18342, "adicionar": [3]}, timeout=30)
print([e["nome"] for e in r.json()["conversa"]["etiquetas"]])

{
  "ok": true,
  "conversa": {
    "id": 18342,
    "protocolo": "20261001-0042",
    "...": "demais campos do objeto conversa",
    "etiquetas": [
      { "id": 1, "nome": "VIP", "cor": "#f59e0b" },
      { "id": 3, "nome": "Visita técnica", "cor": "#2563eb" }
    ]
  }
}

{"ok": false, "error": "etiqueta_invalida", "campo": "adicionar"}

Erros específicos: parametro_obrigatorio (nenhum dos três; campo igual a etiquetas|adicionar|remover), etiqueta_invalida (id inexistente; nada é alterado), parametro_invalido, identificador_obrigatorio, nao_encontrado.

Grava uma nota na linha do tempo da conversa, visível só para a equipe. Exemplos: o NOC avisa que há um rompimento de fibra na região do cliente; o ERP registra que o pagamento foi compensado durante o atendimento.

Permissão: Gerenciar conversas.

• A nota aparece no chat como linha do sistema, com o nome da chave na frente: API (ERP): Pagamento compensado às 10h12.
• Nunca é enviada ao cliente, não entra no histórico que a IA lê e não aparece em relatórios.
• Também não volta pelas rotas de leitura da API (que nunca devolvem conteúdo interno): guarde o nota_id se precisar referenciá-la.

curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/nota" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"protocolo": "20261001-0042", "texto": "Rompimento de fibra no bairro Jardim Alvorada, previsão 14h."}'

<?php
$ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php?r=conversas/nota');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['conversa_id' => 18342, 'texto' => 'Pagamento compensado às 10h12.']),
]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);

import os, requests

r = requests.post("https://atendimento.seuprovedor.com.br/api_publica.php",
    params={"r": "conversas/nota"},
    headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
    json={"conversa_id": 18342, "texto": "Pagamento compensado às 10h12."}, timeout=30)
print(r.json())

{"ok": true, "nota_id": 402990, "conversa_id": 18342}

Erros específicos: texto_invalido (vazio ou acima de 900 caracteres), identificador_obrigatorio, nao_encontrado.

Coloca um telefone na fila de atendimento (ou direto com um atendente) sem enviar nenhuma mensagem ao cliente. É o caminho para quando o pedido nasce fora do WhatsApp: formulário de contato do site, portal do assinante, alarme do sistema de monitoramento, retorno de ligação agendado. A equipe vê o atendimento no painel e fala com o cliente por ali.

Permissão: Abrir atendimentos.

Como a chamada se comporta

1. O ChatISP procura uma conversa aberta desse telefone no número de WhatsApp (pelos dois canais de um número gêmeo, com e sem o nono dígito). Se não houver, cria uma nova, na fila, com protocolo próprio (sai o webhook conversa_criada).
2. A nota, se veio, é gravada na linha do tempo, junto com o registro da chave.
3. Com atendente_id: a conversa vai direto para esse atendente (estado humano), qualquer que seja o estado em que estava, e também para o departamento_id, se veio. Sai da IA ou do fluxo, se estava neles. O atendente é avisado.
4. Sem atendente_id, com a conversa na fila: ela vai para a fila do departamento_id pedido (ou continua na do departamento atual), e a distribuição automática tenta entregá-la na hora. Havendo atendente disponível, ela já sai humano; senão fica fila e a equipe recebe o aviso.
5. Sem atendente_id, com a conversa com a IA, num fluxo ou já com um atendente: nada muda, nem o departamento. A API não puxa uma conversa que já está sendo conduzida.

curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=atendimentos/abrir" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "telefone": "5544988887777",
    "nome": "João Pereira",
    "departamento_id": 2,
    "nota": "Pediu pelo portal a renegociação da fatura de setembro."
  }'

<?php
$ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE')],
    CURLOPT_POSTFIELDS     => http_build_query([
        'r'               => 'atendimentos/abrir',
        'telefone'        => '5544988887777',
        'nome'            => 'João Pereira',
        'departamento_id' => 2,
        'nota'            => 'Pediu pelo portal a renegociação da fatura de setembro.',
    ]),
]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $r['ja_existia'] ? 'Já havia atendimento: ' : 'Atendimento aberto: ', $r['protocolo'], PHP_EOL;

import os, requests

r = requests.post("https://atendimento.seuprovedor.com.br/api_publica.php",
    params={"r": "atendimentos/abrir"},
    headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
    json={
        "telefone": "5544988887777",
        "atendente_id": 7,
        "nota": "Retorno de ligação agendado pelo NOC.",
    }, timeout=30)
corpo = r.json()
print(corpo["protocolo"], corpo["estado"], corpo["ja_existia"])

{
  "ok": true,
  "conversa_id": 18361,
  "protocolo": "20261001-0056",
  "estado": "fila",
  "ja_existia": false,
  "conversa": {
    "id": 18361,
    "protocolo": "20261001-0056",
    "conexao_id": 1,
    "telefone": "5544988887777",
    "nome": "João Pereira",
    "estado": "fila",
    "departamento_id": 2,
    "departamento": "Financeiro",
    "...": "demais campos do objeto conversa",
    "etiquetas": []
  }
}

Erros específicos: telefone_invalido, conexao_invalida, sem_conexao, conexao_id_obrigatorio, conexao_desconectada, departamento_invalido, atendente_invalido, texto_invalido (nota acima de 900 caracteres, com campo igual a nota).