OAuth / Embedded Signup
Onboarding de novos numeros WhatsApp Business via Embedded Signup e troca de tokens OAuth
OAuth / Embedded Signup
Endpoints para onboarding de novos numeros WhatsApp Business via Meta Embedded Signup. Permite que parceiros conectem seus numeros sem necessidade de configuracao manual no Meta Business Manager.
Autenticacao
Todas as requisicoes exigem o header:
Authorization: Bearer <API_KEY>GET /oauth/config
Retorna a configuracao necessaria para iniciar o fluxo de Embedded Signup no frontend.
Curl:
curl http://localhost:8200/oauth/config \
-H "Authorization: Bearer <API_KEY>"Resposta (200 OK):
{
"app_id": "META_APP_ID",
"config_id": "EMBEDDED_SIGNUP_CONFIG_ID",
"redirect_uri": "https://seu-dominio.com/oauth/callback",
"scope": "whatsapp_business_management,whatsapp_business_messaging"
}Use esses valores para inicializar o Facebook Login SDK no frontend com o fluxo de Embedded Signup.
POST /oauth/exchange
Troca o authorization code recebido no callback do Embedded Signup por um access token permanente.
Request Body:
{
"code": "AQB1c2VyX2lkPT..."
}| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
code | string | Sim | Authorization code recebido no callback do OAuth |
Curl:
curl -X POST http://localhost:8200/oauth/exchange \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"code": "AQB1c2VyX2lkPT..."
}'Resposta (200 OK):
{
"access_token": "EAABs...",
"token_type": "bearer",
"waba_id": "987654321",
"phone_number_id": "123456789",
"business_id": "111222333"
}Seguranca: O
access_tokenretornado e armazenado criptografado no banco. O connector cria automaticamente uma nova instancia com os dados retornados.
POST /oauth/register-phone
Registra um numero de telefone obtido via Embedded Signup na Meta Cloud API. Deve ser chamado apos o exchange para completar o setup do numero.
Request Body:
{
"instance_id": "uuid-da-instancia",
"pin": "123456"
}| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
instance_id | string | Sim | UUID da instancia criada no exchange |
pin | string | Sim | PIN de 6 digitos para two-step verification |
Curl:
curl -X POST http://localhost:8200/oauth/register-phone \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"instance_id": "uuid-da-instancia",
"pin": "123456"
}'Resposta (200 OK):
{
"success": true,
"phone_number_id": "123456789",
"display_phone_number": "+5511999998888"
}POST /oauth/override-webhook
Configura a URL do webhook para a aplicacao Meta. Necessario para que a Meta envie os eventos de mensagens para o connector.
Request Body:
{
"instance_id": "uuid-da-instancia",
"webhook_url": "https://seu-dominio.com/webhooks/whatsapp"
}| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
instance_id | string | Sim | UUID da instancia |
webhook_url | string | Sim | URL publica HTTPS para receber webhooks |
Curl:
curl -X POST http://localhost:8200/oauth/override-webhook \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"instance_id": "uuid-da-instancia",
"webhook_url": "https://seu-dominio.com/webhooks/whatsapp"
}'Resposta (200 OK):
{
"success": true,
"webhook_url": "https://seu-dominio.com/webhooks/whatsapp"
}Requisito: A URL deve ser HTTPS com certificado SSL valido. A Meta nao aceita HTTP ou certificados self-signed.
Fluxo Completo de Onboarding
- Frontend chama
GET /oauth/configpara obterapp_ideconfig_id - Frontend inicia o Facebook Login SDK com Embedded Signup
- Usuario autoriza e conecta seu numero no WhatsApp Business
- Frontend recebe o
codeno callback - Backend chama
POST /oauth/exchangecom ocode - Connector cria a instancia automaticamente
- Backend chama
POST /oauth/register-phonepara registrar o numero - Backend chama
POST /oauth/override-webhookpara configurar o webhook - Instancia pronta para enviar/receber mensagens
Usuario -> Facebook Login SDK -> Meta OAuth -> Callback (code)
|
POST /oauth/exchange
|
POST /oauth/register-phone
|
POST /oauth/override-webhook
|
Instancia ativa!