> ## 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.

# Integrar e configurar

> Crie um Meta Business Agent e configure suas definições, conhecimento, habilidades, conectores e ferramentas.

Este guia cria o agente e define sua configuração. A integração prepara os recursos do agente; ela não faz com que o agente responda a todos os clientes.

## Integrar o número de telefone

O corpo da requisição é opcional. Inclua `catalog_id` apenas quando o agente deve usar um catálogo específico da Meta.

**Referência da API:** [POST Onboard Agent](/api-reference/meta-business-agents/onboard-agent) · [GET Get Settings](/api-reference/meta-business-agents/get-settings)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/onboarding" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'
```

Guarde o identificador retornado:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "agent_id": "AGENT_ID"
}
```

A integração agenda uma preparação em segundo plano. A superfície REST atual da YCloud não fornece um endpoint separado para status de integração. Após uma resposta bem-sucedida, use [GET Get Settings](/api-reference/meta-business-agents/get-settings) para confirmar que os recursos vinculados ao telefone estão prontos. Se uma leitura falhar temporariamente, tente a leitura novamente após um breve intervalo; não repita a integração sem necessidade.

Um `403` geralmente significa que o acesso ao produto ou a aceitação dos termos está incompleta. Um `404` em operações posteriores no escopo do telefone pode indicar que o ID do número de telefone está incorreto ou que o mesmo locatário da YCloud não possui uma vinculação ativa de agente na Public API.

## Configurar comportamento de transferência e acompanhamento

Defina estas mensagens e prazos como parte da configuração do agente, antes de testar o fluxo de transferência.

**Referência da API:** [GET Get Settings](/api-reference/meta-business-agents/get-settings) · [PUT Replace Settings](/api-reference/meta-business-agents/replace-settings)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/settings" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "handoff": {
      "enabled": true,
      "message_selection": "CUSTOM",
      "message": "I am connecting you with a support specialist."
    },
    "followup": {
      "enabled": true,
      "followup_interval_in_seconds": 3600,
      "message": "Do you still need help?"
    },
    "never_say_phrases": ["I guarantee delivery by tomorrow"]
  }'
```

| Campo | Significado |
| - | - |
| `handoff.enabled` | Se o agente pode transferir uma conversa para um fluxo de trabalho humano. |
| `handoff.message_selection` | Origem da mensagem de transferência: `DEFAULT`, `AGENT` ou `CUSTOM`. |
| `handoff.message` | Mensagem voltada ao cliente enviada quando a transferência é acionada. |
| `followup.enabled` | Se o agente envia uma mensagem de acompanhamento após inatividade. |
| `followup.followup_interval_in_seconds` | Intervalo antes do acompanhamento. |
| `followup.message` | Mensagem de acompanhamento voltada ao cliente. |
| `never_say_phrases` | Lista completa de frases que o agente não deve dizer. |

`followup_interval_in_seconds` deve ser um dos seguintes: `0`, `300`, `900`, `1800`, `3600`, `7200`, `28800` ou `86400`. Quando `handoff.message_selection` for `CUSTOM`, inclua `handoff.message`.

A YCloud atualiza apenas as configurações incluídas na requisição. Omita `never_say_phrases` para manter a lista atual. Envie um array vazio para limpá-la, ou um array não vazio para substituir a lista completa.

## Configurar informações da empresa

Use as informações da empresa para dados estáveis que se aplicam a todas as dúvidas dos clientes.

**Referência da API:** [GET Get Business Info](/api-reference/meta-business-agents/get-business-info) · [PUT Replace Business Info](/api-reference/meta-business-agents/replace-business-info) · [DELETE Delete Business Info](/api-reference/meta-business-agents/delete-business-info)

| Campo | Significado |
| - | - |
| `payment_method` | Métodos e condições de pagamento que os clientes devem conhecer. |
| `return_policy` | Política de devolução, reembolso ou troca. |
| `purchase_info` | Como os clientes podem comprar, reservar ou fazer um pedido. |
| `delivery_and_shipping` | Áreas de entrega, métodos, taxas e prazos. |
| `business_description` | Descrição em linguagem simples sobre a empresa e suas ofertas. |
| `contact_info.email` | E-mail de contato voltado ao cliente. |
| `contact_info.hours_of_operation` | Horário de funcionamento ou de atendimento legível por humanos. |
| `contact_info.address` | Endereço comercial voltado ao cliente. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/businessInfo" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "business_description": "Example Store sells home and office products.",
    "return_policy": "Unused items can be returned within 30 days.",
    "delivery_and_shipping": "Standard delivery takes 3 to 5 business days."
  }'
```

