> ## 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.

# Criar instância WhatsApp

> Conecta um número de WhatsApp ao seu workspace. Pense nisso como **cadastrar o telefone** que vai enviar e receber mensagens pelo Notifique.

Escolha o exemplo que combina com o seu caso:

- **Não oficial, QR na sua tela** — você mostra o código na sua interface e escaneia no celular.
- **Não oficial, link para o cliente** — você envia um link; o cliente escaneia no WhatsApp dele.
- **Oficial, link para o cliente** — você envia um link; o cliente faz login na Meta e vincula o número.
- **Oficial, credenciais na hora** — você já concluiu o cadastro Meta no navegador e envia os dados nesta requisição.
- **Oficial, token Meta próprio (BYOK)** — você usa token e IDs da sua conta Meta diretamente.

Escopo: **whatsapp:instances:create**.



## OpenAPI

````yaml /whatsapp-api/api-reference/openapi-whatsapp.json post /v1/whatsapp/instances
openapi: 3.0.3
info:
  title: Notifique API — WhatsApp
  description: >-
    Envie mensagens WhatsApp e gerencie conexões. Autentique com `Authorization:
    Bearer sk_live_...` ou `x-api-key`.
  version: 1.0.0
servers:
  - url: https://api.notifique.dev
    description: Produção
security:
  - ntfWaBearerAuth: []
  - ntfWaApiKeyHeader: []
tags:
  - name: Mensagens
    description: Enviar, listar, editar e cancelar mensagens
  - name: Instâncias
    description: >-
      Cadastre e gerencie os números de WhatsApp conectados — cada número é uma
      **instância** (o telefone por onde entram e saem as mensagens).
  - name: Grupos
    description: Grupos (só conexão não oficial)
