> For the complete documentation index, see [llms.txt](https://docs.otima.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otima.io/whatsapp/recursos-de-api/meta-business-agent.md). # Meta Business Agent Configure, teste e opere um agente comercial da Meta no WhatsApp Business. O Meta Business Agent atende clientes no WhatsApp com IA da Meta. Use esta API para habilitar o agente, configurar conhecimento, definir habilidades e acompanhar sua operação. {% hint style="success" %} O recurso depende da elegibilidade do número e da conta Meta. Consulte a elegibilidade antes de iniciar o onboarding. {% endhint %} ### Antes de configurar: elegibilidade O número e a conta Meta precisam estar elegíveis. Sem essa liberação, não é possível configurar o Meta Business Agent. Quando o recurso não estiver disponível, a interface exibe: > A Meta ainda não liberou o Meta Business Agent para este número ou conta. Os botões **Configurar**, **Adicionar**, **Gerenciar**, **Testar**, **Publicar** e **Configurações** permanecem bloqueados. Aguarde a habilitação pela Meta e clique em **Atualizar** para verificar novamente. ### Pré-requisitos Você precisa de um número WhatsApp Business ativo no workspace e de um token válido. Consulte [Autenticação](/provedor/canais-de-comunicacao/whatsapp-business/recursos-de-api/autenticacao.md) para gerar as credenciais. Use o telefone ou o `wa_id` como `{entity_id}`. O telefone aceita DDI, pontuação ou E.164. ```http Authorization: Bearer {SEU_TOKEN} x-workspace-uuid: {SEU_UUID_WORKSPACE} X-API-Version: 2.0.0 Accept: application/json Content-Type: application/json ``` A URL base é: ```http POST https://sync-core-api.otima.io/whatsapp/provider ``` Use `multipart/form-data` no envio de arquivos. Em `thread_control`, use `X-API-Version: 1.0.0`. ### Fluxo de configuração {% stepper %} {% step %} #### Verifique a elegibilidade ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_eligibility ``` Continue somente quando a resposta retornar `is_eligible: true`. ```json { "is_eligible": true } ``` {% endstep %} {% step %} #### Inicie o onboarding ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_onboarding?channel=whatsapp ``` Envie `{}`. O onboarding pode ser assíncrono. Aguarde o `agent_id` antes das configurações dependentes. ```json { "agent_id": "agent-123456" } ``` {% endstep %} {% step %} #### Configure o comportamento Consulte `GET` ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/settings ``` Depois, envie a configuração completa com `PUT`. ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/settings ``` ```json { "rollout": { "enabled": true }, "ai_audience": "EVERYONE", "handoff": { "enabled": true, "message": "Vou encaminhar você para um atendente.", "message_selection": "CUSTOM" }, "followup": { "enabled": false, "followup_interval_in_seconds": 900, "message": "" }, "never_say_phrases": [] } ``` Use `ALLOWLISTED_ONLY` para liberar o agente apenas a números autorizados. Os intervalos aceitos são `0`, `300`, `900`, `1800`, `3600`, `7200`, `28800` e `86400` segundos. {% endstep %} {% step %} #### Adicione conhecimento e habilidades Cadastre informações comerciais, FAQs, websites e arquivos. Em seguida, defina skills para orientar comportamentos específicos. {% endstep %} {% step %} #### Teste antes do rollout Use `POST /{entity_id}/agent_test` para simular mensagens. Esse teste não envia uma mensagem real no WhatsApp. {% endstep %} {% endstepper %} ### Configuração pela interface Acesse **Meta Business Agent** no menu lateral do workspace. Selecione a **WABA** e o **Número** no topo. Os dados exibidos abaixo sempre pertencem ao número selecionado.
#### 1. Confirme a elegibilidade na Meta O número e a conta precisam estar elegíveis antes de qualquer configuração. A plataforma verifica essa condição ao carregar o agente. Se a Meta ainda não tiver liberado o recurso, a tela exibirá: > A Meta ainda não liberou o Meta Business Agent para este número ou conta. Nesse caso, as opções de configuração ficam bloqueadas. Isso inclui **Configurar**, **Adicionar**, **Gerenciar**, **Testar**, **Publicar** e **Configurações**. Não é possível iniciar o onboarding ou configurar o agente enquanto a elegibilidade não for liberada. Aguarde a habilitação pela Meta e clique em **Atualizar** para consultar o status novamente.
Quando o número estiver elegível, os cartões mostram a quantidade de **Habilidades**, fontes da **Base de conhecimento** e o **Agent ID**. Use **Atualizar** após mudanças feitas fora desta tela. Use **Publicar** quando a configuração estiver pronta. {% hint style="info" %} Conclua os itens obrigatórios antes de publicar. Arquivos, sites, connectors e testes são opcionais. {% endhint %} #### 2. Preencha as informações da empresa Na linha **Informações da empresa**, clique em **Configurar**. 1. Descreva a empresa, os produtos e o objetivo do atendimento. 2. Informe meios de pagamento, entrega e política de troca. 3. Adicione e-mail, horário e endereço ou canal de atendimento. 4. Clique em **Salvar**. Use informações confirmadas e mantenha prazos específicos fora do texto, quando dependem de consulta. Esses campos são enviados em `PUT /agent_config/business_info`.
#### 3. Cadastre perguntas frequentes Na linha **Perguntas frequentes**, clique em **Configurar**. 1. Escreva uma pergunta como o cliente a faria. 2. Informe uma resposta completa e objetiva. 3. Clique em **Salvar**. As FAQs cadastradas aparecem abaixo do formulário. Use o ícone de lápis para editar. Use a lixeira para excluir. A interface usa `POST`, `PUT` e `DELETE /agent_config/faq`.
#### 4. Defina habilidades Na linha **Habilidades**, clique em **Configurar**. 1. Informe um título em minúsculas, números e hífens. 2. Adicione uma descrição curta do objetivo. 3. Escreva instruções claras sobre como o agente deve agir. 4. Clique em **Salvar**. Cada habilidade atende um cenário específico. Por exemplo, use `tratar-objecoes` para orientar respostas comerciais sem pressão. As habilidades existentes aparecem na lista. Edite com o lápis ou remova com a lixeira. A tela corresponde a `POST`, `PUT` e `DELETE /agent_config/skills`.
#### 5. Adicione arquivos como conhecimento Na linha **Arquivos**, clique em **Adicionar**. 1. Arraste um arquivo ou clique em **Selecionar arquivo**. 2. Aguarde o status de processamento. 3. Clique em **Salvar** para persistir a alteração. São aceitos PDF, DOC, DOCX, PNG, JPG e JPEG de até 100 MB. CSV e XLSX dependem da habilitação do asset. Remova uma fonte pela lixeira. O processamento pode levar alguns minutos. Aguarde a conclusão antes de testar respostas baseadas no arquivo. A interface envia `POST /agent_config/files` em `multipart/form-data`.
#### 6. Adicione sites como conhecimento Na linha **Sites**, clique em **Adicionar**. 1. Informe a URL inicial do site. 2. Salve a fonte. 3. Aguarde o crawl e confirme o status na lista. Mantenha apenas páginas públicas e relevantes. Atualize ou exclua uma URL quando o conteúdo mudar. Esta ação usa as rotas `/agent_config/websites`.
#### 7. Conecte serviços externos Na linha **Connectors**, clique em **Gerenciar**. 1. Informe o nome, a URL base e uma descrição. 2. Selecione o tipo de autenticação: `NONE`, `API_KEY` ou `OAUTH2_CLIENT_CREDENTIALS`. 3. Clique em **Salvar**. O connector aparece abaixo do formulário. Use o lápis para alterar sua configuração. A lixeira remove o connector. Não inclua chaves, tokens ou segredos na descrição. Cadastre credenciais somente nos campos próprios do connector. Depois, crie as tools que o agente pode executar por meio da API.
#### 8. Teste o agente Na linha **Teste seu agente**, clique em **Testar**. 1. Digite uma mensagem em **Mensagem de teste**. 2. Clique em **Enviar** e aguarde a resposta. 3. Confira a conversa simulada à esquerda. 4. Confira o JSON retornado pela Meta à direita. Copie o **ID da conversa** retornado. Informe-o no próximo teste para continuar o mesmo contexto. Deixe o campo vazio para iniciar uma conversa nova. O teste não envia mensagens reais pelo WhatsApp. Durante o processamento, a tela exibe que o agente está respondendo. Ao finalizar, ela mostra `agent_response`, `conversation_id`, `handoff_reason` e outros campos.
#### 9. Ajuste o rollout e o atendimento humano Clique em **Configurações** no canto superior direito. 1. Marque **Ativar rollout do agente** quando estiver pronto. 2. Escolha o público em **Público do agente**. 3. Marque **Permitir encaminhamento para humano**, se necessário. 4. Defina a mensagem de encaminhamento. 5. Opcionalmente, ative o follow-up e informe o intervalo. 6. Adicione uma frase por linha em **Frases que o agente nunca deve dizer**. 7. Clique em **Salvar**. Use **Todos** para atender toda a audiência elegível. Use `ALLOWLISTED_ONLY` pela API para restringir o atendimento aos números autorizados. O follow-up aceita `0`, `300`, `900`, `1800`, `3600`, `7200`, `28800` ou `86400` segundos.
Depois de revisar o comportamento, clique em **Publicar** na tela principal. A publicação aplica a configuração ao provedor. ### Sobre o conhecimento do agente O agente combina as fontes configuradas para responder clientes. Mantenha o conteúdo atual, objetivo e consistente. * **Business information**: pagamentos, entrega, política comercial e contatos. * **FAQs**: perguntas com respostas diretas e reutilizáveis. * **Websites e files**: fontes adicionais processadas pela Meta. #### Informações comerciais ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/business_info ``` ```json { "payment_method": "Pix, cartão e boleto.", "return_policy": "Trocas e devoluções em até 7 dias.", "purchase_info": "O agente qualifica o cliente e orienta a conclusão da compra.", "delivery_and_shipping": "Prazo e condições dependem do produto e da região.", "business_description": "Agente de vendas para atendimento comercial.", "contact_info": { "email": "contato@exemplo.com", "hours_of_operation": "Segunda a sexta, das 9h às 18h", "address": "Atendimento online" } } ``` A Meta retorna, por exemplo: ```json { "business_description": "Agente de vendas para atendimento comercial.", "status": "SYNCED" } ``` #### FAQ ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/faq ``` ```json { "question": "Quais formas de pagamento estão disponíveis?", "answer": "Aceitamos Pix, cartão de crédito e boleto.", "metadata": { "origem": "integracao" } } ``` A criação retorna um identificador da Meta. Use-o para consultar, atualizar ou excluir a FAQ. #### Website e arquivo ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/websites ``` ```json { "url": "https://www.exemplo.com.br/ajuda" } ``` A resposta inicia o processamento: ```json { "website_id": "website-123456", "url": "https://www.exemplo.com.br/ajuda", "crawl_status": "PROCESSING" } ``` Para arquivos, envie `POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/files` em `multipart/form-data` com `file_name` e `file`. São aceitos PDF, DOC, DOCX, PNG, JPG e JPEG. CSV e XLSX dependem da habilitação do asset. O limite é de 100 MB. ### Habilidades do agente Skills orientam o agente em situações específicas. O campo `title` aceita letras minúsculas, números e hífens. O limite é de 64 caracteres. ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/skills ``` ```json { "title": "qualificar-lead", "description": "Aplicar quando houver interesse comercial.", "skill": "Pergunte objetivo, prazo, orçamento e volume." } ``` #### GET Skills ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/skills ``` Exemplo da resposta completa retornada pela Meta: ```json [ { "id": "pfbid04mnahZEHBLercnBfMbixRVezRzQDwMyZETHMES3fuAQ8rhvdDSbpDBz3Vjkt6DJWyQchHPaFYf8XaaBoJY9P6BfAHB5DjMS17Xl", "skill": "Ouça a objeção, reconheça a preocupação e responda com informações verificáveis. Nunca pressione, disfarce custos ou prometa condição especial sem confirmação.", "channel": "whatsapp", "title": "tratar-objecoes", "description": "Responder objecoes comerciais sem pressionar o cliente." }, { "id": "pfbid0Mt5gV5QAHycjULUCJtnxpBQk4fEeE9dREYkCkCGm2YWJuNFUMKkeqfJ7trwzUhuYEw1SNcUhYRAA2cEMWNygQTWWp5uN6ftVwzl", "skill": "Ao finalizar ou transferir o atendimento, resuma necessidade, produto de interesse, quantidade, prazo, orçamento, dúvidas e próximos passos, sem incluir dados sensíveis.", "channel": "whatsapp", "title": "resumir-atendimento", "description": "Resumir a conversa para o cliente ou para o consultor humano." }, { "id": "pfbid04bHkAEG2xqMVCU6PvU8GqW49if2mSNSjCVWRjS9Q84MZdMe4Kho7zN1MkETp1fCaspWMwUU88BTumdTspgkokTK2Ejbqw65rSfYl", "skill": "Use o contexto disponível para retomar o atendimento, reconheça o ponto em que a conversa parou e faça apenas as perguntas que ainda faltarem para orientar o cliente.", "channel": "whatsapp", "title": "retomar-atendimento", "description": "Retomar uma conversa comercial sem repetir perguntas desnecessárias." }, { "id": "pfbid03fi8Zr3Hsy8VBexgR5sBjsJBuvhkfVhR7R1PZDh8pqScZRMGzzw5Sxy7Pi2fWgJQLUYFML2D27fvsoqDoduzD35iW2hZWKfQxpVl", "skill": "Pergunte a região e o produto quando necessário. Informe prazo e condições de entrega apenas quando confirmados. Se depender de cálculo ou consulta, encaminhe para um consultor.", "channel": "whatsapp", "title": "orientar-entrega", "description": "Explicar entrega, prazo e cobertura conforme a base." }, { "id": "pfbid03cFPCeHDkQicDstHAsVQbjaX9wmrC5ruGfYRbWtPBoFYi9NMXNBnGgED7Lxt7FzVLu1B8cRpRQbeUTfaqHXw23SD1KycmhfTEWal", "skill": "Apresente as formas de pagamento cadastradas para o negócio. Não solicite dados completos de cartão, senhas ou códigos de segurança no chat e encaminhe procedimentos sensíveis para o canal seguro.", "channel": "whatsapp", "title": "orientar-pagamento", "description": "Orientar o cliente sobre as formas de pagamento disponíveis." }, { "id": "pfbid03DJEzzedrrKnLxLBSbHVUmZm2p9C6yaKUCFixNy7MFBH2uDYQHbvcMZSaytDUPBGa6EMTQP3UVicKVhcvfFRsYBXpiqV4G9eBdTl", "skill": "Antes de encaminhar o pedido, confirme produto ou serviço, quantidade, dados relevantes, prazo desejado e forma de pagamento. Resuma tudo e peça confirmação do cliente.", "channel": "whatsapp", "title": "confirmar-pedido", "description": "Confirmar os dados antes de encaminhar uma compra." }, { "id": "pfbid065dBmzuDbEYMcRy7ZmrmfAJJbF1A3cpoVTpw497PYLPSG6YCXuFppeGkA9TGsG88My3Ev1LtKMevV9EPyjmxgYeN1yD5n4wBetl", "skill": "Informe preço somente quando houver valor confirmado na base de conhecimento. Se o preço depender de configuração, volume ou negociação, explique isso e encaminhe para um consultor.", "channel": "whatsapp", "title": "responder-precos", "description": "Tratar dúvidas sobre preços com segurança." }, { "id": "pfbid04Ctc6ydgy4TGCxFRh6nTvm2qKCvQBRCqd9uhjDJJ18Pxp1xjnyeZxmMECKW2UFb2rfrmAzM54p2rVyLsBqmfXk29pfVe9ma3amJl", "skill": "Quando o cliente pedir comparação, organize as opções por características, benefícios e condições conhecidas. Informe o que não estiver disponível e ajude o cliente a escolher conforme sua necessidade.", "channel": "whatsapp", "title": "comparar-opcoes", "description": "Comparar alternativas comerciais de forma imparcial." }, { "id": "pfbid03EKQ8vYrHVduiwD6eagzNfnM4P5hYDTsnPW6PHsHm5a7HC7zC1kL5KQiDEBXx9izVaM1MFhpnLAE2TBkYz8pDe5hACWRR9SUphil", "skill": "Explique os benefícios do produto ou serviço com linguagem simples e consultiva. Não invente características, resultados, garantias ou condições que não estejam na base de conhecimento.", "channel": "whatsapp", "title": "explicar-beneficios", "description": "Explicar benefícios sem prometer resultados não documentados." }, { "id": "pfbid03xzKQ2qRGsu7GiSpTyiXRm1HvwaBoRd7FJ67s256yogFvCX9QC85M2BmDWnxWz8PKAe6UQtrZES8j6grCzVSg73P9hyukKKtMyGl", "skill": "Pergunte o que o cliente procura e apresente somente produtos ou serviços confirmados na base de conhecimento, destacando informações objetivas e relevantes.", "channel": "whatsapp", "title": "apresentar-catalogo", "description": "Apresentar as opções comerciais disponíveis conforme o interesse do cliente." }, { "id": "pfbid04HdFaUL9TuLbmvkhGn5CYJP1XUuuAan5tv6DbVgBSx1egn4iMuNzRRELFoTTq5L5wbEh6r7bLetrPvin1DzbkYKQZMDkUfg6Mzzl", "skill": "Encaminhe para um consultor quando o cliente pedir um humano, houver reclamação, dúvida fora da base de conhecimento ou necessidade de negociação personalizada. Informe o cliente com transparência.", "channel": "whatsapp", "title": "encaminhar-humano", "description": "Encaminhar a conversa para uma pessoa quando necessário." }, { "id": "pfbid0QJhhv1b7cLJEauxa99i45y2eG22HSRe89gcMXneWvrCmCxenjeWX5DNfcoSBZXy5yQmF6mfmo9GRiE4Ahwbb3Je3JEz5hpGkpAl", "skill": "Entenda a necessidade do cliente, apresente somente opções e informações disponíveis na base de conhecimento, explique benefícios de forma objetiva e nunca invente preço, prazo ou disponibilidade.", "channel": "whatsapp", "title": "recomendar-produto", "description": "Orientar o cliente na escolha da melhor opção comercial." }, { "id": "pfbid0U6TVTVV7Lj1d434YsFJfAw1aoDtEKf1fp8KPojSvLPNbZQuwXG8LXSVPAJ1vFQtD1aU6k6bfQBu2CqZzZAfLQvi1QMnxdTjuuFl", "skill": "Pergunte o objetivo do cliente, produto ou serviço de interesse, prazo, orçamento e volume. Resuma as informações e confirme antes de encaminhar para um consultor.", "channel": "whatsapp", "title": "qualificar-lead", "description": "Qualificar o interesse comercial do cliente antes do encaminhamento." } ] ``` ### Connectors e tools Connectors conectam o agente a APIs externas. Tools descrevem as operações disponíveis em cada connector. ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors ``` ```json { "name": "Order Management API", "description": "Consulta pedidos e devoluções.", "base_url": "https://api.exemplo.com", "auth_type": "API_KEY", "auth_config": { "api_key": { "headers": [{ "field_name": "X-API-Key", "value": "SUA_CHAVE", "prefix": "" }], "query_params": [], "body_params": [] } }, "requires_certificate": false } ``` `auth_type` aceita `API_KEY`, `OAUTH2_CLIENT_CREDENTIALS` ou `NONE`. Nunca registre tokens, chaves, segredos OAuth ou certificados na collection compartilhada. Defina uma tool com `POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/tools`. Para testar uma tool manualmente, envie `input` como uma string JSON serializada. ```json { "input": "{\"order_id\":\"12345\"}" } ``` ### Operação e teste #### Teste simulado validado ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_test ``` ```json { "user_msg": "Olá! Quero conhecer as opções disponíveis e entender qual seria a melhor para minha empresa.", "conversation_id": "docs20260818-v2" } ``` A Meta retornou: ```json { "message_id": "pfbid02YzyMWBt7guypevDEhS1BSdM24t69PZ7AQ8HAE937LroQ22n54p4poXv5FF6fdDA8l_1787068974201", "agent_response": "Olá! Com certeza, será um prazer ajudar você a encontrar a melhor opção para sua empresa.\n\nPara orientar uma recomendação, conte seu objetivo, produto ou serviço de interesse, quantidade, prazo e faixa de orçamento.", "conversation_id": "pfbid02YzyMWBt7guypevDEhS1BSdM24t69PZ7AQ8HAE937LroQ22n54p4poXv5FF6fdDA8l", "timestamp": 1787068974, "handoff_reason": null, "no_response_reason": null, "quick_replies": [], "product_variant_ids": [] } ``` Reutilize `conversation_id` em mensagens posteriores do mesmo teste. #### Controle de conversa ```http POST https://sync-core-api.otima.io/whatsapp/provider/business/whatsapp/phone_numbers/{entity_id}/thread_control ``` ```json { "messaging_product": "whatsapp", "action": "release", "to": "+5511988888888" } ``` Use `release` ou `take`, conforme a autorização da operação. Esta rota usa a versão `1.0.0`. #### Eventos de negócio Envie atualizações relevantes com `POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_event`. O campo `event.payload` é uma string JSON e aceita até 4.096 caracteres. ```json { "to": "+5511988888888", "event": { "type": "payment_received", "description": "Pagamento confirmado", "payload": "{\"order_id\":\"12345\"}" } } ``` Consulte o processamento em `GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_event/{event_id}`. Os status incluem `request_received`, `processing`, `sent`, `failed`, `skipped` e `success`. ### Referência de rotas Esta API expõe **54 rotas** para o Meta Business Agent oficial Meta. Expanda um grupo para copiar uma URL completa. Cada rota apresenta método, finalidade e payload ou resposta disponível.
Integração e habilitação — 7 rotas Rotas oficiais da Meta: [onboarding do agente](https://developers.facebook.com/documentation/meta-business-agent/reference/onboard/agent-onboarding). #### Verificar elegibilidade ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_eligibility ``` Confirma se o número pode usar o agente. **Resposta** ```json { "is_eligible": true } ``` #### Iniciar onboarding ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_onboarding?channel=whatsapp ``` Inicia o onboarding do canal WhatsApp. **Payload** ```json {} ``` **Resposta** ```json { "agent_id": "agent-123456" } ``` #### Consultar configurações ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/settings ``` Retorna rollout, audiência, handoff e follow-up configurados. #### Atualizar configurações ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/settings ``` Atualiza rollout, audiência, handoff e follow-up. **Payload** ```json { "rollout": { "enabled": true }, "ai_audience": "EVERYONE", "handoff": { "enabled": true } } ``` #### Listar allowlist ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/allowlist ``` Lista os números autorizados. #### Adicionar à allowlist ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/allowlist ``` Autoriza um número a falar com o agente. **Payload** ```json { "phone_number": "+5511988888888" } ``` #### Remover da allowlist ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/allowlist/{entry_id} ``` Remove um número autorizado. A resposta não possui corpo.
Conhecimento — 17 rotas Rotas oficiais da Meta: [configuração do agente](https://developers.facebook.com/documentation/meta-business-agent/reference/configure/agent-skills). #### Consultar informações comerciais ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/business_info ``` Retorna as informações comerciais do agente. #### Atualizar informações comerciais ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/business_info ``` Atualiza as informações comerciais. **Payload** ```json { "payment_method": "Pix e cartão.", "business_description": "Atendimento comercial." } ``` #### Remover informações comerciais ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/business_info ``` Remove as informações comerciais. A resposta não possui corpo. #### Listar FAQs ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/faq ``` Lista as perguntas frequentes cadastradas. #### Criar FAQ ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/faq ``` Cria uma pergunta frequente. **Payload** ```json { "question": "Quais pagamentos aceitam?", "answer": "Pix e cartão.", "metadata": {} } ``` #### Consultar FAQ ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/faq/{faq_id} ``` Retorna uma FAQ pelo identificador. #### Atualizar FAQ ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/faq/{faq_id} ``` Atualiza uma pergunta frequente. **Payload** ```json { "question": "Quais pagamentos aceitam?", "answer": "Pix e cartão.", "metadata": {} } ``` #### Excluir FAQ ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/faq/{faq_id} ``` Exclui uma pergunta frequente. A resposta não possui corpo. #### Listar websites ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/websites ``` Lista os websites usados como fontes. #### Adicionar website ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/websites ``` Adiciona um website como fonte de conhecimento. **Payload** ```json { "url": "https://www.exemplo.com.br/ajuda" } ``` **Resposta** ```json { "website_id": "website-123456", "crawl_status": "PROCESSING" } ``` #### Consultar website ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/websites/{website_id} ``` Retorna um website e seu status de processamento. #### Atualizar website ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/websites/{website_id} ``` Atualiza a URL de um website. **Payload** ```json { "url": "https://www.exemplo.com.br/ajuda" } ``` #### Excluir website ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/websites/{website_id} ``` Exclui um website. A resposta não possui corpo. #### Listar arquivos ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/files ``` Lista os arquivos usados como fontes. #### Enviar arquivo ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/files ``` Envia uma fonte de conhecimento. Use `multipart/form-data` com `file_name` e `file`. #### Consultar arquivo ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/files/{file_id} ``` Retorna um arquivo pelo identificador. #### Excluir arquivo ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/files/{file_id} ``` Exclui um arquivo. A resposta não possui corpo.
Skills e connectors — 20 rotas Rotas oficiais da Meta: [skills do agente](https://developers.facebook.com/documentation/meta-business-agent/reference/configure/agent-skills). #### Listar skills ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/skills ``` Lista as instruções específicas do agente. #### Criar skill ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/skills ``` Cria uma instrução específica. **Payload** ```json { "title": "qualificar-lead", "description": "Qualifica o interesse.", "skill": "Pergunte objetivo e prazo." } ``` #### Consultar skill ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/skills/{skill_id} ``` Retorna uma skill pelo identificador. #### Atualizar skill ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/skills/{skill_id} ``` Atualiza uma skill. **Payload** ```json { "title": "qualificar-lead", "description": "Qualifica o interesse.", "skill": "Pergunte objetivo e prazo." } ``` #### Excluir skill ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_config/skills/{skill_id} ``` Exclui uma skill. A resposta não possui corpo. #### Listar connectors ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors ``` Lista as integrações externas do agente. #### Criar connector ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors ``` Cria uma integração externa. **Payload** ```json { "name": "Order API", "description": "Consulta pedidos.", "base_url": "https://api.exemplo.com", "auth_type": "NONE" } ``` #### Consultar connector ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id} ``` Retorna um connector pelo identificador. #### Atualizar connector ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id} ``` Atualiza uma integração externa. **Payload** ```json { "name": "Order API", "description": "Consulta pedidos.", "base_url": "https://api.exemplo.com", "auth_type": "NONE" } ``` #### Excluir connector ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id} ``` Exclui uma integração externa. A resposta não possui corpo. #### Consultar logs do connector ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/logs?include_stats=true&limit=100 ``` Retorna logs e estatísticas da integração. #### Salvar chave de API ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/upsertApiKey ``` Cria ou atualiza a autenticação por chave de API. #### Salvar OAuth ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/upsertOAuth ``` Cria ou atualiza a autenticação OAuth. #### Salvar certificado ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/upsertCertificate ``` Cria ou atualiza o certificado do connector. #### Listar tools ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/tools ``` Lista as operações disponíveis em um connector. #### Criar tool ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/tools ``` Cria uma operação para o connector. #### Consultar tool ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/tools/{tool_id} ``` Retorna uma tool pelo identificador. #### Atualizar tool ```http PUT https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/tools/{tool_id} ``` Atualiza uma operação do connector. #### Excluir tool ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/tools/{tool_id} ``` Exclui uma tool. A resposta não possui corpo. #### Executar tool ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_connectors/{connector_id}/tools/{tool_id}/run ``` Executa uma tool manualmente. **Payload** ```json { "input": "{\"order_id\":\"12345\"}" } ```
Operação, avaliação e insights — 10 rotas Rotas oficiais da Meta: [controle de conversas](https://developers.facebook.com/documentation/meta-business-agent/reference/operate/thread-control-cloud-api) e [avaliação do agente](https://developers.facebook.com/documentation/meta-business-agent/reference/operate/agent-eval). #### Controle de conversa ```http POST https://sync-core-api.otima.io/whatsapp/provider/business/whatsapp/phone_numbers/{entity_id}/thread_control ``` Libera ou assume uma conversa. Use `X-API-Version: 1.0.0`. **Payload** ```json { "messaging_product": "whatsapp", "action": "release", "to": "+5511988888888" } ``` #### Enviar evento de negócio ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_event ``` Envia um evento comercial ao agente. **Payload** ```json { "to": "+5511988888888", "event": { "type": "payment_received", "payload": "{\"order_id\":\"12345\"}" } } ``` #### Consultar evento de negócio ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_event/{event_id} ``` Retorna o processamento do evento. Os status incluem `request_received`, `processing`, `sent`, `failed`, `skipped` e `success`. #### Testar o agente ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent_test ``` Simula uma mensagem sem enviá-la no WhatsApp. **Payload** ```json { "user_msg": "Quero conhecer as opções.", "conversation_id": "teste-001" } ``` **Resposta** ```json { "agent_response": "Olá! Como posso ajudar?", "conversation_id": "teste-001" } ``` #### Listar casos de avaliação ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent-eval/cases ``` Lista os casos disponíveis para avaliação. #### Iniciar avaliação ```http POST https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent-eval/run?eval_case_ids={eval_case_id} ``` Inicia a avaliação de um ou mais casos. #### Consultar execução de avaliação ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent-eval/run?job_id={job_id} ``` Retorna o estado de uma execução de avaliação. #### Consultar detalhes da avaliação ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent-eval/details?eval_ids={eval_id} ``` Retorna os detalhes de uma avaliação. #### Consultar resumo da avaliação ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent-eval/summary?summary_ids={summary_id} ``` Retorna o resumo de uma avaliação. #### Insights ```http GET https://sync-core-api.otima.io/whatsapp/provider/{entity_id}/agent-insights ``` Retorna insights operacionais do agente.
### Collection do Postman A collection organiza 54 requisições por fluxo: habilitação, conhecimento, skills, connectors, operação, avaliação e insights. Ao importar a collection, preencha somente estas variáveis: * `token` — seu token de acesso. * `workspaceUuid` — UUID do workspace. * `numberIdentifier` — telefone ou `wa_id` do número. {% file src="/files/r2M4SGeEQbinQHEwnB3D" %} Mantenha `token` vazio em exportações compartilhadas. Use também valores de exemplo para `externalApiKey`, `oauthClientId` e `oauthClientSecret`. {% hint style="warning" %} Nunca compartilhe collections com tokens, chaves de API, segredos OAuth ou certificados. Revogue qualquer credencial exposta. {% endhint %} ### Respostas e erros | Código | Significado | | ------ | -------------------------------------------- | | `200` | Consulta ou operação concluída. | | `201` | Recurso criado ou onboarding iniciado. | | `204` | Recurso excluído, sem corpo de resposta. | | `400` | Payload, query ou parâmetro inválido. | | `401` | Token inválido, expirado ou sem autorização. | | `403` | Operação não permitida. | | `404` | Número ou recurso não encontrado. | | `409` | Conflito com recurso existente. | | `429` | Limite de requisições atingido. | | `500` | Erro inesperado no provedor. | O provedor pode retornar o seguinte erro de validação: ```json { "title": "JSON Schema Validation Error", "detail": "Descrição do erro retornada pela Meta.", "status": 400 } ``` Trate o código HTTP e os campos `title`, `detail` e `status` quando estiverem presentes. ### Referências oficiais * [Introdução ao Meta Business Agent](https://developers.facebook.com/documentation/meta-business-agent/get-started) * [Onboarding do agente](https://developers.facebook.com/documentation/meta-business-agent/reference/onboard/agent-onboarding) * [Skills do agente](https://developers.facebook.com/documentation/meta-business-agent/reference/configure/agent-skills) * [Operação de conversas](https://developers.facebook.com/documentation/meta-business-agent/reference/operate/thread-control-cloud-api) * [Avaliação do agente](https://developers.facebook.com/documentation/meta-business-agent/reference/operate/agent-eval)