O objeto de informações da empresa é fechado. Envie apenas os campos definidos pelo esquema da API da YCloud.

## Adicionar perguntas frequentes

Mantenha uma intenção do cliente por FAQ. Atualize ou exclua respostas desatualizadas em vez de adicionar itens quase duplicados.

**Referência da API:** [GET List FAQs](/api-reference/meta-business-agents/list-faqs) · [POST Create FAQ](/api-reference/meta-business-agents/create-faq) · [GET Get FAQ](/api-reference/meta-business-agents/get-faq) · [PATCH Update FAQ](/api-reference/meta-business-agents/update-faq) · [DELETE Delete FAQ](/api-reference/meta-business-agents/delete-faq)

| Campo | Obrigatório | Significado |
| - | - | - |
| `question` | Sim | Pergunta do cliente escrita em linguagem natural. |
| `answer` | Sim | Resposta factual que o agente deve usar. |
| `metadata` | Não | Metadados de string para string mantidos com a FAQ. |
| `id` | Apenas resposta | Identificador usado para recuperar, atualizar ou excluir a FAQ. |
| `created_at` | Apenas resposta | Carimbo de data/hora de criação. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/faqs" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "question": "How can I return an item?",
    "answer": "Contact support with your order number within 30 days of delivery."
  }'
```

Use os endpoints de coleção vinculados para listar ou criar FAQs, e os endpoints de item vinculados para recuperar, atualizar ou excluir uma FAQ.

## Adicionar sites e arquivos

Use sites e arquivos apenas quando o conteúdo deles estiver atualizado e for adequado para responder aos clientes.

**Referência da API de Sites:** [GET List Websites](/api-reference/meta-business-agents/list-websites) · [POST Create Website](/api-reference/meta-business-agents/create-website) · [GET Get Website](/api-reference/meta-business-agents/get-website) · [PATCH Update Website](/api-reference/meta-business-agents/update-website) · [DELETE Delete Website](/api-reference/meta-business-agents/delete-website)

**Referência da API de Arquivos:** [GET List Files](/api-reference/meta-business-agents/list-files) · [POST Upload File](/api-reference/meta-business-agents/upload-file) · [GET Get File](/api-reference/meta-business-agents/get-file) · [DELETE Delete File](/api-reference/meta-business-agents/delete-file)

Crie uma fonte de site com sua `url`. Use `/websites/{websiteId}` para recuperá-la, atualizá-la ou excluí-la. As respostas de sites podem incluir `crawl_status`, `pages_crawled`, `last_crawled_at` e `created_at`. A indexação (crawling) é assíncrona, portanto, uma resposta de criação bem-sucedida não significa que todas as páginas foram indexadas.

Envie um arquivo como `multipart/form-data` com uma parte chamada `file`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/files" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --form "file=@./returns-policy.pdf"
```

A YCloud exige um nome de arquivo original não vazio e aceita arquivos de requisição de até 100.000.000 de bytes. A Meta controla a aceitação final do tipo de arquivo e do conteúdo. Liste arquivos em `/files`; recupere ou exclua um em `/files/{fileId}`.

<Warning>
  Tabelas em arquivos PDF ou CSV podem não ser interpretadas de maneira confiável. Trate os arquivos como fontes de recuperação e teste conteúdos representativos. Não assuma que o agente pode enviar a imagem ou o arquivo de origem de volta para o cliente.
</Warning>

## Adicionar habilidades comportamentais

As habilidades explicam como o agente deve lidar com uma tarefa. O conhecimento explica o que é verdade.

