Integrar e configurar

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 · GET Get Settings

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:

{
  "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 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 · PUT Replace Settings

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 · PUT Replace Business Info · DELETE 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.

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 · POST Create FAQ · GET Get FAQ · PATCH Update FAQ · DELETE 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.

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 · POST Create Website · GET Get Website · PATCH Update Website · DELETE Delete Website Referência da API de Arquivos: GET List Files · POST Upload File · GET Get File · DELETE 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:

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

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.

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 · POST Create Skill · GET Get Skill · PATCH Update Skill · DELETE 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.

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 · POST Create UI Skill · GET Get UI Skill · PATCH Update UI Skill · DELETE Delete UI Skill

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 · POST Criar Conector · GET Obter Conector · PATCH Atualizar Conector · POST Atualizar Ferramentas do Conector MCP · DELETE Excluir Conector Referência da API de Credenciais: PUT Upsert API Key · PUT Upsert Credenciais OAuth · PUT Upsert Certificado

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 · POST Criar Ferramenta do Conector · GET Obter Ferramenta do Conector · PATCH Atualizar Ferramenta do Conector · DELETE Excluir Ferramenta do Conector

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:

{"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:

{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false,"transformation_spec":null}

Para defini-la:

{"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.

Próximo: Testar e avaliar

Valide as respostas e os cenários de negócios representativos.

Primeiros passos

Guias

Endpoints

Webhooks

Integrar e configurar

Integrar o número de telefone

Configurar comportamento de transferência e acompanhamento

Configurar informações da empresa

Adicionar perguntas frequentes

Adicionar sites e arquivos

Adicionar habilidades comportamentais

Adicionar habilidades de UI

Adicionar conectores e ferramentas apenas quando necessário

Configurar o conector

Definir ferramentas

Transformar respostas de ferramentas

Verificar o estado de descoberta do MCP

Próximo: Testar e avaliar

​Integrar o número de telefone

​Configurar comportamento de transferência e acompanhamento

​Configurar informações da empresa

​Adicionar perguntas frequentes

​Adicionar sites e arquivos

​Adicionar habilidades comportamentais

​Adicionar habilidades de UI

​Adicionar conectores e ferramentas apenas quando necessário

​Configurar o conector

​Definir ferramentas

​Transformar respostas de ferramentas

​Verificar o estado de descoberta do MCP

Próximo: Testar e avaliar

Integrar o número de telefone

Configurar comportamento de transferência e acompanhamento

Configurar informações da empresa

Adicionar perguntas frequentes

Adicionar sites e arquivos

Adicionar habilidades comportamentais

Adicionar habilidades de UI

Adicionar conectores e ferramentas apenas quando necessário

Configurar o conector

Definir ferramentas

Transformar respostas de ferramentas

Verificar o estado de descoberta do MCP