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 Turnsuser_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
Usepass, 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
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
500em 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 HTTP200 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.
