Saltar para o conteúdo principal
Este guia cria o agente e define sua configuração. A integração (onboarding) prepara os recursos do agente; ela não faz com que o agente responda a todos os clientes.

Fazer a integração do número de telefone

O corpo da requisição é opcional. Inclua catalog_id somente quando o agente precisar usar um catálogo específico da Meta. Referência da API: POST Onboard Agent · GET Get Settings
Guarde o identificador retornado:
A integração agenda a preparação em segundo plano. A superfície REST atual da YCloud não fornece um endpoint separado para o status da integração. Após uma resposta bem-sucedida, use GET Get Settings para confirmar se os recursos com escopo de telefone estão prontos. Se uma leitura falhar temporariamente, tente lê-la novamente após um breve intervalo; não repita a integração às cegas. 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 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

Use POST /v2/metaBusinessAgents/{entityId}/allowListEntries com exatamente uma identidade não nula:
Como alternativa, forneça 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 Settings
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 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 Info
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
Use os endpoints de coleção vinculados para listar ou criar FAQs, e os endpoints de item vinculados para recuperar, atualizar ou excluir um FAQ. Para PATCH, 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 seu url. 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:
A YCloud exige um nome de arquivo original não vazio e aceita arquivos de solicitação de até 100.000.000 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 presuma que o agente possa enviar a imagem ou o arquivo de origem de volta a um cliente.

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 Skill
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. 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 Certificate name, 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

Um transformation_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:
O campo omitido preserva a transformação atual. Para excluí-la:
Para defini-la:
As macros de vinculaçã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 de sucesso do conector pode conter mcp_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.