**Referência da API:** [GET List Skills](/api-reference/meta-business-agents/list-skills) · [POST Create Skill](/api-reference/meta-business-agents/create-skill) · [GET Get Skill](/api-reference/meta-business-agents/get-skill) · [PATCH Update Skill](/api-reference/meta-business-agents/update-skill) · [DELETE Delete Skill](/api-reference/meta-business-agents/delete-skill)

| Campo | Limite | Significado |
| - | - | - |
| `agent_id` | Opcional | ID do agente quando a seleção explícita for necessária. |
| `title` | 64 caracteres | Letras minúsculas, números e hifens, sem hífen no início ou no final. |
| `description` | 1.024 caracteres | Quando a habilidade deve ser usada. |
| `skill` | 20.000 caracteres | Instruções comportamentais completas. |
| `id` | Apenas resposta | Identificador usado para recuperar, atualizar ou excluir a habilidade. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/skills" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "return-request",
    "description": "Collect the information needed to start a return.",
    "skill": "Ask for the order number. Explain the return policy. If the item is outside the policy, offer human handoff."
  }'
```

Use os endpoints de coleção vinculados para listar ou criar habilidades, e os endpoints de item vinculados para recuperar, atualizar ou excluir uma. As respostas também podem incluir `channel`, `created_at` e metadados de string.

Dê a cada habilidade um único objetivo. Especifique quando usá-la, coloque regras obrigatórias antes dos exemplos e defina o que fazer quando faltarem informações. Mantenha fatos voláteis em informações comerciais, FAQs, sites ou arquivos.

## Adicionar habilidades de UI

As habilidades de UI controlam quais componentes avançados do WhatsApp o agente pode apresentar. As habilidades comportamentais definem como o agente deve lidar com uma tarefa.

**Referência da API:** [GET List UI Skills](/api-reference/meta-business-agents/list-ui-skills) · [POST Create UI Skill](/api-reference/meta-business-agents/create-ui-skill) · [GET Get UI Skill](/api-reference/meta-business-agents/get-ui-skill) · [PATCH Update UI Skill](/api-reference/meta-business-agents/update-ui-skill) · [DELETE Delete UI Skill](/api-reference/meta-business-agents/delete-ui-skill)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/uiSkills" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Choose a support topic",
    "component_type": "interactive_reply_buttons",
    "status": "enabled",
    "instruction": "Use these reply buttons when the customer asks for support but has not selected a topic."
  }'
```

| Campo | Significado |
| - | - |
| `title` | Título de exibição da habilidade de UI. |
| `component_type` | Componente avançado do WhatsApp que o agente pode apresentar. |
| `status` | `enabled` ou `disabled`. |
| `instruction` | Quando o agente deve usar este componente. |
| `flow_id` | ID do WhatsApp Flow. Obrigatório apenas quando `component_type` for `flow`; omita-o para todos os outros tipos. |

Os tipos de componentes suportados são `carousel_quick_reply`, `carousel_url`, `cta_url`, `flow`, `image`, `interactive_list`, `interactive_reply_buttons`, `location` e `location_request`.

O endpoint de atualização altera apenas `title`, `status` e `instruction`. Crie uma nova habilidade de UI se precisar de um tipo de componente ou associação de Flow diferente. As requisições de listagem suportam `before`, `after` e `limit`. Continue a paginação enquanto `paging.next` estiver presente. Os carimbos de data/hora (timestamps) da resposta estão em segundos da época Unix.

## Adicionar conectores e ferramentas apenas quando necessário

Um conector define um serviço HTTP externo ou um servidor MCP remoto. Uma ferramenta define uma operação que o agente pode chamar nesse conector. Não adicione nenhum desses recursos quando o conhecimento estático for suficiente.

### Configurar o conector

**Referência da API do Conector:** [GET Listar Conectores](/api-reference/meta-business-agents/list-connectors) · [POST Criar Conector](/api-reference/meta-business-agents/create-connector) · [GET Obter Conector](/api-reference/meta-business-agents/get-connector) · [PATCH Atualizar Conector](/api-reference/meta-business-agents/update-connector) · [POST Atualizar Ferramentas do Conector MCP](/api-reference/meta-business-agents/refresh-mcp-connector-tools) · [DELETE Excluir Conector](/api-reference/meta-business-agents/delete-connector)