paths:
  /v1/whatsapp/instances:
    post:
      tags:
        - Instâncias
      summary: Criar instância WhatsApp
      description: >-
        Conecta um número de WhatsApp ao seu workspace. Pense nisso como
        **cadastrar o telefone** que vai enviar e receber mensagens pelo
        Notifique.


        Escolha o exemplo que combina com o seu caso:


        - **Não oficial, QR na sua tela** — você mostra o código na sua
        interface e escaneia no celular.

        - **Não oficial, link para o cliente** — você envia um link; o cliente
        escaneia no WhatsApp dele.

        - **Oficial, link para o cliente** — você envia um link; o cliente faz
        login na Meta e vincula o número.

        - **Oficial, credenciais na hora** — você já concluiu o cadastro Meta no
        navegador e envia os dados nesta requisição.

        - **Oficial, token Meta próprio (BYOK)** — você usa token e IDs da sua
        conta Meta diretamente.


        Escopo: **whatsapp:instances:create**.
      operationId: ntfWa_postV1WhatsappInstances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 1024
                  description: >-
                    Nome para identificar este número no painel (ex.: Suporte,
                    Vendas).
                expectedPhoneNumber:
                  type: string
                  minLength: 10
                  maxLength: 20
                  description: >-
                    Opcional. Número internacional que você espera conectar
                    (ex.: 5511999999999). Se escanear outro chip, a API responde
                    409.
                generateShareableLink:
                  type: boolean
                  default: false
                  description: >-
                    Gera um **link** para outra pessoa concluir a conexão. Use
                    `true` quando quem vai escanear ou fazer login Meta **não
                    está na sua tela**. Omita ou use `false` para receber o QR
                    direto na resposta e exibir na sua interface.
                metaEmbeddedCode:
                  type: string
                  description: >-
                    Código retornado pelo Facebook ao concluir o cadastro Meta
                    no navegador (Embedded Signup). Obrigatório na linha
                    oficial, salvo quando usar link compartilhável.
                metaPhoneNumberId:
                  type: string
                  description: ID do número na Meta (linha oficial).
                metaWabaId:
                  type: string
                  description: ID da conta WhatsApp Business na Meta (linha oficial).
                metaBusinessId:
                  type: string
                  description: ID opcional do portfólio Business na Meta.
                metaPin:
                  type: string
                  description: PIN opcional de registro do número na Cloud API da Meta.
                mode:
                  type: string
                  enum:
                    - UNOFFICIAL
                    - OFFICIAL
                    - OFFICIAL_BYOK
                    - OFFICIAL_BSP
                  description: >-
                    Tipo de conexão. **`UNOFFICIAL`** (padrão): QR no celular,
                    ideal para testes. **`OFFICIAL`**: linha Meta (cadastro no
                    navegador ou link para o cliente). **`OFFICIAL_BYOK`**:
                    linha Meta com token e IDs que você já possui.
                    **`OFFICIAL_BSP`**: reservado.
                metaAccessToken:
                  type: string
                  description: >-
                    Token de acesso permanente da Meta (modo BYOK — credenciais
                    próprias).
            examples:
              unofficialQrOnYourScreen:
                summary: 'Não oficial: QR na sua tela'
                description: >-
                  Você exibe o código na sua interface. Quem escaneia precisa
                  estar com o celular na sua frente.
                value:
                  name: Suporte
                  mode: UNOFFICIAL
              unofficialLinkForCustomer:
                summary: 'Não oficial: link para o cliente escanear'
                description: >-
                  Envie o link para outra pessoa; ela abre e escaneia no
                  WhatsApp dela.
                value:
                  name: Suporte
                  mode: UNOFFICIAL
                  generateShareableLink: true
              officialLinkForCustomer:
                summary: 'Oficial: link para o cliente conectar na Meta'
                description: >-
                  O cliente abre o link e conclui o login Meta para vincular o
                  número.
                value:
                  name: Suporte oficial
                  mode: OFFICIAL
                  generateShareableLink: true
              officialWithMetaCredentials:
                summary: 'Oficial: credenciais Meta na hora'
                description: Use quando o Embedded Signup já foi concluído no navegador.
                value:
                  name: Suporte oficial
                  mode: OFFICIAL
                  metaEmbeddedCode: CODE_DO_EMBEDDED_SIGNUP
                  metaPhoneNumberId: '123456789012345'
                  metaWabaId: '987654321098765'
              officialByok:
                summary: 'Oficial: token Meta próprio (BYOK)'
                description: Linha oficial com token e IDs da sua conta Meta.
                value:
                  name: Linha BYOK
                  mode: OFFICIAL_BYOK
                  metaAccessToken: EAAG...
                  metaPhoneNumberId: '123456789012345'
                  metaWabaId: '987654321098765'
      responses:
        '200':
          description: >-
            Número cadastrado. Se ainda falta conectar, a resposta traz o QR
            (`connection.base64`) ou um link (`shareableLink`) para concluir.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_CreateInstanceResponse'
              examples:
                unofficialQrOnYourScreen:
                  summary: 'Não oficial: aguardando scan do QR'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Suporte
                        status: PENDING
                        phoneNumber: null
                        mode: UNOFFICIAL
                      connection:
                        status: pending_qr
                        base64: data:image/png;base64,...
                        code: 2@...
                        count: 1
                unofficialLinkForCustomer:
                  summary: 'Não oficial: QR + link para o cliente'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Suporte
                        status: PENDING
                        phoneNumber: null
                        mode: UNOFFICIAL
                      connection:
                        status: pending_qr
                        base64: data:image/png;base64,...
                      shareableLink:
                        hostedUrl: >-
                          https://api.notifique.dev/w/instance-connect/...?token=...
                        embedUrl: >-
                          https://api.notifique.dev/w/embed/instance-connect/...?token=...
                        publicId: ...
                officialLinkForCustomer:
                  summary: 'Oficial: aguardando login Meta pelo cliente'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Suporte oficial
                        status: PENDING
                        phoneNumber: null
                        mode: OFFICIAL
                        whatsappOfficialCloud: true
                      connection:
                        status: pending_signup
                      shareableLink:
                        hostedUrl: >-
                          https://api.notifique.dev/w/instance-connect/...?token=...
                        embedUrl: >-
                          https://api.notifique.dev/w/embed/instance-connect/...?token=...
                        publicId: ...
                officialActive:
                  summary: 'Oficial: número já conectado'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Suporte oficial
                        status: ACTIVE
                        phoneNumber: '5511999999999'
                        mode: OFFICIAL
        '401':
          description: Não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
        '402':
          description: Plano expirado ou suspenso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
        '403':
          description: Escopo ausente ou limite de instâncias (PLAN_LIMIT_INSTANCES).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
        '502':
          description: Erro na conexão WhatsApp.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
        '503':
          description: Capacidade global de instâncias cheia.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
