> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Do zero ao primeiro envio no WhatsApp: escolha conexão oficial ou não oficial e siga o passo a passo.

<Tip>
  Este guia leva você da **conta ao primeiro envio**. Escolha o modo abaixo: **oficial** para produção ou **não oficial** para testar rápido.
</Tip>

## Em poucas palavras

* **Oficial:** login Meta no painel, cartão no gerenciador do WhatsApp, primeiro envio com **template aprovado**
* **Não oficial:** crie a instância, **escaneie o código no celular** e envie **texto livre**
* Nos dois casos você usa a **mesma API**; só muda como conecta o número

Dúvida sobre qual escolher? Veja [Modos de conexão](/whatsapp-api/como-funciona/modos-de-conexao).

## Antes de começar

* Uma **chave de API** (`sk_live_...` ou `sk_test_...` para sandbox)
* Permissões de instância e envio na chave. Veja [Escopos](/whatsapp-api/como-funciona/escopos-api-key)
* Nos exemplos, troque `sk_live_xxxxx` pela sua chave e `https://api.notifique.dev` pela sua URL base, se for o caso

<Note>
  Começando agora? Use `sk_test_...` e confira o resultado na [Caixa sandbox](/guides/sandbox/index).
</Note>

***

<Tabs>
  <Tab title="Conexão oficial">
    ### 1. Conectar o número

    Três caminhos, escolha o que combina com sua integração:

    #### 1A, Pelo painel

    1. WhatsApp → Nova instância → **Oficial**
    2. Faça login com sua conta Meta e vincule o número
    3. Quando o status ficar **ativo**, anote o **id da instância**

    #### 1B, Pela API com link para o cliente

    Para **onboarding remoto** (sem browser no seu servidor): crie um rascunho e envie o link, o cliente conclui o login Meta na página.

    ```http theme={null}
    POST /v1/whatsapp/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Suporte oficial",
      "mode": "OFFICIAL",
      "generateShareableLink": true
    }
    ```

    Resposta esperada: **200** com instância **PENDING** e o link:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "Suporte oficial",
          "status": "PENDING",
          "phoneNumber": null
        },
        "connection": {
          "provider": "META_CLOUD",
          "status": "pending_signup"
        },
        "shareableLink": {
          "hostedUrl": "https://api.notifique.dev/w/instance-connect/...?token=...",
          "embedUrl": "https://api.notifique.dev/w/embed/instance-connect/...?token=...",
          "publicId": "..."
        }
      }
    }
    ```

    Envie `shareableLink.hostedUrl` para o cliente. Quando ele terminar, a instância passa para **ativa**.

    <Warning>
      Quem tiver o link pode conectar ou desconectar a instância. Depois do uso, rotacione o secret com `POST /v1/whatsapp/instances/:instanceId/connect-page/rotate-secret`.
    </Warning>

    #### 1C, Pela API com credenciais Meta

    Com o **Embedded Signup** já concluído no navegador, crie a instância oficial já **ativa** enviando os três campos da Meta:

    ```http theme={null}
    POST /v1/whatsapp/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Suporte oficial",
      "mode": "OFFICIAL",
      "metaEmbeddedCode": "CODE_DO_EMBEDDED_SIGNUP",
      "metaPhoneNumberId": "123456789012345",
      "metaWabaId": "987654321098765"
    }
    ```

    Resposta esperada: **200** com a instância **ativa**:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "Suporte oficial",
          "status": "ACTIVE",
          "phoneNumber": "5511999999999",
          "createdAt": "2025-02-20T12:00:00.000Z"
        }
      }
    }
    ```

    <Info>
      Resumo: **painel** para o caminho mais simples; **`generateShareableLink: true`** quando outra pessoa precisa fazer o login Meta; **`metaEmbeddedCode` + `metaPhoneNumberId` + `metaWabaId`** quando você já tem os dados do Embedded Signup.
    </Info>

    ### 2. Cadastrar cartão no gerenciador do WhatsApp

    A Meta cobra as **conversas** na sua conta. Sem cartão cadastrado, o envio em produção não funciona.

    1. Abra o [gerenciador do WhatsApp](https://business.facebook.com/wa/manage/)
    2. Vá em **Configurações de pagamento**
    3. Adicione um cartão válido
    4. No painel Notifique, confirme que o pagamento está ativo

    ### 3. Sincronizar templates

    No painel, use **Sincronizar templates com a Meta** (ou crie um template novo). Você vai precisar de um **aprovado** para o primeiro contato.

    Detalhes: [Templates oficiais Meta](/whatsapp-api/como-funciona/templates-oficiais-meta).

    ### 4. Enviar o primeiro template

    Fora de uma conversa recente, a oficial exige **template aprovado**:

    ```http theme={null}
    POST /v1/whatsapp/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "ID_DA_INSTANCIA",
      "to": ["5511999999999"],
      "type": "template",
      "payload": {
        "templateId": "ID_DO_TEMPLATE",
        "variables": { "1": "Maria" }
      }
    }
    ```

    Resposta esperada: **202** com a mensagem na fila:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "messageIds": ["clxx789..."],
        "status": "QUEUED",
        "scheduledAt": null
      }
    }
    ```

    ### 5. Conversar depois da resposta

    Quando o cliente **responder**, você tem cerca de **24 horas** para enviar texto ou mídia livre:

    ```http theme={null}
    POST /v1/whatsapp/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "ID_DA_INSTANCIA",
      "to": ["5511999999999"],
      "type": "text",
      "payload": {
        "message": "Olá! Recebemos sua mensagem. Em que posso ajudar?"
      }
    }
    ```

    Resposta esperada: **202**:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "messageIds": ["clxx790..."],
        "status": "QUEUED",
        "scheduledAt": null
      }
    }
    ```

    Fora dessa janela, volte a usar **template**.
  </Tab>

  <Tab title="Conexão não oficial">
    <Warning>
      Use a não oficial para **testes e MVP**. Em produção com clientes reais, prefira a **oficial**.
    </Warning>

    ### 1. Criar instância e parear

    Três caminhos, escolha o que combina com sua integração:

    #### 1A, Pelo painel

    1. WhatsApp → Nova instância (o padrão é **não oficial**)
    2. Abra o **código no celular** que aparece no painel
    3. Escaneie no app WhatsApp do número que vai enviar as mensagens
    4. Quando o status ficar **ativo**, anote o **id da instância**

    #### 1B, Pela API com QR na sua interface

    Cria a conexão e devolve o código para você exibir na sua UI:

    ```http theme={null}
    POST /v1/whatsapp/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Minha instância de teste"
    }
    ```

    Resposta esperada: **200** com o código em `connection.base64`:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "Minha instância de teste",
          "status": "PENDING",
          "phoneNumber": null,
          "createdAt": "2025-02-20T12:00:00.000Z"
        },
        "connection": {
          "pairingCode": null,
          "code": "2@KbXFfHsvo+byvkP6k4VoBIE5gZFwYHT9y6dNt/c6Sfg6M+...",
          "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs...",
          "count": 1
        }
      }
    }
    ```

    Use `connection.base64` para mostrar o **código** (imagem) e escaneie no WhatsApp do número que vai enviar.

    #### 1C, Pela API com link para o cliente escanear

    Passe `generateShareableLink: true` para receber também um link, útil quando quem vai escanear não está na sua tela:

    ```http theme={null}
    POST /v1/whatsapp/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Minha instância de teste",
      "generateShareableLink": true
    }
    ```

    Resposta esperada: **200** com QR **e** link compartilhável:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "Minha instância de teste",
          "status": "PENDING",
          "phoneNumber": null,
          "createdAt": "2025-02-20T12:00:00.000Z"
        },
        "connection": {
          "pairingCode": null,
          "code": "2@KbXFfHsvo+byvkP6k4VoBIE5gZFwYHT9y6dNt/c6Sfg6M+...",
          "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs...",
          "count": 1
        },
        "shareableLink": {
          "hostedUrl": "https://api.notifique.dev/w/instance-connect/...?token=...",
          "embedUrl": "https://api.notifique.dev/w/embed/instance-connect/...?token=...",
          "publicId": "..."
        }
      }
    }
    ```

    Envie `shareableLink.hostedUrl` para o cliente abrir e escanear. Quando conectar, o status fica **ativo**.

    <Warning>
      Quem tiver o link pode conectar ou desconectar a instância. Depois do uso, rotacione o secret com `POST /v1/whatsapp/instances/:instanceId/connect-page/rotate-secret`.
    </Warning>

    <Info>
      Resumo: **painel** para o caminho mais simples; **API com QR** para embutir o código na sua UI; **`generateShareableLink: true`** quando outra pessoa precisa escanear.
    </Info>

    <Warning>
      **Chip ou número novo?** Leia [Números e chips novos](/whatsapp-api/como-funciona/politica-anti-banimento#números-e-chips-novos) antes do primeiro envio em produção.
    </Warning>

    ### 2. Renovar o código (se expirar)

    O código expira rápido. Peça outro **sem criar instância nova**:

    ```http theme={null}
    GET /v1/whatsapp/instances/:instanceId/qr
    Authorization: Bearer sk_live_xxxxx
    ```

    Resposta esperada: **200** com um código novo:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "status": "PENDING",
        "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs..."
      }
    }
    ```

    Você também pode receber um novo código por [webhook](/whatsapp-api/como-funciona/eventos-do-webhooks) (`instance.qrcode`).

    ### 3. Enviar mensagem de texto

    Com a instância **ativa**, envie para números em formato internacional (`5511999999999`):

    ```http theme={null}
    POST /v1/whatsapp/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "ID_DA_INSTANCIA",
      "to": ["5511999999999"],
      "type": "text",
      "payload": {
        "message": "Olá! Mensagem de teste."
      }
    }
    ```

    Resposta esperada: **202** com a mensagem na fila:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "messageIds": ["clxx789..."],
        "status": "QUEUED",
        "scheduledAt": null
      }
    }
    ```
  </Tab>
</Tabs>

***

## Depois do primeiro envio

* Acompanhe **entrega e leitura** por [webhooks](/whatsapp-api/como-funciona/eventos-do-webhooks)
* Vários números? Veja [Sending Pools](/whatsapp-api/como-funciona/sending-pools)
* Campos e rotas completas: **referência da API** na aba WhatsApp

## Próximos passos

* [Introdução](/whatsapp-api/como-funciona/introducao): visão geral do canal
* [Modos de conexão](/whatsapp-api/como-funciona/modos-de-conexao): comparativo completo
* [Templates oficiais Meta](/whatsapp-api/como-funciona/templates-oficiais-meta)
* [Política anti-banimento](/whatsapp-api/como-funciona/politica-anti-banimento)