Gerenciar conversas

Lista as conversas de todos os agentes, com filtros por agente, canal, período, conteúdo e metadados. Para paginar, informe limit e, nas páginas seguintes, reenvie cursor, currentPage, total e totalPages recebidos na resposta anterior — sem eles, total e totalPages voltam null.

Retorna os dados gerais de uma conversa: agente, canal, nota da pesquisa, metadados e os arquivos enviados, com link de download já assinado e o texto extraído de cada um.

Retorna o histórico completo da conversa. A primeira interação é a apresentação do agente (sem id); as demais estão em ordem cronológica.

Abre uma conversa com o agente e devolve o id usado nas rotas de mensagem. Nenhuma mensagem é enviada nesta chamada.

O corpo é opcional. Use meta para gravar metadados (pares nome–valor) que depois servem de filtro em [Listar conversas]; valores null são descartados.

Grava metadados na conversa. Envie um objeto plano com os campos — sem aninhar em meta.

• Campo novo é criado; campo existente tem o valor substituído.
• { "campo": { "delete": true } } remove o campo.
• Valores null são ignorados.
• O conjunto final de metadados, serializado em JSON, pode ter até 5.000 caracteres.

A resposta é 203 mesmo quando a conversa não existe.

Envia uma mensagem ao agente e devolve a resposta em partes, à medida que é gerada.

O corpo da resposta é texto puro (UTF-8), sem eventos nem delimitadores: concatene os pedaços na ordem em que chegam. A resposta termina quando a conexão é encerrada. O header Content-Type vem como json/event-stream, mas o conteúdo não é JSON nem SSE. Quando a conversa passa de um agente para outro, as falas vêm separadas por uma linha em branco.

O stream não informa o consumo do turno; use [Enviar mensagem] quando precisar de usage.

Headers da resposta

Envio de arquivos

Com multipart/form-data, envie os arquivos no campo files, repetindo a parte uma vez por arquivo (file continua aceito para um arquivo só). Arquivos de tipos diferentes podem ir na mesma mensagem: o tipo de cada um é identificado pelo próprio arquivo. Envie sempre text com a instrução sobre os arquivos.

Fora dos limites, a resposta é 400 com o motivo em message (ex.: Envie no máximo 5 arquivos por mensagem., Arquivo maior que 20MB., O total dos arquivos excede 50MB.). Campo de arquivo com outro nome — como files[] — é recusado com Campo de arquivo inesperado.

Falhas

Se a geração falhar no meio, o texto termina com o aviso “Tivemos um problema durante o processamento da resposta. Tente novamente em alguns instantes.”, precedido de ---. Falhas antes do início do stream respondem com status de erro e corpo em texto puro.

Envia uma mensagem ao agente e devolve a resposta completa, em JSON, depois que ela termina de ser gerada. Aceita application/json (texto) ou multipart/form-data (texto com arquivos).

sendMensages[].usage.token é o consumo do turno em créditos — o mesmo valor debitado no painel. O header X-user-message traz o ID da mensagem enviada.

Envio de arquivos

Com multipart/form-data, envie os arquivos no campo files, repetindo a parte uma vez por arquivo (file continua aceito para um arquivo só). Arquivos de tipos diferentes podem ir na mesma mensagem: o tipo de cada um é identificado pelo próprio arquivo. Envie sempre text com a instrução sobre os arquivos.

Fora dos limites, a resposta é 400 com o motivo em message (ex.: Envie no máximo 5 arquivos por mensagem., Arquivo maior que 20MB., O total dos arquivos excede 50MB.). Campo de arquivo com outro nome — como files[] — é recusado com Campo de arquivo inesperado.

Atenção: falhas na geração não mudam o status. A resposta vem 200 só com {"message": "Estamos enfrentando uma instabilidade temporária. Tente novamente em alguns minutos"}, sem id nem sendMensages. Sem créditos disponíveis, também vem 200, com sendMensages sem id e sem usage. Confira a presença de id antes de tratar o corpo como resposta do agente.

Registra a avaliação de uma resposta do agente: 0 negativo, 1 positivo, 2 neutro.

idmessage é o ID da mensagem do agente: o id devolvido por [Enviar mensagem], o header X-Custom-Info do stream ou o id da interação em [Listar mensagens da conversa].

Registra a nota da pesquisa de satisfação da conversa, de 1 (muito ruim) a 5 (muito bom). Só é aceita quando o agente está com o envio de pesquisa habilitado.

Baixa um arquivo enviado na conversa.

Aceita a chave de API ou o link assinado devolvido em files[].url de [Metadados da conversa]. No link assinado a autenticação vai na própria URL (s, e e sig), sem header, e vale por 90 dias.

Retorna a transcrição de uma mensagem de áudio da conversa. Para mensagens de texto, transcription vem vazio.

Exporta as conversas de um agente, com todas as mensagens, em arquivo. O download começa antes de a exportação terminar (stream).

Atribui uma categoria à conversa pelo nome. Se não existir categoria com esse nome, ela é criada. Espaços e aspas nas pontas são removidos e o nome é cortado no primeiro :.