1. Objetivo
Este guia descreve o procedimento para conectar o canal WhatsApp Business Platform (Meta Cloud API) à Plataforma de Recrutamento com Agentes de IA do WallJobs.
Ao final, o número de WhatsApp corporativo da sua empresa estará conectado à plataforma, permitindo que candidatos e colaboradores conversem com os agentes de IA de recrutamento e seleção pelo WhatsApp da sua empresa.
O procedimento é executado majoritariamente pela sua equipe, por exigência da própria Meta: a conta comercial, o aplicativo e o número de telefone permanecem sob titularidade e controle da sua empresa. O WallJobs é a provedora da tecnologia que recebe e envia as mensagens.
Quem costuma executar: TI, marketing digital ou atendimento, porque são as áreas que normalmente têm perfil de administrador no Gerenciador de Negócios.
2. Como as mensagens trafegam
- 1. Candidato
- Envia mensagem ao número de WhatsApp da sua empresa.
- 2. Meta Cloud API
- Entrega o evento, assinado criptograficamente, ao webhook seguro do WallJobs.
- 3. Plataforma WallJobs
- Valida a autenticidade, processa a mensagem e aciona o motor de IA de RH.
- 4. Resposta
- Enviada ao candidato pela Graph API, com o token de acesso da sua empresa.
Nenhuma mensagem transita por servidores intermediários que não sejam os da Meta e os do WallJobs.
3. Pré-requisitos
- Conta no Gerenciador de Negócios da Meta (business.facebook.com), preferencialmente com a verificação de empresa concluída. A verificação amplia os limites de envio de mensagens e é fortemente recomendada.
- Usuário com perfil de administrador no Gerenciador de Negócios.
- Número de telefone dedicado ao canal, com capacidade de receber SMS ou ligação para validação.
- Conta de desenvolvedor da Meta (instruções na Etapa 1).
Atenção: o número escolhido não pode estar ativo em nenhum aplicativo WhatsApp ou WhatsApp Business convencional. Se estiver, é preciso excluir a conta do aplicativo antes de prosseguir.
4. Passo a passo
Etapa 1. Criação da conta de desenvolvedor
- Acesse developers.facebook.com e faça login com a conta Meta (Facebook) do responsável técnico.
- Clique em "Começar" (Get Started) e conclua o registro como desenvolvedor, aceitando os termos da plataforma.
- Use, de preferência, uma conta vinculada ao Gerenciador de Negócios da sua empresa.
Etapa 2. Criação do aplicativo
- No painel de desenvolvedor, acesse "Meus aplicativos" e clique em "Criar aplicativo".
- Quando for solicitado o caso de uso, selecione "Conectar-se a clientes pelo WhatsApp" (Connect with customers through WhatsApp). Em fluxos antigos, a opção equivalente é criar um aplicativo do tipo "Empresa" (Business) e adicionar o produto WhatsApp em seguida.
- Informe o nome do aplicativo (sugestão: o nome da sua empresa seguido de "RH WhatsApp"), o e-mail de contato e vincule o aplicativo ao portfólio empresarial (Business Manager) da sua empresa.
- Conclua a criação. Você será direcionado ao painel do aplicativo (App Dashboard).
Etapa 3. Adição do caso de uso WhatsApp
- No painel do aplicativo, confirme que o produto WhatsApp está habilitado. Se você criou o aplicativo pelo caso de uso da etapa anterior, ele já estará presente.
- Acesse o menu WhatsApp, opção "API Setup" (Configuração da API). Nesse painel a Meta disponibiliza um número de teste temporário, o identificador da conta do WhatsApp Business (WABA ID), o identificador do número (Phone Number ID) e um token de acesso temporário.
- Anote o WABA ID: ele será compartilhado com o WallJobs ao final.
Etapa 4. Cadastro e validação do número de telefone
- Ainda em WhatsApp, API Setup, clique em "Adicionar número de telefone" (Add phone number).
- Preencha o nome de exibição (display name) que aparecerá para os candidatos. Ele deve guardar relação clara com a sua marca e está sujeito à aprovação da Meta.
- Informe a categoria do negócio, a descrição e o número de telefone dedicado ao canal.
- Escolha o método de validação (SMS ou ligação), receba o código e informe-o no painel para concluir a verificação.
Etapa 5. Autenticação do número na Cloud API
- Ao selecionar o número recém-validado, o painel pede o cadastro do PIN de confirmação em duas etapas (two-step verification), um código de 6 dígitos definido pela sua empresa.
- Guarde esse PIN em local seguro: ele é exigido em qualquer migração ou novo registro do número.
- Com o PIN cadastrado, o número fica autenticado e ativo na Cloud API.
Se o registro for feito por via programática, a operação corresponde à chamada POST /{phone-number-id}/register da Graph API. A equipe do WallJobs pode acompanhar esse ponto, se necessário.
Etapa 6. Configuração do webhook
O webhook é o mecanismo pelo qual a Meta entrega ao WallJobs as mensagens recebidas.
- No painel do aplicativo, acesse WhatsApp, opção "Configuration" (Configuração).
- Na seção Webhook, clique em "Editar" e preencha os campos abaixo.
- URL de callback
- https://api-hr.walljobs.ai/api/webhooks/meta/whatsapp
- Token de verificação (verify token)
- Fornecido pela equipe do WallJobs, por canal seguro, antes desta etapa.
Clique em "Verificar e salvar". Nesse momento a Meta faz uma chamada de verificação (handshake) ao servidor do WallJobs. Se o token de verificação estiver correto, a configuração é aceita na hora.
Esta etapa precisa ser agendada junto com o WallJobs: o ambiente do nosso lado precisa estar configurado com o token de verificação e com a chave secreta do aplicativo da sua empresa (App Secret), usada na validação criptográfica de cada requisição.
Etapa 7. Assinatura do campo de mensagens
- Ainda em WhatsApp, Configuration, na seção "Webhook fields" (Campos do webhook), clique em "Gerenciar" (Manage).
- Localize o campo messages e clique em "Assinar" (Subscribe). Ele contempla tanto as mensagens recebidas dos candidatos quanto as atualizações de status das mensagens enviadas (entregue, lida, falha).
- Confirme que a assinatura ficou ativa para a conta do WhatsApp Business (objeto "WhatsApp Business Account") vinculada ao aplicativo.
As permissões de negócio associadas ao envio e à gestão do canal, whatsapp_business_messaging e whatsapp_business_management, são tratadas na etapa seguinte, na geração do token.
Etapa 8. Criação do token permanente
O token exibido no painel "API Setup" é temporário, expira em poucas horas e não deve ser usado em produção. Para o envio de mensagens pela plataforma é necessário um token permanente, gerado por um usuário do sistema.
- Acesse o Gerenciador de Negócios (business.facebook.com) e vá em Configurações do negócio, seção Usuários, opção "Usuários do sistema" (System users).
- Clique em "Adicionar" e crie um usuário do sistema com função Administrador (sugestão de nome: walljobs-integracao).
- Com o usuário criado, clique em "Adicionar ativos" (Add assets) e atribua a ele o aplicativo criado na Etapa 2 e a conta do WhatsApp (WABA), ambos com permissão de gerenciamento.
- Clique em "Gerar novo token" (Generate new token), selecione o aplicativo e defina a expiração como "Nunca" (Never expire).
- Marque as permissões whatsapp_business_messaging (envio e recebimento), whatsapp_business_management (gestão da conta e dos modelos de mensagem) e business_management (recomendada, para gestão dos ativos do negócio).
- Gere o token e copie-o imediatamente: por segurança, a Meta não o exibe de novo.
5. O que enviar ao WallJobs
Ao concluir as etapas acima, envie as informações abaixo à equipe técnica do WallJobs, exclusivamente por canal seguro: cofre de senhas compartilhado ou mecanismo equivalente combinado entre as partes.
- App ID
- Painel do aplicativo, Configurações básicas.
- App Secret
- Painel do aplicativo, Configurações básicas, "Chave Secreta do Aplicativo".
- WABA ID
- WhatsApp, API Setup.
- Phone Number ID
- WhatsApp, API Setup, ao selecionar o número.
- Número de telefone
- Em formato internacional, definido pela sua empresa.
- Token permanente
- Gerado na Etapa 8.
Tokens e chaves nunca devem ser enviados por e-mail ou WhatsApp em texto aberto. O WallJobs fornece previamente o token de verificação do webhook e confirma a ativação do canal.
6. Validação conjunta
- Verificação do webhook: confirmação de que o handshake da Meta foi aceito e de que os eventos estão chegando à plataforma.
- Teste de recebimento: mensagem enviada de um celular de teste ao número da sua empresa, com confirmação de processamento.
- Teste de envio: resposta gerada pela plataforma e entregue ao celular de teste, com confirmação dos status de entrega e leitura.
- Homologação do fluxo de RH: execução de um fluxo completo de triagem ou entrevista com candidato fictício.
7. Boas práticas e segurança
- Janela de 24 horas
- Por política da Meta, mensagens de formato livre só podem ser enviadas dentro de 24 horas após a última mensagem do usuário. Fora dessa janela é obrigatório usar modelos (templates) aprovados previamente pela Meta. O WallJobs orienta a criação dos modelos necessários aos fluxos de RH.
- Verificação de empresa
- Sem a verificação no Gerenciador de Negócios, o canal opera com limites reduzidos de conversas diárias. Recomendamos concluir a verificação o quanto antes.
- Segurança das credenciais
- O token permanente e o App Secret dão controle sobre o canal. Devem ser tratados como segredos corporativos, com rotação em caso de suspeita de exposição. O WallJobs armazena as credenciais de clientes com criptografia dedicada.
- Assinatura criptográfica
- Toda requisição recebida pelo WallJobs é validada por assinatura HMAC SHA-256 contra o App Secret do aplicativo da sua empresa. Requisições sem assinatura válida são rejeitadas.
- Número exclusivo
- O número conectado à Cloud API não pode ser usado ao mesmo tempo no aplicativo WhatsApp convencional.
8. Checklist
- 1. Criar conta em developers.facebook.com
- Sua empresa
- 2. Criar o aplicativo vinculado ao Business Manager
- Sua empresa
- 3. Habilitar o caso de uso WhatsApp
- Sua empresa
- 4. Cadastrar e validar o número de telefone
- Sua empresa
- 5. Autenticar o número com o PIN de duas etapas
- Sua empresa
- 6. Fornecer o token de verificação do webhook
- WallJobs
- 7. Configurar o webhook (URL e token)
- Sua empresa, junto com o WallJobs
- 8. Assinar o campo messages no webhook
- Sua empresa
- 9. Criar usuário do sistema e token permanente
- Sua empresa
- 10. Compartilhar credenciais por canal seguro
- Sua empresa
- 11. Validação conjunta e homologação
- Sua empresa e WallJobs
9. Referências oficiais da Meta
- Primeiros passos com a Cloud API: developers.facebook.com/documentation/business-messaging/whatsapp/get-started
- Configuração de webhooks: developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks
- Números de telefone comerciais: developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers
- Registro de número: developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration
- Visão geral da plataforma: developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform
Travou em alguma etapa? Fale com um especialista do WallJobs e a gente acompanha o procedimento com você.