Quick Start - Notifique

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.

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.

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
Nos exemplos, troque sk_live_xxxxx pela sua chave e https://api.notifique.dev pela sua URL base, se for o caso

Começando agora? Use sk_test_... e confira o resultado na Caixa sandbox.

Conexão oficial
Conexão não oficial

1. Conectar o número

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

1A, Pelo painel

WhatsApp → Nova instância → Oficial
Faça login com sua conta Meta e vincule o número
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.

POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Suporte oficial",
  "mode": "OFFICIAL",
  "generateShareableLink": true
}

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

{
  "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.

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.

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:

POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Suporte oficial",
  "mode": "OFFICIAL",
  "metaEmbeddedCode": "CODE_DO_EMBEDDED_SIGNUP",
  "metaPhoneNumberId": "123456789012345",
  "metaWabaId": "987654321098765"
}

Resposta esperada: 200 com a instância ativa:

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

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.

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.

Abra o gerenciador do WhatsApp
Vá em Configurações de pagamento
Adicione um cartão válido
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.

4. Enviar o primeiro template

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

POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "instanceId": "ID_DA_INSTANCIA",
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "ID_DO_TEMPLATE",
    "variables": { "1": "Maria" }
  }
}

Resposta esperada: 202 com a mensagem na fila:

{
  "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:

POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

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

Resposta esperada: 202:

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

Fora dessa janela, volte a usar template.

Use a não oficial para testes e MVP. Em produção com clientes reais, prefira a oficial.

1. Criar instância e parear

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

1A, Pelo painel

WhatsApp → Nova instância (o padrão é não oficial)
Abra o código no celular que aparece no painel
Escaneie no app WhatsApp do número que vai enviar as mensagens
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:

POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Minha instância de teste"
}

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

{
  "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:

POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Minha instância de teste",
  "generateShareableLink": true
}

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

{
  "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.

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.

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.

Chip ou número novo? Leia Números e chips novos antes do primeiro envio em produção.

2. Renovar o código (se expirar)

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

GET /v1/whatsapp/instances/:instanceId/qr
Authorization: Bearer sk_live_xxxxx

Resposta esperada: 200 com um código novo:

{
  "success": true,
  "data": {
    "status": "PENDING",
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs..."
  }
}

Você também pode receber um novo código por webhook (instance.qrcode).

3. Enviar mensagem de texto

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

POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

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

Resposta esperada: 202 com a mensagem na fila:

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

Depois do primeiro envio

Acompanhe entrega e leitura por webhooks
Vários números? Veja Sending Pools
Campos e rotas completas: referência da API na aba WhatsApp

Próximos passos

Introdução: visão geral do canal
Modos de conexão: comparativo completo
Templates oficiais Meta
Política anti-banimento

​Em poucas palavras

​Antes de começar

​1. Conectar o número

​1A, Pelo painel

​1B, Pela API com link para o cliente

​1C, Pela API com credenciais Meta

​2. Cadastrar cartão no gerenciador do WhatsApp

​3. Sincronizar templates

​4. Enviar o primeiro template

​5. Conversar depois da resposta

​1. Criar instância e parear

​1A, Pelo painel

​1B, Pela API com QR na sua interface

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

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

​3. Enviar mensagem de texto

​Depois do primeiro envio

​Próximos passos

Em poucas palavras

Antes de começar

1. Conectar o número

1A, Pelo painel

1B, Pela API com link para o cliente

1C, Pela API com credenciais Meta

2. Cadastrar cartão no gerenciador do WhatsApp

3. Sincronizar templates

4. Enviar o primeiro template

5. Conversar depois da resposta

1. Criar instância e parear

1A, Pelo painel

1B, Pela API com QR na sua interface

1C, Pela API com link para o cliente escanear

2. Renovar o código (se expirar)

3. Enviar mensagem de texto

Depois do primeiro envio

Próximos passos