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

# Enviar mensaje WhatsApp

> Envía un mensaje de WhatsApp a uno o más números. Texto, media, botones, listas o plantillas.



## OpenAPI

````yaml /es/whatsapp-api/api-reference/openapi-whatsapp.json post /v1/whatsapp/messages
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/messages:
    post:
      tags:
        - Mensagens
      summary: Enviar mensaje WhatsApp
      description: >-
        Envía un mensaje de WhatsApp a uno o más números. Texto, media, botones,
        listas o plantillas.
      operationId: ntfWa_postV1WhatsappSend
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: 'Chave única para idempotência. Alternativa: x-idempotency-key.'
        - name: x-idempotency-key
          in: header
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NtfWa_SendWhatsAppMessageRequest'
            examples:
              text:
                summary: Texto
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: text
                  payload:
                    message: Olá!
              image:
                summary: Imagen
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: image
                  payload:
                    mediaUrl: https://example.com/image.jpg
                    fileName: image.jpg
                    mimetype: image/jpeg
                    caption: Legenda opcional
              video:
                summary: Vídeo
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: video
                  payload:
                    mediaUrl: https://example.com/video.mp4
                    fileName: video.mp4
                    mimetype: video/mp4
                    caption: Legenda opcional
              audio:
                summary: Audio
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: audio
                  payload:
                    mediaUrl: https://example.com/audio.mp3
                    fileName: audio.mp3
                    mimetype: audio/mpeg
              document:
                summary: Documento
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: document
                  payload:
                    mediaUrl: https://example.com/file.pdf
                    fileName: file.pdf
                    mimetype: application/pdf
              buttons:
                summary: Botones
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: buttons
                  payload:
                    title: Confirmación
                    description: ¿Desea continuar?
                    buttons:
                      - type: reply
                        displayText: Sim
                        id: btn_yes
                      - type: reply
                        displayText: Não
                        id: btn_no
                description: Hasta 3 botones reply (o solo url / solo call).
              list:
                summary: Lista
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: list
                  payload:
                    title: Menú
                    description: Elija una opción
                    buttonText: Ver opções
                    listSections:
                      - title: Principal
                        rows:
                          - rowId: opt_1
                            title: Opción 1
                            description: Detalle
                          - rowId: opt_2
                            title: Opción 2
                description: Lista interactiva (máx. 10 filas).
              location:
                summary: Ubicación
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: location
                  payload:
                    latitude: -23.5505
                    longitude: -46.6333
                    name: São Paulo
                    address: São Paulo, SP
              scheduled:
                summary: Programada
                value:
                  instanceId: clxx...
                  to:
                    - '5511999999999'
                  type: text
                  payload:
                    message: Lembrete agendado.
                  schedule:
                    sendAt: '2025-12-31T14:00:00.000Z'
      responses:
        '202':
          description: >-
            Mensaje(ns) aceita(s). Enfileirada(s) ou agendada(s). Respuesta
            padronizada com envelope success/data; status em MAIÚSCULO (QUEUED,
            SCHEDULED).
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/NtfWa_SendWhatsAppMessageResponse'
              example:
                success: true
                data:
                  messageIds:
                    - clxx1...
                    - clxx2...
                  status: QUEUED
                  scheduledAt: null
        '400':
          description: >-
            Validação (instance_id, to, type, payload) ou envio para o próprio
            número (CANNOT_SEND_TO_SELF).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
              example:
                success: false
                error: Bad Request
                message: Validation failed
                details:
                  - field: payload.message
                    message: text type requires payload.message
                code: BAD_REQUEST
        '401':
          description: API Key ausente ou inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
        '402':
          description: >-
            Trial/plano expirado (WORKSPACE_BLOCKED), créditos/saldo
            insuficientes (INSUFFICIENT_CREDITS /
            INSUFFICIENT_CREDITS_OR_BALANCE) ou limite da API Key
            (API_KEY_SPEND_LIMIT_EXCEEDED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
        '403':
          description: >-
            Escopo whatsapp:send ausente, acesso à instancia negado ou
            agendamento não permitido (PLAN_LIMIT_SCHEDULING).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
        '404':
          description: Instancia no encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
        '429':
          description: >-
            Rate limit excedido ou limite de warm-up da instancia
            (WARMUP_DAILY_LIMIT: 20 msgs/dia nos primeiros 3 dias após
            firstConnectedAt).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
              example:
                success: false
                error: Too Many Requests
                code: WARMUP_DAILY_LIMIT
                message: >-
                  This instance is in the warm-up period (first 3 days). Daily
                  send limit is 20. Try again tomorrow or wait until warm-up
                  ends.
        '503':
          description: Falha ao enfileirar mensaje.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfWa_ErrorResponse'
components:
  schemas:
    NtfWa_SendWhatsAppMessageRequest:
      type: object
      required:
        - instanceId
        - to
        - type
        - payload
      properties:
        instanceId:
          type: string
          description: ID da instancia WhatsApp do workspace.
        to:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: >-
            Destinatários: números com DDI (ex.: 5511999999999) ou JID de grupo
            (ex.: 120363295648424210@g.us). Uma mensaje por item.
        type:
          type: string
          enum:
            - text
            - image
            - video
            - audio
            - document
            - location
            - contact
            - buttons
            - list
          description: >-
            Tipo de mensaje. Plantillas oficiales Meta: usa `POST
            /v1/templates/send` (no hay `type: template` aquí).
        payload:
          type: object
          description: >-
            Conteúdo conforme `type`. **text:** `message`.
            **image|video|audio|document:** `mediaUrl`, `fileName`, `mimetype`
            (obligatorios); `caption` opcional. **location:** `latitude`,
            `longitude`, `name`, `address`. **contact:** `contact` ou
            `contactId`. **buttons:** `title`, `description`, `buttons` (1 a 3);
            `footer` opcional. **list:** `title`, `description`, `buttonText`,
            `listSections`; `footer` opcional.
          properties:
            message:
              type: string
              maxLength: 1600
              description: >-
                Obrigatório para type=text. Limite alinhado à validação da API
                (1600 caracteres).
            mediaUrl:
              type: string
              format: uri
              description: >-
                URL pública do arquivo. Obrigatório para image, video, audio,
                document.
            fileName:
              type: string
              description: Nome do arquivo. Obrigatório para mídia.
            mimetype:
              type: string
              description: >-
                Mimetype (ex.: image/jpeg, audio/mpeg, application/pdf).
                Obrigatório para mídia.
            caption:
              type: string
              description: Leyenda opcional para image, video, audio ou document.
            latitude:
              type: number
              description: Obrigatório para type=location.
            longitude:
              type: number
              description: Obrigatório para type=location.
            name:
              type: string
              description: Nome do local. Obrigatório para type=location.
            address:
              type: string
              description: Endereço do local. Obrigatório para type=location.
            contact:
              type: object
              description: >-
                Objeto de contato. Requer fullName e pelo menos um de wuid ou
                phoneNumber. Opcionais: organization, email, url.
              properties:
                fullName:
                  type: string
                  description: Nome completo do contato.
                wuid:
                  type: string
                  description: 'Número só dígitos com DDI (ex.: 5528999999999).'
                phoneNumber:
                  type: string
                  description: 'Número formatado (ex.: +55 28 99999-9999).'
                organization:
                  type: string
                  description: Empresa ou organização.
                email:
                  type: string
                  description: E-mail.
                url:
                  type: string
                  description: URL (site, etc.).
              required:
                - fullName
            contactId:
              type: string
              description: >-
                ID do contato do workspace. Alternativa a contact; o contato é
                resolvido no envio.
            vcard:
              type: string
              description: >-
                Deprecated. Use contact ou contact_id. vCard em string ainda
                aceito para compatibilidade.
            title:
              type: string
              description: Obrigatório para type=buttons ou type=list. Título (cabeçalho).
            description:
              type: string
              description: >-
                Obrigatório para type=buttons ou type=list. Texto principal
                (corpo).
            footer:
              type: string
              description: >-
                Opcional para type=buttons ou type=list. Rodapé (footerText
                enviado ao WhatsApp).
            buttonText:
              type: string
              maxLength: 20
              description: >-
                Obrigatório para type=list. Texto do botão que abre a lista
                (máx. 20 caracteres na validação da API).
            listSections:
              type: array
              minItems: 1
              maxItems: 10
              description: >-
                Obrigatório para type=list. Seções com linhas; no máximo 10
                linhas no total entre todas as seções.
              items:
                $ref: '#/components/schemas/NtfWa_WhatsAppListSection'
            buttons:
              type: array
              minItems: 1
              maxItems: 3
              description: >-
                Obrigatório para type=buttons. Todos os botões devem ser do
                mesmo tipo: apenas reply, apenas url ou apenas call.
              items:
                $ref: '#/components/schemas/NtfWa_WhatsAppButtonItem'
        schedule:
          type: object
          properties:
            sendAt:
              type: string
              format: date-time
              description: Entre 5 minutos e 30 dias no futuro.
        options:
          type: object
          properties:
            priority:
              type: string
              enum:
                - high
                - normal
                - low
              default: normal
              description: >-
                `high` = fila prioritária de mensagens WhatsApp e fila
                prioritária de webhooks.
            maxRetries:
              type: integer
              minimum: 0
              maximum: 5
              default: 3
            webhook:
              type: object
              description: >-
                Webhook só para este envio: eventos `message.*` destes
                destinatários vão para esta URL HTTPS.
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  maxLength: 2048
                secret:
                  type: string
                  description: Opcional. Segredo HMAC.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Metadados por envio, mesclados em `Message.metadata` (pares
            string→string). Respeite limites de payload.
    NtfWa_SendWhatsAppMessageResponse:
      type: object
      description: Conteúdo de data na resposta de envio.
      properties:
        messageIds:
          type: array
          items:
            type: string
          description: IDs das mensagens criadas.
        status:
          type: string
          enum:
            - QUEUED
            - SCHEDULED
          description: Status em MAIÚSCULO.
        scheduledAt:
          type: string
          format: date-time
          nullable: true
          description: Presente quando status é SCHEDULED.
    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_WhatsAppListSection:
      type: object
      required:
        - title
        - rows
      properties:
        title:
          type: string
          maxLength: 24
          description: Título da seção (máx. 24 na API).
        rows:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/NtfWa_WhatsAppListRow'
    NtfWa_WhatsAppButtonItem:
      oneOf:
        - $ref: '#/components/schemas/NtfWa_WhatsAppButtonReply'
        - $ref: '#/components/schemas/NtfWa_WhatsAppButtonUrl'
        - $ref: '#/components/schemas/NtfWa_WhatsAppButtonCall'
      discriminator:
        propertyName: type
        mapping:
          reply:
            $ref: '#/components/schemas/NtfWa_WhatsAppButtonReply'
          url:
            $ref: '#/components/schemas/NtfWa_WhatsAppButtonUrl'
          call:
            $ref: '#/components/schemas/NtfWa_WhatsAppButtonCall'
    NtfWa_WhatsAppListRow:
      type: object
      required:
        - rowId
        - title
      properties:
        rowId:
          type: string
          description: >-
            Identificador único da linha em toda a mensaje (webhook ao
            selecionar).
        title:
          type: string
          maxLength: 24
          description: Título da linha (máx. 24 na API).
        description:
          type: string
          maxLength: 72
          description: Subtítulo opcional (máx. 72 na API).
    NtfWa_WhatsAppButtonReply:
      type: object
      required:
        - type
        - displayText
        - id
      description: >-
        Botão de resposta. O `id` é referenciado quando o destinatário toca
        (eventos/webhooks).
      properties:
        type:
          type: string
          enum:
            - reply
        displayText:
          type: string
          description: Rótulo exibido no botão.
        id:
          type: string
          description: Identificador único do botão (payload do clique).
    NtfWa_WhatsAppButtonUrl:
      type: object
      required:
        - type
        - displayText
        - url
      description: >-
        Botão que abre URL. Deve ser HTTPS e host público (sem localhost/rede
        privada).
      properties:
        type:
          type: string
          enum:
            - url
        displayText:
          type: string
          description: Rótulo exibido no botão.
        url:
          type: string
          format: uri
          description: Link HTTPS público.
    NtfWa_WhatsAppButtonCall:
      type: object
      required:
        - type
        - displayText
        - phoneNumber
      description: >-
        Botão que inicia ligação para o número informado (somente dígitos/DDI
        conforme validação da API).
      properties:
        type:
          type: string
          enum:
            - call
        displayText:
          type: string
          description: Rótulo exibido no botão.
        phoneNumber:
          type: string
          description: 'Número para discagem (ex.: 5511999999999).'
        mode:
          type: string
          enum:
            - UNOFFICIAL
            - OFFICIAL
            - OFFICIAL_BYOK
            - OFFICIAL_BSP
          description: Modo público de conexão.
  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.

````