> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.muchau.com.br/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.muchau.com.br/_mcp/server.

# Embedded Signup

> Deixe seus usuários conectar seus números de WhatsApp ao seu app via fluxo de Embedded Signup do Facebook.

## O que é o Embedded Signup?

O Embedded Signup é um fluxo nativo do Facebook que permite que seus usuários finais conectem seus números de WhatsApp Business diretamente da sua aplicação — sem nenhum conhecimento do Meta Business Manager. Ele abre um popup usando o SDK JavaScript do Facebook, guia o usuário pelo processo de autorização e retorna um código de autorização.

O Muchaw DEV cuida de todo o processo de provisionamento no backend. Seu usuário final nunca sabe que o Muchaw DEV existe.

## Visão geral do fluxo

```
Seu Frontend         Muchaw DEV              API Cloud da Meta
     │                     │                       │
     │  GET /init          │                       │
     │────────────────────▶│                       │
     │ { app_id, config_id }                       │
     │◀────────────────────│                       │
     │                     │                       │
     │  FB.login(app_id, config_id)                │
     │──────────────────────────────────────────▶  │
     │              (usuário completa o popup)      │
     │◀──────────────────────────────────────── code│
     │                     │                       │
     │  POST /complete     │                       │
     │  { code }           │                       │
     │────────────────────▶│                       │
     │                     │  Registrar, configurar│
     │                     │──────────────────────▶│
     │  { number_id, status: "PENDING" }           │
     │◀────────────────────│                       │
     │                     │                       │
     │  [webhook: number.activated disparado]      │
```

## Passos de integração

### 1. Buscar configuração do SDK

```javascript
const res = await fetch("https://dev.muchau.com.br/api/embedded-signup/init", {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { app_id, config_id } = await res.json();
```

### 2. Carregar o SDK do Facebook e acionar o login

```html
<script>
  window.fbAsyncInit = function() {
    FB.init({ appId: app_id, version: "v21.0" });
  };
</script>
<script async src="https://connect.facebook.net/en_US/sdk.js"></script>
```

```javascript
FB.login(
  (response) => {
    if (response.authResponse?.code) {
      completeSignup(response.authResponse.code);
    }
  },
  {
    config_id: config_id,
    response_type: "code",
    override_default_response_type: true,
  }
);
```

### 3. Completar o cadastro

```javascript
async function completeSignup(code) {
  const res = await fetch("https://dev.muchaw.com.br/api/embedded-signup/complete", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code }),
  });
  const { number_id, status } = await res.json();
  // Status é "PENDING" — aguarde o webhook number.activated
}
```

### 4. Aguardar a ativação

Configure um webhook para `number.activated` para saber quando o número estiver pronto:

```json
{
  "event": "number.activated",
  "data": {
    "id": "clxyz123...",
    "displayNumber": "+55 11 99999-0000",
    "status": "ACTIVE"
  }
}
```

## White-label

O fluxo completo de Embedded Signup usa internamente o App da Meta e o Business Portfolio do Muchaw DEV. Seu usuário final vê apenas a interface padrão do Facebook — não há menção ao Muchaw DEV. Você pode personalizar a experiência embutindo-a dentro da sua própria UI.

## Requisitos

* Seu frontend deve ser servido via **HTTPS** (obrigatório pelo Facebook)
* O domínio deve ser adicionado à lista de domínios permitidos do Muchaw DEV (entre em contato com o suporte)

## Pipeline de provisionamento (interno)

Após `POST /embedded-signup/complete`, o Muchaw DEV enfileira um job `number-provisioning` que:

1. Troca o `code` de curta duração por um token de acesso de longa duração via API Graph da Meta
2. Inscreve a WABA no App da Meta do Muchaw DEV (`/waba_id/subscribed_apps`)
3. Registra o número de telefone na API Cloud (`/phone_number_id/register`)
4. Define um PIN de 2FA (`/phone_number_id/enable_two_step`)
5. Busca detalhes do número (nome de exibição, avaliação de qualidade) da Meta
6. Atualiza o registro no banco de dados para `status: ACTIVE`
7. Enfileira uma entrega de webhook para `number.activated`

## Endpoints adicionais

| Endpoint                                   | Descrição                                                            |
| ------------------------------------------ | -------------------------------------------------------------------- |
| `POST /api/embedded-signup/exchange-token` | Trocar manualmente token de curta duração por token de longa duração |
| `POST /api/embedded-signup/register-phone` | Registrar manualmente um número de telefone na API Cloud             |

Estes são expostos para casos de uso avançados, mas normalmente não são necessários — `/complete` os executa automaticamente.