Fazer a integração do número de telefone
O corpo da requisição é opcional. Incluacatalog_id somente quando o agente precisar usar um catálogo específico da Meta.
Referência da API: POST Onboard Agent · GET Get Settings
403 geralmente significa que o acesso ao produto ou a aceitação dos termos está incompleta. Um 404 em operações posteriores no escopo de telefone pode significar que o Phone Number ID está incorreto ou que o mesmo locatário da YCloud não possui uma vinculação ativa de agente da API pública.
Adicionar um consumidor de teste à lista de permissões
UsePOST /v2/metaBusinessAgents/{entityId}/allowListEntries com exatamente uma identidade não nula:
consumer_phone_number no formato E.164. A API pública usa a identidade que você especificar; ela não pesquisa um BSUID a partir do telefone. As entradas de telefone e BSUID têm IDs independentes e cada uma usa um dos 20 slots compartilhados do WhatsApp. Exclua pelo ID da entrada selecionada.
As respostas de listagem exigem apenas id; uma identidade pode não estar disponível. consumer_instagram_username é aceito apenas como um campo de resposta opcional, não como um recurso de gerenciamento do Instagram.
Configurar comportamento de transição e acompanhamento
Defina essas mensagens e intervalos como parte da configuração do agente, antes de testar o fluxo de transferência. Referência da API: GET Get Settings · PUT Replace Settingsfollowup_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 preservar 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 fatos 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 InfoAdicionar 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 FAQPATCH, envie tanto question quanto answer. A Meta pode retornar um novo id e redefinir created_at para a hora da atualização. Use o ID retornado para solicitações posteriores. Um tempo limite ou 502 não comprova que a atualização falhou; não tente novamente de forma automática nem crie um FAQ de substituição.
Adicionar sites e arquivos
Use sites e arquivos apenas quando o conteúdo deles for atualizado e adequado para respostas 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 seuurl. Use /websites/{websiteId} para recuperá-la, atualizá-la ou excluí-la. As solicitações aceitam os campos de escopo included_sub_domains, included_url_patterns, excluded_sub_domains, excluded_url_patterns e single_urls. Omita um campo de escopo para deixá-lo não especificado; envie [] para limpá-lo.
As respostas podem incluir todos os cinco arrays de escopo, crawl_error, crawl_status, pages_crawled, last_crawled_at e created_at.
Uma atualização pode retornar um id diferente; use o ID retornado para leituras, atualizações e exclusões subsequentes. Não repita automaticamente uma atualização com resultado incerto. O rastreamento é assíncrono, portanto, uma resposta de criação bem-sucedida não significa que todas as páginas foram indexadas.
Faça upload de um arquivo como multipart/form-data com uma parte chamada file:
/files; recupere ou exclua um em /files/{fileId}.
Adicionar habilidades comportamentais
As habilidades explicam como o agente deve lidar com uma tarefa. O conhecimento explica o que é verdadeiro. Referência da API: GET List Skills · POST Create Skill · GET Get Skill · PATCH Update Skill · DELETE Delete Skillchannel, created_at e metadados de string.
Defina um objetivo para cada habilidade. Indique 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 UI Skills
As UI Skills 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
Os tipos de componente compatíveis 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 UI Skill se precisar de um tipo de componente diferente ou de uma associação de Flow. As solicitações de listagem são compatíveis com before, after e limit. Continue a paginação enquanto paging.next estiver presente. Os carimbos de data/hora 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 dos dois recursos quando o conhecimento estático for suficiente.Configurar o conector
Referência da API Connector: GET List Connectors · POST Create Connector · GET Get Connector · PATCH Update Connector · POST Refresh MCP Connector Tools · DELETE Delete Connector Referência da API Credential: PUT Upsert API Key · PUT Upsert OAuth Credentials · PUT Upsert Certificatename, description, base_url e auth_type são obrigatórios para solicitaçõ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 chave de API, 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.
Credenciais de 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 texto PEM em client_certificate e client_key; ca_certificate é opcional. Nunca registre corpos de solicitação de credenciais em logs.
Use /connectors para listar ou criar conectores. Use /connectors/{connectorId} para recuperar, atualizar ou excluir um conector. Substitua credenciais por meio de seu sub-recurso /credentials/apiKey, /credentials/oauth ou /credentials/certificate.
Para um conector MCP, chame /connectors/{connectorId}/refreshMCPTools com o Meta Connector ID retornado pela API Connector para solicitar que a Meta redescubra suas ferramentas. Não envie corpo de solicitaçã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 ela 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 tente novamente de forma automática; após um tempo limite, recupere o conector porque o resultado da atualização é incerto.
Definir ferramentas
Referência da API Tool: GET List Connector Tools · POST Create Connector Tool · GET Get Connector Tool · PATCH Update Connector Tool · DELETE Delete Connector Tool
Crie e liste ferramentas em
/connectors/{connectorId}/tools. Recupere, atualize ou exclua uma em /tools/{toolId}.
As definições de parâmetros incluem um type de dados, uma description legível por humanos, uma flag de obrigatório e uma binding opcional. Uma vinculação pode fornecer um valor fixo, uma macro ou uma entrada em tempo de execução.
As solicitações de criação e atualização exigem name, description, request_definition e user_auth_required. Uma definição de solicitaçã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
Umtransformation_spec não nulo exige version=1 e steps, com no máximo cinco etapas ordenadas.
Cada etapa exige kind. Os 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:
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 de sucesso do conector pode contermcp_tool_sync.status=ERROR; isso significa que a descoberta de ferramentas falhou. Criar um conector não
estipula 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.
A seguir: Testar e avaliar
Valide respostas e cenários de negócios representativos.