**Referência da API de Credenciais:** [PUT Upsert API Key](/api-reference/meta-business-agents/upsert-connector-api-key) · [PUT Upsert Credenciais OAuth](/api-reference/meta-business-agents/upsert-connector-o-auth) · [PUT Upsert Certificado](/api-reference/meta-business-agents/upsert-connector-certificate)

| Campo | Significado |
| - | - |
| `name` | Nome do conector visível para a configuração do agente. |
| `description` | Finalidade e limites do serviço externo. |
| `base_url` | URL base HTTP ou endereço remoto do servidor MCP. |
| `connector_protocol` | `HTTP` ou `MCP` opcional; a omissão na criação assume o padrão HTTP. O protocolo não pode ser alterado após a criação. |
| `auth_type` | Estratégia de autenticação. |
| `auth_config` | Configuração de credenciais do cliente OAuth ou API-key. |
| `user_auth_injection_config` | Onde e como a credencial de usuário é injetada. |
| `requires_certificate` | Se o conector espera credenciais mTLS. |
| `connection_status` | Estado de validação retornado do conector e erro opcional. |
| `mtls_config` | Presença de certificado e metadados retornados. |
| `mcp_tool_sync` | Metadados opcionais de descoberta anuláveis: `status=ERROR`, `PENDING` ou `READY`, timestamps de tentativa/sucesso em segundos Unix, `fingerprint` e `tool_count`. |

`name`, `description`, `base_url` e `auth_type` são obrigatórios para requisições de criação e atualização. Os tipos de autenticação padrão são `OAUTH2_CLIENT_CREDENTIALS`, `API_KEY` e `NONE`. A Meta pode rejeitar outro valor de contrato que não esteja habilitado para a conta.

Para autenticação por API-key, injete valores em `headers`, `query_params` ou `body_params`. Cada item requer `field_name` e `value` não vazios; `prefix` é opcional. Pelo menos um item deve estar presente.

As credenciais do cliente OAuth requerem `token_url`, `scopes_to_request`, `client_id` e `client_secret`. Quando fornecido, `token_request_content_type` deve ser `application/x-www-form-urlencoded` ou `application/json`. Para mTLS, forneça o texto em PEM em `client_certificate` e `client_key`; `ca_certificate` é opcional. Nunca registre corpos de requisição de credenciais em logs.

Use `/connectors` para listar ou criar conectores. Use `/connectors/{connectorId}` para recuperar, atualizar ou excluir um. Substitua credenciais por meio do sub-recurso `/credentials/apiKey`, `/credentials/oauth` ou `/credentials/certificate`.

Para um conector MCP, chame `/connectors/{connectorId}/refreshMCPTools` com o ID do Conector da Meta retornado pela API do Conector para solicitar que a Meta redescubra suas ferramentas. Não envie corpo na requisição. O HTTP `200` retorna o conector atual, mas nem sempre significa que a descoberta foi bem-sucedida. Verifique `mcp_tool_sync.status`: `READY` significa que a descoberta foi concluída, `PENDING` significa que ainda está em andamento e `ERROR` significa que a descoberta remota ou o provisionamento falhou. A operação não possui chave de idempotência. Não a repita automaticamente; após um tempo limite (timeout), recupere o conector, pois o resultado da atualização é incerto.

### Definir ferramentas

**Referência da API de Ferramentas:** [GET Listar Ferramentas do Conector](/api-reference/meta-business-agents/list-connector-tools) · [POST Criar Ferramenta do Conector](/api-reference/meta-business-agents/create-connector-tool) · [GET Obter Ferramenta do Conector](/api-reference/meta-business-agents/get-connector-tool) · [PATCH Atualizar Ferramenta do Conector](/api-reference/meta-business-agents/update-connector-tool) · [DELETE Excluir Ferramenta do Conector](/api-reference/meta-business-agents/delete-connector-tool)

