Conversaciones y atenciones

Lista paginada de conversaciones, con filtros combinables (todos se suman con Y). Sin ningún filtro, devuelve todas las conversaciones, de las más recientes a las más antiguas.

Permiso: Consultar conversaciones.

Las fechas aceptan ISO 8601 (2026-10-01T08:00:00-03:00), AAAA-MM-DD o AAAA-MM-DD HH:MM:SS; sin zona horaria, valen en la zona del servidor. Fecha que no tiene sentido: 400 data_invalida con campo.

# cola del departamento 2 ahora, primero las que esperan hace más tiempo
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"

# cerradas ayer con la 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
// recorre todas las páginas de las conversaciones abiertas
$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"], "conversaciones con el agente 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": "Finanzas",
      "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 }
}

Errores específicos: parametro_invalido (estado, orden, límite o página fuera de lo aceptado, con campo), data_invalida, telefone_invalido.

Devuelve una conversación completa (con etiquetas) y sus últimos mensajes, en orden cronológico. Sirve para mostrar en el CRM el avance de un protocolo, verificar si el cliente respondió a un aviso o buscar el contexto después de un webhook.

Permiso: Consultar conversaciones.

Con más de un identificador, vale el primero en el orden conversa_id/id, protocolo, telefone. Para más de 100 mensajes, o para paginar el historial, use conversas/mensagens.

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

# la conversación más reciente de un teléfono, sin mensajes
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'], ' con ', $r['conversa']['atendente'] ?: 'nadie', 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("El protocolo no 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": "Soporte 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": "Mi internet está caída desde temprano", "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": "¡Hola, Maria! Voy a verificar su conexión ahora mismo.", "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, identifiqué la falla. Un técnico irá a su domicilio hoy por la 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"
    }
  ]
}

Errores específicos: identificador_obrigatorio (ninguno de los tres identificadores), telefone_invalido, nao_encontrado (404: id o protocolo inexistente, o teléfono sin ninguna conversación).

Recorre el historial completo de una conversación, en páginas, por cursor de id de mensaje. El cursor no salta ni repite mensajes cuando llegan mensajes nuevos en medio de la lectura, a diferencia de una paginación numerada. Los mensajes vienen siempre en orden cronológico (del más antiguo al más nuevo) y sin las notas internas.

Permiso: Consultar conversaciones.

Dos formas de usarlo

• Leer todo de atrás hacia adelante (exportar el historial): primera llamada sin cursor (los más recientes); mientras tem_mais sea true, llame de nuevo con antes_de igual a cursor.antes_de.
• Seguir lo que llega (reflejar la conversación en su sistema): guarde el cursor.depois_de y, la próxima vez, llame con depois_de; mientras tem_mais sea true, continúe con el nuevo cursor.depois_de.

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

# la 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"

# lo que llegó después del mensaje 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 el historial completo, del más antiguo al más nuevo
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 todo lo que llegó después de ultimo_id y devuelve el nuevo 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 }
}

Errores específicos: identificador_obrigatorio, nao_encontrado, parametro_invalido (limite fuera de 1 a 100, con maximo; cursor que no es un número entero).

Lleva una conversación abierta a un departamento, a un agente o a ambos, exactamente como el botón Transferir del panel. Ejemplos: el ERP detecta que el cliente está en mora y envía la conversación a Finanzas; el CRM dirige a los clientes corporativos a su ejecutivo de cuenta.

Permiso: Gestionar conversaciones.

Qué sucede

• En todos los casos la conversación sale de la automatización: si estaba con la IA o en un flujo, estos dejan de responder.
• Se deshace el uso compartido de la conversación con otros agentes; quien la recibe decide con quién compartirla.
• La API no verifica si el agente forma parte del departamento: la combinación es responsabilidad de la integración.
• El cliente no recibe ningún mensaje de la transferencia. La única excepción posible es el Aviso de tiempo de espera, cuando está activado en Configuración y la conversación entra en la cola con todos los agentes ocupados.
• Se dispara el webhook conversa_transferida (y conversa_atribuida cuando la distribución automática entrega la conversación a alguien).

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 en mora"}'

<?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'], ' con ', $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"])

La respuesta trae la conversación ya actualizada, con etiquetas:

{
  "ok": true,
  "conversa": {
    "id": 18342,
    "protocolo": "20261001-0042",
    "estado": "fila",
    "departamento_id": 2,
    "departamento": "Finanzas",
    "atendente_id": null,
    "atendente": "",
    "...": "demás campos del objeto conversación",
    "etiquetas": []
  }
}

Si la distribución automática entrega la conversación en el momento, el estado ya viene como humano, con el agente elegido por ella.

Errores específicos: parametro_obrigatorio (sin departamento ni agente; campo igual a departamento_id|atendente_id), departamento_invalido, atendente_invalido (inexistente, inactivo o eliminado), conversa_encerrada (409), identificador_obrigatorio, nao_encontrado.

Cierra una conversación abierta, como el botón Cerrar del panel. Ejemplo: el sistema de órdenes de servicio cierra la OS y cierra la atención de WhatsApp con el motivo correcto.

Permiso: Gestionar conversaciones.

Qué sucede con el cliente

Con enviar_mensagem verdadero (predeterminado), el cierre por la API hace lo mismo que por el panel:

1. Mensaje de atención cerrada: se envía el texto configurado en Configuración (con {protocolo} y {nome} completados), siempre que haya habido atención real: el cliente participó en la conversación, o la IA o un agente habló con él. Con el campo vacío en Configuración, no se envía nada.
2. Encuesta de satisfacción: si Enviar la encuesta al cerrar conversaciones atendidas está activado (vea Encuesta de satisfacción), la pregunta se envía cuando la IA o un agente respondió al cliente en la conversación. La nota que el cliente responda entra en los informes.

