> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operar e solucionar problemas

> Controle threads de conversa, processe eventos, inspecione logs, lide com falhas e desative um Meta Business Agent com segurança.

Configure o comportamento de transferência e acompanhamento em [Onboard and configure](/pt/documentation/meta-business-agent/onboard-and-configure) e valide-o em [Test and evaluate](/pt/documentation/meta-business-agent/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](/api-reference/meta-business-agents/get-conversation-turns)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/control-thread)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/submit-agent-event) · [GET Get Agent Event Status](/api-reference/meta-business-agents/get-agent-event-status)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/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](/api-reference/meta-business-agents/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](/api-reference/meta-business-agents/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.