Operar e solucionar problemas

Configure o comportamento de transferência e acompanhamento em Onboard and configure e valide-o em Test and evaluate. Durante a operação, o agente, o fluxo de trabalho de suporte humano e a automação de back-end não devem assumir que controlam a mesma thread ao mesmo tempo.

Inspecionar turnos de conversa

Use os turnos de conversa para investigar a latência, os 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

curl --get \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/conversationTurns" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --data-urlencode "user_phone_number=14155550123" \
  --data-urlencode "start_timestamp_ms=1788134400000" \
  --data-urlencode "end_timestamp_ms=1788220800000" \
  --data-urlencode "limit=50"

user_phone_number deve conter apenas o código do país e os dígitos. Não inclua um + inicial, espaços ou separadores. Os limites de carimbo de data/hora são milissegundos de época Unix 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 a matriz data atual estiver vazia ou contiver menos itens que limit.

Controlar uma thread de cliente

Use pass, release ou take com o endpoint geral de controle de thread. 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

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/threadControl" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "release",
    "to": "+14155550123",
    "metadata": "Escalated to order support"
  }'

Liberar o controle impede que o agente responda nessa thread. 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 relata o proprietário atual da thread, 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 controlar a thread do cliente. Referência da API: POST Submit Agent Event · GET Get Agent Event Status

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/events" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+14155550123",
    "event": {
      "type": "order_status_changed",
      "description": "The customer order moved to shipped.",
      "payload": "{\"order_id\":\"ORD-1001\",\"status\":\"shipped\"}"
    }
  }'

Campo	Limite	Significado
`to`	E.164	Número de telefone do WhatsApp do consumidor.
`event.type`	256 caracteres	Tipo de evento estável.
`event.description`	1.024 caracteres	Significado em linguagem simples do evento.
`event.payload`	4.096 caracteres	JSON opaco serializado como uma string.

Retenha agent_event_id da resposta e pesquise GET Get Agent Event Status para estado de processamento, carimbos de data/hora, error_message ou skipped_reason. Um envio bem-sucedido confirma apenas que o evento foi aceito para processamento assíncrono; não garante uma resposta voltada para o cliente. Um evento ignorado pode significar que o agente não controla mais a thread.

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 limitado. O limite upstream atual é de sete dias. Verifique o posicionamento da credencial, o estado do certificado, as associações de solicitação e as definições de ferramentas antes de tentar novamente uma operação com falha.

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

A YCloud preserva o status HTTP upstream relevante e retorna um envelope de erro seguro em vez de expor respostas upstream brutas ou credenciais.

Campo	Significado
`status`	Código de status HTTP.
`code`	Código de erro da YCloud.
`message`	Resumo voltado para o desenvolvedor.
`target`	Destino da solicitação relacionada, quando disponível.
`docUrl`	URL da documentação da YCloud relacionada, quando disponível.
`requestId`	Identificador da YCloud usado para suporte e correlação de log.
`metaBusinessAgentApiError.title`	Título do erro upstream, quando seguro e disponível.
`metaBusinessAgentApiError.detail`	Detalhe upstream acionável.
`metaBusinessAgentApiError.type`	Categoria de erro upstream ou URI.
`metaBusinessAgentApiError.status`	Status upstream.
`metaBusinessAgentApiError.requestId`	Identificador de solicitação upstream.

Quando o serviço upstream não retorna um erro utilizável, a YCloud pode retornar MBA_UPSTREAM_UNAVAILABLE.

Sintoma	O que verificar
`401`	Verifique a chave de API da YCloud e o acesso do locatário. Não envie um token de acesso da Meta.
`403`	Verifique o acesso ao produto e a aceitação dos termos para a empresa proprietária.
`404`	Verifique o ID do número de telefone e a associação do agente da API pública ativa do locatário.
O teste não retorna resposta	Verifique a implementação, o público, a lista de permissões, a elegibilidade e `no_response_reason`.
O site permanece pendente	O rastreamento é assíncrono; recupere o recurso do site novamente mais tarde.
A chamada do conector falha	Verifique os logs, as credenciais, o estado do certificado e as associações de parâmetros.

Tente novamente as leituras 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 multipartes, determine se a gravação original já entrou em vigor. Registre os IDs de solicitação e uma forma de solicitação higienizada ao escalar uma falha repetida.

Planejar 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 de inelegibilidade estável.
O teste do agente pode depender das configurações de lançamento e de público.
O contexto da conversa pode ser perdido após a transferência para um humano e o retorno.
Tabelas em PDF ou CSV podem não ser interpretadas de forma confiável.
O agente pode não enviar arquivos ou imagens aos consumidores de forma confiável.
Conectores MCP não estão disponíveis; use conectores e ferramentas 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 dever 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 o fornecer. Excluir o agente é diferente de desativar o lançamento. Use rollout.enabled=false quando precisar de uma pausa reversível.

Primeiros passos

Guias

Endpoints

Webhooks

Operar e solucionar problemas

Inspecionar turnos de conversa

Controlar uma thread de cliente

Enviar e rastrear eventos de negócios

Inspecionar logs de execução do conector

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

Planejar limitações de acesso antecipado

Excluir o agente ao desativar o número de telefone

​Inspecionar turnos de conversa

​Controlar uma thread de cliente

​Enviar e rastrear eventos de negócios

​Inspecionar logs de execução do conector

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

​Planejar limitações de acesso antecipado

​Excluir o agente ao desativar o número de telefone

Inspecionar turnos de conversa

Controlar uma thread de cliente

Enviar e rastrear eventos de negócios

Inspecionar logs de execução do conector

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

Planejar limitações de acesso antecipado

Excluir o agente ao desativar o número de telefone