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

# Crear instância WhatsApp

> Conecta un número de WhatsApp a su workspace. Piense en esto como **registrar el teléfono** que enviará y recibirá mensajes por Notifique.

Elija el ejemplo que encaje con su caso:

- **No oficial, QR en su pantalla** — usted muestra el código en su interfaz y escanea en el celular.
- **No oficial, enlace para el cliente** — envía un enlace; el cliente escanea en su WhatsApp.
- **Oficial, enlace para el cliente** — envía un enlace; el cliente inicia sesión en Meta y vincula el número.
- **Oficial, credenciales al momento** — ya completó el registro Meta en el navegador y envía los datos en esta solicitud.
- **Oficial, token Meta propio (BYOK)** — usa token e IDs de su cuenta Meta directamente.

Ámbito: **whatsapp:instances:create**.



## OpenAPI

````yaml /es/whatsapp-api/api-reference/openapi-whatsapp.json post /v1/whatsapp/instances
openapi: 3.0.3
info:
  title: Notifique API — WhatsApp
  description: >-
    Envíe mensajes de WhatsApp y gestione conexiones. Autentíquese con
    `Authorization: Bearer sk_live_...` o `x-api-key`.
  version: 1.0.0
servers:
  - url: https://api.notifique.dev
    description: Producción
security:
  - ntfWaBearerAuth: []
  - ntfWaApiKeyHeader: []
tags:
  - name: Mensajes
    description: Enviar, listar, editar y cancelar mensajes
  - name: Instancias
    description: >-
      Registre y gestione los números de WhatsApp conectados — cada número es
      una **instancia** (el teléfono por el que entran y salen los mensajes).
  - name: Grupos
    description: Grupos (solo conexión no oficial)
paths:
  /v1/whatsapp/instances:
    post:
      tags:
        - Instâncias
      summary: Crear instância WhatsApp
      description: >-
        Conecta un número de WhatsApp a su workspace. Piense en esto como
        **registrar el teléfono** que enviará y recibirá mensajes por Notifique.


        Elija el ejemplo que encaje con su caso:


        - **No oficial, QR en su pantalla** — usted muestra el código en su
        interfaz y escanea en el celular.

        - **No oficial, enlace para el cliente** — envía un enlace; el cliente
        escanea en su WhatsApp.

        - **Oficial, enlace para el cliente** — envía un enlace; el cliente
        inicia sesión en Meta y vincula el número.

        - **Oficial, credenciales al momento** — ya completó el registro Meta en
        el navegador y envía los datos en esta solicitud.

        - **Oficial, token Meta propio (BYOK)** — usa token e IDs de su cuenta
        Meta directamente.


        Ámbito: **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: >-
                    Nombre para identificar este número en el panel (ej.:
                    Soporte, Ventas).
                expectedPhoneNumber:
                  type: string
                  minLength: 10
                  maxLength: 20
                  description: >-
                    Opcional. Número internacional que espera conectar (ej.:
                    5511999999999). Si escanea otro chip, la API responde 409.
                generateShareableLink:
                  type: boolean
                  default: false
                  description: >-
                    Genera un **enlace** para que otra persona termine la
                    conexión. Use `true` cuando quien va a escanear o iniciar
                    sesión en Meta **no está en su pantalla**. Omita o use
                    `false` para recibir el QR en la respuesta y mostrarlo en su
                    interfaz.
                metaEmbeddedCode:
                  type: string
                  description: >-
                    Código de Facebook al completar el registro Meta en el
                    navegador (Embedded Signup). Obligatorio en la línea
                    oficial, salvo con enlace compartible.
                metaPhoneNumberId:
                  type: string
                  description: ID del número en Meta (línea oficial).
                metaWabaId:
                  type: string
                  description: ID de la cuenta WhatsApp Business en Meta (línea oficial).
                metaBusinessId:
                  type: string
                  description: ID opcional del portafolio Business en Meta.
                metaPin:
                  type: string
                  description: PIN opcional de registro del número en Cloud API de Meta.
                mode:
                  type: string
                  enum:
                    - UNOFFICIAL
                    - OFFICIAL
                    - OFFICIAL_BYOK
                    - OFFICIAL_BSP
                  description: >-
                    Tipo de conexión. **`UNOFFICIAL`** (predeterminado): QR en
                    el celular, ideal para pruebas. **`OFFICIAL`**: línea Meta
                    (registro en navegador o enlace para el cliente).
                    **`OFFICIAL_BYOK`**: línea Meta con token e IDs que ya
                    posee. **`OFFICIAL_BSP`**: reservado.
                metaAccessToken:
                  type: string
                  description: >-
                    Token de acceso permanente de Meta (modo BYOK — credenciales
                    propias).
            examples:
              unofficialQrOnYourScreen:
                summary: 'No oficial: QR en su pantalla'
                description: >-
                  Usted muestra el código en su interfaz. Quien escanea debe
                  estar frente a su pantalla.
                value:
                  name: Soporte
                  mode: UNOFFICIAL
              unofficialLinkForCustomer:
                summary: 'No oficial: enlace para que el cliente escanee'
                description: >-
                  Envíe el enlace a otra persona; ella lo abre y escanea en su
                  WhatsApp.
                value:
                  name: Soporte
                  mode: UNOFFICIAL
                  generateShareableLink: true
              officialLinkForCustomer:
                summary: 'Oficial: enlace para que el cliente conecte Meta'
                description: >-
                  El cliente abre el enlace y completa el login Meta para
                  vincular el número.
                value:
                  name: Soporte oficial
                  mode: OFFICIAL
                  generateShareableLink: true
              officialWithMetaCredentials:
                summary: 'Oficial: credenciales Meta al momento'
                description: Use cuando el Embedded Signup ya se completó en el navegador.
                value:
                  name: Soporte oficial
                  mode: OFFICIAL
                  metaEmbeddedCode: CODE_EMBEDDED_SIGNUP
                  metaPhoneNumberId: '123456789012345'
                  metaWabaId: '987654321098765'
              officialByok:
                summary: 'Oficial: token Meta propio (BYOK)'
                description: Línea oficial con token e IDs de su cuenta Meta.
                value:
                  name: Línea BYOK
                  mode: OFFICIAL_BYOK
                  metaAccessToken: EAAG...
                  metaPhoneNumberId: '123456789012345'
                  metaWabaId: '987654321098765'
      responses:
        '200':
          description: >-
            Número registrado. Si aún falta conectar, la respuesta trae el QR
            (`connection.base64`) o un enlace (`shareableLink`) para terminar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_CreateInstanceResponse'
              examples:
                unofficialQrOnYourScreen:
                  summary: 'No oficial: esperando escaneo del QR'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Soporte
                        status: PENDING
                        phoneNumber: null
                        mode: UNOFFICIAL
                      connection:
                        status: pending_qr
                        base64: data:image/png;base64,...
                        code: 2@...
                        count: 1
                unofficialLinkForCustomer:
                  summary: 'No oficial: QR + enlace para el cliente'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Soporte
                        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: esperando login Meta del cliente'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Soporte 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 ya conectado'
                  value:
                    success: true
                    data:
                      instance:
                        id: inst_abc
                        name: Soporte oficial
                        status: ACTIVE
                        phoneNumber: '5511999999999'
                        mode: OFFICIAL
        '401':
          description: No 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 instancias (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 instancias 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: >-
                    Imagen 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: >-
            Mensaje 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 [Respuestas 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 instancia — 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.

````