Con enviar_mensagem=false, no sale ninguno de los dos. Úselo, por ejemplo, al cerrar en lote conversaciones antiguas o de prueba.

Qué sucede internamente

• El estado pasa a encerrada, con el motivo; la conversación sale del flujo y de la IA; una espera de respuesta abierta se cierra.
• Si el cliente escribió algo, la IA escribe el resumo de la atención en segundo plano (consulte la conversación de nuevo algunos minutos después).
• Las órdenes de servicio abiertas a partir de esa atención tienen el resumen rehecho cubriendo la conversación completa.
• Se dispara el webhook conversa_encerrada, con motivo igual al nombre del motivo elegido (o a la identificación de la clave, sin motivo).

# cierra con motivo, enviando el mensaje de cierre y la encuesta
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"

# cierra en silencio
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: ya estaba cerrada; trátelo como éxito
}

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": "Resuelto",
    "resumo": null,
    "encerrada_em": "2026-10-01T11:05:12-03:00",
    "...": "demás campos del objeto conversación"
  }
}

Errores específicos: motivo_invalido (inexistente o inactivo), conversa_encerrada (409: ya estaba cerrada; en reprocesamientos, trátelo como éxito), parametro_invalido (enviar_mensagem con un valor que no es booleano), identificador_obrigatorio, nao_encontrado.

Cambia las etiquetas de una conversación (abierta o cerrada). Las etiquetas se registran en Catálogos y se listan con etiquetas/listar. Ejemplos: marcar VIP cuando el ERP identifica un plan empresarial; marcar En mora para que Finanzas filtre en el kanban.

Permiso: Gestionar conversaciones.

Envíe al menos uno de los tres. Pueden venir juntos: la API parte de etiquetas (o de las actuales, sin él), suma adicionar y quita remover. Las listas aceptan JSON ([1, 3]), formulario (adicionar[]=1&adicionar[]=3) o texto separado por comas (adicionar=1,3). Los ids repetidos se ignoran.

# agrega las etiquetas 1 y 3 y quita la 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]}'

# quita 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",
    "...": "demás campos del objeto conversación",
    "etiquetas": [
      { "id": 1, "nome": "VIP", "cor": "#f59e0b" },
      { "id": 3, "nome": "Visita técnica", "cor": "#2563eb" }
    ]
  }
}

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

Errores específicos: parametro_obrigatorio (ninguno de los tres; campo igual a etiquetas|adicionar|remover), etiqueta_invalida (id inexistente; no se modifica nada), parametro_invalido, identificador_obrigatorio, nao_encontrado.

Graba una nota en la línea de tiempo de la conversación, visible solo para el equipo. Ejemplos: el NOC avisa que hay un corte de fibra en la zona del cliente; el ERP registra que el pago se acreditó durante la atención.

Permiso: Gestionar conversaciones.

• La nota aparece en el chat como línea del sistema, con el nombre de la clave al frente: API (ERP): Pago acreditado a las 10:12.
• Nunca se envía al cliente, no entra en el historial que lee la IA y no aparece en los informes.
• Tampoco vuelve por las rutas de lectura de la API (que nunca devuelven contenido interno): guarde el nota_id si necesita hacer referencia a ella.

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": "Corte de fibra en el barrio Jardim Alvorada, previsión 14:00."}'

<?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' => 'Pago acreditado a las 10:12.']),
]);
$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": "Pago acreditado a las 10:12."}, timeout=30)
print(r.json())

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

Errores específicos: texto_invalido (vacío o de más de 900 caracteres), identificador_obrigatorio, nao_encontrado.

Coloca un teléfono en la cola de atención (o directo con un agente) sin enviar ningún mensaje al cliente. Es el camino para cuando la solicitud nace fuera de WhatsApp: formulario de contacto del sitio web, portal del suscriptor, alarma del sistema de monitoreo, devolución de llamada programada. El equipo ve la atención en el panel y habla con el cliente desde allí.

Permiso: Abrir atenciones.

Cómo se comporta la llamada

1. ChatISP busca una conversación abierta de ese teléfono en el número de WhatsApp (por los dos canales de un número gemelo, con y sin el noveno dígito). Si no la hay, crea una nueva, en la cola, con protocolo propio (se dispara el webhook conversa_criada).
2. La nota, si se envió, se graba en la línea de tiempo, junto con el registro de la clave.
3. Con atendente_id: la conversación va directo a ese agente (estado humano), sea cual sea el estado en que estaba, y también al departamento_id, si se envió. Sale de la IA o del flujo, si estaba en ellos. El agente recibe el aviso.
4. Sin atendente_id, con la conversación en la cola: va a la cola del departamento_id pedido (o sigue en la del departamento actual), y la distribución automática intenta entregarla en el momento. Si hay un agente disponible, ya sale como humano; si no, queda en fila y el equipo recibe el aviso.
5. Sin atendente_id, con la conversación con la IA, en un flujo o ya con un agente: no cambia nada, ni el departamento. La API no toma una conversación que ya está siendo conducida.

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": "Pidió por el portal renegociar la factura de septiembre."
  }'

<?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'            => 'Pidió por el portal renegociar la factura de septiembre.',
    ]),
]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $r['ja_existia'] ? 'Ya había una atención: ' : 'Atención abierta: ', $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": "Devolución de llamada programada por el 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": "Finanzas",
    "...": "demás campos del objeto conversación",
    "etiquetas": []
  }
}

Errores específicos: telefone_invalido, conexao_invalida, sem_conexao, conexao_id_obrigatorio, conexao_desconectada, departamento_invalido, atendente_invalido, texto_invalido (nota de más de 900 caracteres, con campo igual a nota).