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

# Create WhatsApp instance

> Connect a WhatsApp number to your workspace. Think of it as **registering the phone** that will send and receive messages through Notifique.

Pick the example that matches your case:

- **Unofficial, QR on your screen** — you show the code in your UI and scan on the phone.
- **Unofficial, link for the customer** — you send a link; the customer scans on their WhatsApp.
- **Official, link for the customer** — you send a link; the customer signs in with Meta and links the number.
- **Official, credentials now** — Embedded Signup is already done in the browser and you send Meta data in this request.
- **Official, your own Meta token (BYOK)** — you use token and IDs from your Meta account directly.

Scope: **whatsapp:instances:create**.



## OpenAPI

````yaml /en/whatsapp-api/api-reference/openapi-whatsapp.json post /v1/whatsapp/instances
openapi: 3.0.3
info:
  title: Notifique API — WhatsApp
  description: >-
    Send WhatsApp messages and manage connections. Authenticate with
    `Authorization: Bearer sk_live_...` or `x-api-key`.
  version: 1.0.0
servers:
  - url: https://api.notifique.dev
    description: Production
security:
  - ntfWaBearerAuth: []
  - ntfWaApiKeyHeader: []
tags:
  - name: Messages
    description: Send, list, edit, and cancel messages
  - name: Instances
    description: >-
      Register and manage connected WhatsApp numbers — each number is an
      **instance** (the phone that sends and receives messages).
  - name: Groups
    description: Groups (unofficial only)
paths:
  /v1/whatsapp/instances:
    post:
      tags:
        - Instâncias
      summary: Create WhatsApp instance
      description: >-
        Connect a WhatsApp number to your workspace. Think of it as
        **registering the phone** that will send and receive messages through
        Notifique.


        Pick the example that matches your case:


        - **Unofficial, QR on your screen** — you show the code in your UI and
        scan on the phone.

        - **Unofficial, link for the customer** — you send a link; the customer
        scans on their WhatsApp.

        - **Official, link for the customer** — you send a link; the customer
        signs in with Meta and links the number.

        - **Official, credentials now** — Embedded Signup is already done in the
        browser and you send Meta data in this request.

        - **Official, your own Meta token (BYOK)** — you use token and IDs from
        your Meta account directly.


        Scope: **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: >-
                    Friendly name to identify this number in the dashboard (e.g.
                    Support, Sales).
                expectedPhoneNumber:
                  type: string
                  minLength: 10
                  maxLength: 20
                  description: >-
                    Optional. International number you expect to connect (e.g.
                    5511999999999). Scanning a different SIM returns 409.
                generateShareableLink:
                  type: boolean
                  default: false
                  description: >-
                    Returns a **link** for someone else to finish connection.
                    Use `true` when the person scanning or signing in with Meta
                    **is not on your screen**. Omit or use `false` to get the QR
                    in the response and show it in your UI.
                metaEmbeddedCode:
                  type: string
                  description: >-
                    Code from Facebook after Meta signup in the browser
                    (Embedded Signup). Required on the official line unless you
                    use a shareable link.
                metaPhoneNumberId:
                  type: string
                  description: Meta Phone Number ID (official line).
                metaWabaId:
                  type: string
                  description: WhatsApp Business Account ID on Meta (official line).
                metaBusinessId:
                  type: string
                  description: Optional Business Portfolio ID on Meta.
                metaPin:
                  type: string
                  description: Optional registration PIN for the number on Meta Cloud API.
                mode:
                  type: string
                  enum:
                    - UNOFFICIAL
                    - OFFICIAL
                    - OFFICIAL_BYOK
                    - OFFICIAL_BSP
                  description: >-
                    Connection type. **`UNOFFICIAL`** (default): QR on the
                    phone, good for testing. **`OFFICIAL`**: Meta line (browser
                    signup or link for the customer). **`OFFICIAL_BYOK`**: Meta
                    line with token and IDs you already have.
                    **`OFFICIAL_BSP`**: reserved.
                metaAccessToken:
                  type: string
                  description: >-
                    Permanent Meta access token (BYOK — bring your own
                    credentials).
            examples:
              unofficialQrOnYourScreen:
                summary: 'Unofficial: QR on your screen'
                description: >-
                  You display the code in your UI. The person scanning must be
                  in front of your screen.
                value:
                  name: Support
                  mode: UNOFFICIAL
              unofficialLinkForCustomer:
                summary: 'Unofficial: link for the customer to scan'
                description: >-
                  Send the link to someone else; they open it and scan on their
                  WhatsApp.
                value:
                  name: Support
                  mode: UNOFFICIAL
                  generateShareableLink: true
              officialLinkForCustomer:
                summary: 'Official: link for the customer to connect Meta'
                description: >-
                  The customer opens the link and completes Meta login to link
                  the number.
                value:
                  name: Official support
                  mode: OFFICIAL
                  generateShareableLink: true
              officialWithMetaCredentials:
                summary: 'Official: Meta credentials now'
                description: Use when Embedded Signup was already completed in the browser.
                value:
                  name: Official support
                  mode: OFFICIAL
                  metaEmbeddedCode: EMBEDDED_SIGNUP_CODE
                  metaPhoneNumberId: '123456789012345'
                  metaWabaId: '987654321098765'
              officialByok:
                summary: 'Official: your own Meta token (BYOK)'
                description: Official line with token and IDs from your Meta account.
                value:
                  name: BYOK line
                  mode: OFFICIAL_BYOK
                  metaAccessToken: EAAG...
                  metaPhoneNumberId: '123456789012345'
                  metaWabaId: '987654321098765'
      responses:
        '200':
          description: >-
            Number registered. If connection is still pending, the response
            includes a QR (`connection.base64`) or a link (`shareableLink`) to
            finish setup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_CreateInstanceResponse'
              examples:
                unofficialQrOnYourScreen:
                  summary: 'Unofficial: waiting for QR scan'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Support
                        status: PENDING
                        phoneNumber: null
                        mode: UNOFFICIAL
                      connection:
                        status: pending_qr
                        base64: data:image/png;base64,...
                        code: 2@...
                        count: 1
                unofficialLinkForCustomer:
                  summary: 'Unofficial: QR + link for the customer'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Support
                        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: 'Official: waiting for customer Meta login'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Official support
                        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: 'Official: number already connected'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Official support
                        status: ACTIVE
                        phoneNumber: '5511999999999'
                        mode: OFFICIAL
        '401':
          description: Unauthorized.
          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 instances (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 instances 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 official (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: >-
                    Image 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: >-
            Message 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 [Responses 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 instance — 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.

````