components:
  schemas:
    NtfWa_CreateInstanceResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            instance:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                status:
                  type: string
                phoneNumber:
                  type: string
                  nullable: true
                createdAt:
                  type: string
                  format: date-time
                mode:
                  type: string
                  enum:
                    - UNOFFICIAL
                    - OFFICIAL
                    - OFFICIAL_BYOK
                    - OFFICIAL_BSP
            connection:
              type: object
              description: >-
                Dados para pareamento: QR em base64, code, pairingCode e count
                (UNOFFICIAL); ou status do provider oficial (OFFICIAL*).
              properties:
                pairingCode:
                  type: string
                  nullable: true
                  description: Código de pareamento (quando disponível).
                code:
                  type: string
                  description: Código interno de conexão.
                base64:
                  type: string
                  description: >-
                    Imagem do QR code em Data URL (ex.:
                    data:image/png;base64,...). Use para exibir o QR (ex.: <img
                    src="connection.base64" />).
                count:
                  type: integer
                  description: Contador do QR/geração.
              example:
                pairingCode: null
                code: 2@KbXFfHsvo+byvkP6k4VoBIE5gZFwYHT9y6dNt/c6Sfg6M+...
                base64: >-
                  data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs...
                count: 1
            shareableLink:
              $ref: '#/components/schemas/NtfWa_ShareableLink'
    NtfWa_ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: 'Rótulo HTTP do erro (ex.: Unauthorized, Bad Request, Not Found).'
        message:
          type: string
          description: >-
            Mensagem legível para exibir ao usuário (localizada via
            Accept-Language / x-locale quando aplicável).
        code:
          type: string
          description: >-
            Código estável da API v1 (enum). Sempre presente em erros. Use com o
            status HTTP para decidir retry ou correção. Ver [Respostas de
            erro](/guides/conceitos/resposta-de-erros).
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
        note:
          type: string
      required:
        - success
        - error
        - message
        - code
    NtfWa_ShareableLink:
      type: object
      description: >-
        URLs da página pública de conexão. Quem tiver a URL pode
        conectar/desconectar a instância — rotacione o secret após o uso.
      properties:
        hostedUrl:
          type: string
          description: URL hospedada da página de conexão (inclui o token).
          example: >-
            https://api.notifique.dev/w/instance-connect/V1StGXR8_Z5jdHi6B-myT?token=AbCdEfGhIjKlMnOpQrStUvWxYz012345
        embedUrl:
          type: string
          description: URL para embed em iframe (inclui o token).
          example: >-
            https://api.notifique.dev/w/embed/instance-connect/V1StGXR8_Z5jdHi6B-myT?token=AbCdEfGhIjKlMnOpQrStUvWxYz012345
        publicId:
          type: string
          description: ID público da página de conexão.
          example: V1StGXR8_Z5jdHi6B-myT
        secret:
          type: string
          description: >-
            Secret bruto (retornado em enable/rotate). Prefira usar hostedUrl,
            que já embute o token.
          example: AbCdEfGhIjKlMnOpQrStUvWxYz012345
        iframeSnippet:
          type: string
          description: Snippet HTML de iframe pronto para colar.
          example: >-
            <iframe
            src="https://api.notifique.dev/w/embed/instance-connect/V1StGXR8_Z5jdHi6B-myT?token=AbCdEfGhIjKlMnOpQrStUvWxYz012345"
            style="border:0;width:100%;min-height:560px" allow="clipboard-read;
            clipboard-write"></iframe>
      required:
        - hostedUrl
        - embedUrl
        - publicId
  securitySchemes:
    ntfWaBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API Key no header Authorization. Exemplo: `Authorization: Bearer
        sk_live_xxxxx`
    ntfWaApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key no header x-api-key.

````