| Campo | Significado |
| - | - |
| `name` | Nome da ferramenta utilizado pelo agente. |
| `description` | Gatilho e resultado esperado utilizados para a seleção da ferramenta. |
| `request_definition.method` | `GET`, `POST`, `PUT`, `DELETE` ou `PATCH`. |
| `request_definition.path` | Caminho relativo a `base_url`. |
| `request_definition.path_parameters` | Definições de parâmetros de caminho nomeados. |
| `request_definition.query_parameters` | Definições de parâmetros de consulta nomeados. |
| `request_definition.headers` | Definições de cabeçalhos de requisição nomeados. |
| `request_definition.body` | Campos do corpo JSON e lista de campos obrigatórios. |
| `user_auth_required` | Se a operação necessita de uma credencial do usuário final. |
| `transformation_spec` | Transformação ordenada de resposta opcional e anulável. Omita na atualização para mantê-la, envie `null` para excluí-la ou envie um objeto para defini-la. |
| `user_auth_action_config` | Como ler os valores de token, refresh-token e expiração de uma ação de autenticação. |

Crie e liste ferramentas em `/connectors/{connectorId}/tools`. Obtenha, atualize ou exclua uma em `/tools/{toolId}`.

As definições de parâmetros incluem um `type` de dados, `description` legível para humanos, sinalizador obrigatório e `binding` opcional. Uma associação (binding) pode fornecer um valor fixo, macro ou entrada em tempo de execução.

As requisições de criação e atualização exigem `name`, `description`, `request_definition` e `user_auth_required`. A definição de uma requisição exige `method` e `path`. Um corpo exige `content_type=application/json` e um objeto `params`. Quando fornecido, `user_auth_action_config` exige `user_action_tool_type` (`auth` ou `refresh`) e `user_auth_token_path`; `expires_at_type` deve ser `absolute` ou `relative_seconds`. Definições inválidas de conector ou ferramenta retornam HTTP `400` sem serem encaminhadas upstream.

### Transformar respostas de ferramentas

Um `transformation_spec` não nulo exige `version=1` e `steps`, com no máximo cinco etapas ordenadas.
Cada etapa exige `kind`. Os campos opcionais `target` e `params` aceitam strings ou `null`; `params` contém
um objeto JSON codificado como string. Uma expressão `math` suporta no máximo quatro níveis aninhados.

Os tipos suportados são `allowlist`, `case`, `catalog`, `decorate_url`, `dedupe`, `dehydrate`, `filter`,
`first_nonempty`, `first_nonnull`, `first_nonzero`, `format`, `html_escape`, `lookup`, `math`,
`proxy_image`, `reshape`, `shadow_allowlist`, `string_replace` e `truncate`.

Na criação, a omissão ou `null` significa nenhuma transformação. Na atualização, estas três entradas diferem:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false}
```

O campo omitido preserva a transformação atual. Para excluí-la:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false,"transformation_spec":null}
```

Para defini-la:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false,"transformation_spec":{"version":1,"steps":[{"kind":"allowlist","params":"{\"paths\":[\"order.id\",\"order.status\"]}"}]}}
```

As macros de associação suportam `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`,
`WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`,
`WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID` e
`INSTAGRAM_CONVERSATION_ID`. Aceitar uma macro do Instagram não habilita entidades do Instagram
nem garante seu valor para um consumidor do WhatsApp.

### Verificar o estado de descoberta do MCP

O MCP usa o mesmo endpoint e campos de autenticação. Uma resposta bem-sucedida do conector pode conter
`mcp_tool_sync.status=ERROR`; isso significa que a descoberta de ferramentas falhou. Criar um conector não
garante que as ferramentas estejam prontas. O tempo da primeira descoberta e as restrições de edição específicas do MCP não
foram verificados. Use a operação de atualização acima quando a Meta precisar redescobrir as ferramentas do conector.

<Card title="Próximo: Testar e avaliar" icon="arrow-right" href="/pt/documentation/meta-business-agent/test-and-evaluate">
  Valide as respostas e os cenários de negócios representativos.
</Card>


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