Saltar para o conteúdo principal
Configure o comportamento de transferência e acompanhamento em Integrar e configurar e valide-o em Testar e avaliar. Durante a operação, o agente, o fluxo de trabalho de suporte humano e a automação de back-end não devem presumir que controlam a mesma conversa ao mesmo tempo.

Inspecionar turnos de conversa

Use turnos de conversa para investigar latência, erros e a sequência de chamadas de LLM e ferramentas para um usuário do WhatsApp. Referência da API: GET Get Conversation Turns
user_phone_number deve conter apenas o código do país e dígitos. Não inclua um + inicial, espaços ou separadores. Os limites de timestamp são milissegundos Unix epoch inclusivos. Não combine before e after. Cada turno requer conversation_id, turn_id e steps. message_id é opcional, e a resposta não contém session_id. Cada etapa tem o tipo LLM_CALL ou TOOL_CALL e pode ter o status SUCCESS, ERROR ou TIMEOUT. Continue a paginação enquanto paging.next estiver presente, mesmo quando o array data atual estiver vazio ou contiver menos itens do que limit.

Controlar a conversa de um cliente

Use pass, release ou take com o endpoint geral de controle de conversa. Forneça to como um número de telefone E.164 ou ID do WhatsApp. metadata é opcional e suporta até 2.000 caracteres. Referência da API: POST Control Thread
Liberar o controle impede que o agente responda nessa conversa. O contexto da conversa pode ser perdido quando o controle retornar posteriormente ao agente. A superfície REST atual não expõe um endpoint que informe o proprietário atual da conversa, portanto, sua integração deve rastrear as transições solicitadas e seus resultados.

Enviar e rastrear eventos de negócios

Envie um evento apenas enquanto o agente estiver no controle da conversa do cliente. Referência da API: POST Submit Agent Event · GET Get Agent Event Status
Quando disponível, a resposta de status inclui conversation_id, o mesmo identificador opaco retornado por Conversation Turns. Use-o para correlacionar registros, não como um ID de evento ou comprovante de entrega de mensagem. O campo pode estar ausente. Guarde agent_event_id da resposta e consulte periodicamente GET Get Agent Event Status para obter o estado de processamento, timestamps, error_message ou skipped_reason. Um envio bem-sucedido confirma apenas que o evento foi aceito para processamento assíncrono; ele não garante uma resposta voltada ao cliente. Um evento ignorado pode significar que o agente não controla mais a conversa.

Inspecionar logs de execução do conector

Consulte GET List Connector Logs quando uma chamada de ferramenta falhar ou ficar lenta. A resposta combina entradas de log com contagens, taxa de sucesso e estatísticas de latência. As consultas de log do conector suportam um intervalo de tempo delimitado. O limite upstream atual é de sete dias. Verifique o posicionamento das credenciais, o estado do certificado, os vínculos da solicitação e as definições da ferramenta antes de tentar novamente uma operação que está falhando.

Lidar com solicitações com falha com segurança

A YCloud preserva o status HTTP relevante do upstream e retorna um envelope de erro seguro em vez de expor credenciais ou respostas brutas do upstream. Quando o serviço upstream não retorna um erro utilizável, a YCloud pode retornar MBA_UPSTREAM_UNAVAILABLE. Tente ler novamente com recuo exponencial limitado para 429, 500 e 502. Antes de tentar novamente uma solicitação de criação, atualização, exclusão, evento, teste, execução de ferramenta, credencial ou multipart, determine se a gravação original já surtiu efeito. Registre os dois IDs de solicitação e uma estrutura de solicitação higienizada ao encaminhar uma falha repetida.

Planejar para as limitações de acesso antecipado

Os seguintes comportamentos são limitações, não garantias do contrato REST da YCloud:
  • Algumas falhas de elegibilidade aparecem como 500 em vez de uma resposta estável de inelegibilidade.
  • O teste de agentes pode depender das configurações de distribuição (rollout) e de público.
  • O contexto da conversa pode ser perdido após a transferência humana e o retorno.
  • Tabelas em PDF ou CSV podem não ser interpretadas de maneira confiável.
  • O agente pode não enviar arquivos ou imagens a clientes de forma confiável.
  • Conectores MCP não estão disponíveis; use ferramentas e conectores HTTP.
  • O faturamento e o comportamento comercial podem mudar enquanto o produto estiver em acesso antecipado.

Excluir o agente ao desativar o número de telefone

Envie DELETE Delete Agent apenas quando o agente precisar ser removido desse número de telefone do WhatsApp Business. Uma solicitação bem-sucedida retorna HTTP 200 e pode incluir deleted_agent_id quando a resposta upstream a fornecer. Excluir o agente é diferente de desativar a distribuição (rollout). Use rollout.enabled=false quando precisar de uma pausa reversível.