> ## 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. Contrato canónico: `type` + `payload` (texto, media, botones, lista, carrusel o `type: template` con `payload.templateId`). Use `from` para elegir instancia o pool. En la **no oficial**, `type=buttons` y `type=carousel` también están disponibles; pueden dejar de funcionar en cualquier momento. ## 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) - name: Llamadas description: Llamar y hablar en WhatsApp (no oficial hoy; oficial pronto) - name: Sending pools description: Balanceamento de instâncias WhatsApp 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. Contrato canónico: `type` + `payload` (texto, media, botones, lista, carrusel o `type: template` con `payload.templateId`). Use `from` para elegir instancia o pool. En la **no oficial**, `type=buttons` y `type=carousel` también están disponibles; pueden dejar de funcionar en cualquier momento. 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: to: - '5511999999999' type: text payload: message: Olá! from: clxx... image: summary: Imagen value: to: - '5511999999999' type: image payload: mediaUrl: https://example.com/image.jpg fileName: image.jpg mimetype: image/jpeg caption: Legenda opcional from: clxx... video: summary: Vídeo value: to: - '5511999999999' type: video payload: mediaUrl: https://example.com/video.mp4 fileName: video.mp4 mimetype: video/mp4 caption: Legenda opcional from: clxx... audio: summary: Audio value: to: - '5511999999999' type: audio payload: mediaUrl: https://example.com/audio.mp3 fileName: audio.mp3 mimetype: audio/mpeg from: clxx... document: summary: Documento value: to: - '5511999999999' type: document payload: mediaUrl: https://example.com/file.pdf fileName: file.pdf mimetype: application/pdf from: clxx... buttons: summary: Botones value: 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 from: clxx... description: Hasta 3 botones reply (o solo url / solo call). list: summary: Lista value: 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 from: clxx... description: Lista interactiva (máx. 10 filas). carousel: summary: Carrusel description: >- Solo en conexión no oficial (QR). Varias cards con media, texto y botones. Puede dejar de funcionar en cualquier momento. value: to: - '5511999999999' type: carousel payload: body: Confira as ofertas cards: - mediaUrl: https://example.com/card1.jpg mediaKind: image body: Card 1 - oferta buttons: - type: reply displayText: Quero id: c1_ok - mediaUrl: https://example.com/card2.jpg mediaKind: image body: Card 2 - info buttons: - type: reply displayText: Info id: c2_info from: clxx... location: summary: Ubicación value: to: - '5511999999999' type: location payload: latitude: -23.5505 longitude: -46.6333 name: São Paulo address: São Paulo, SP from: clxx... scheduled: summary: Programada value: to: - '5511999999999' type: text payload: message: Lembrete agendado. schedule: sendAt: '2025-12-31T14:00:00.000Z' from: clxx... template: summary: Plantilla del workspace value: to: - '5511999999999' type: template payload: templateId: clxx_template... variables: nombre: Maria codigo: '482910' from: clxx... 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: $ref: '#/components/schemas/ntfWa_PostV1WhatsappSendResponse' example: success: true data: messageIds: - clxx1... - clxx2... count: 2 status: QUEUED scheduledAt: null sandbox: false localization: appliedAiLocales: - en fallbackLocales: - pt aiTranslatedRecipientCount: 1 '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' example: success: false error: Bad Request code: VALIDATION_ERROR message: Campo inválido ou ausente. '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' example: success: false error: Bad Request code: VALIDATION_ERROR message: Campo inválido ou ausente. '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' example: success: false error: Bad Request code: VALIDATION_ERROR message: Campo inválido ou ausente. '404': description: Instancia no encontrada. content: application/json: schema: $ref: '#/components/schemas/NtfWa_ErrorResponse' example: success: false error: Bad Request code: VALIDATION_ERROR message: Campo inválido ou ausente. '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' example: success: false error: Service Unavailable message: Failed to enqueue message code: SERVICE_UNAVAILABLE components: schemas: NtfWa_SendWhatsAppMessageRequest: type: object required: - from - to - type - payload properties: to: type: array items: type: string minItems: 1 maxItems: 500 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 - carousel - template description: >- Tipo de mensaje. Use `template` con `payload.templateId` para plantillas del workspace (oficial o no oficial). payload: type: object description: >- Contenido según `type`. **text:** `message`. **image|video|audio|document:** `mediaUrl`, `fileName`, `mimetype` (obligatorios); `caption` opcional. **location:** `latitude`, `longitude`, `name`, `address`. **contact:** `contact` o `contactId`. **buttons:** `title`, `description`, `buttons` (1 a 3; reply | copy | url | call | pix). **list:** `title`, `description`, `buttonText`, `listSections`. **carousel:** `cards` (1 a 10). **template:** `templateId`, `variables`, `headerMediaUrl`, `carouselCardMediaUrls`. properties: 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. required: - fullName contactId: type: string description: >- ID do contato do workspace. Alternativa a contact; o contato é resolvido no envio. description: type: string description: >- Obrigatório para type=buttons ou type=list. Texto principal (corpo). footer: type: string description: >- Opcional para type=buttons, type=list o type=carousel. Pie de página (footerText enviado a 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: >- Obligatorio para type=buttons. Hasta 3 botones del mismo grupo: reply; copy/url/call; o un solo pix. items: $ref: '#/components/schemas/NtfWa_WhatsAppButtonItem' cards: type: array minItems: 1 maxItems: 10 description: Obligatorio para type=carousel. items: $ref: '#/components/schemas/NtfWa_WhatsAppCarouselCard' templateId: type: string description: Obrigatório para type=template. ID do template do workspace. variables: type: object additionalProperties: type: string description: >- Opcional. Objeto JSON **clave → valor** que rellena los placeholders (ej.: `{"nombre": "Maria", "codigo": "482910"}`). properties: '1': type: string example: Maria nombre: type: string example: Maria codigo: type: string example: '482910' headerMediaUrl: type: string format: uri description: >- URL pública de mídia do cabeçalho (template com header de mídia). carouselCardMediaUrls: type: array items: type: string nullable: true description: URLs de mídia por card (template carrossel). message: type: string example: Olá! title: type: string example: Confirmación body: type: string example: Confira as ofertas 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: secret: type: string description: Opcional. Segredo HMAC. autoReplyText: type: string maxLength: 1600 description: >- Texto enviado automáticamente (1×) cuando el destinatario responda (correlacionado al envío). fallback: type: object description: Canal de respaldo en fallo final de WhatsApp (máx. 1). required: - channel properties: channel: type: string enum: - sms description: Canal de fallback suportado. interactiveFallback: type: boolean default: true description: >- QR/no oficial: reenvía PIX o lista como texto si no hay DELIVERED en ~20s. Por defecto true. metadata: type: object additionalProperties: type: string description: >- Metadados por envio, mesclados em `Message.metadata` (pares string→string). Respeite limites de payload. localization: type: object description: >- Tradução por destinatário (manual ou IA). Campos traduzíveis: payload.message, payload.caption. properties: mode: type: string enum: - 'off' - manual - ai default: 'off' description: >- off = sem tradução; manual = usa i18n; ai = traduz com IA conforme idioma do contato. sourceLocale: type: string description: 'Locale BCP-47 do texto base (ex.: pt-BR).' i18n: type: object additionalProperties: true description: >- Mapa locale → string ou objeto com chaves por campo (message, caption, …). Usado com localization.mode=manual. variables: type: object additionalProperties: type: string description: >- Variáveis para substituir placeholders {{chave}} em payload.message, payload.caption e options.autoReplyText. from: type: string description: >- Remetente WhatsApp: id da instância, id ou nome do pool, telefone E.164 ou nome da instância. example: to: - '5511999999999' type: text payload: mediaUrl: https://example.com/resource fileName: string mimetype: string caption: string latitude: 1 longitude: 1 name: Exemplo address: string contact: fullName: string wuid: clxx... phoneNumber: string organization: string email: string contactId: clxx... description: string footer: string buttonText: string listSections: - title: string rows: - rowId: clxx... title: string description: string buttons: - type: reply displayText: string id: clxx... cards: - mediaUrl: https://example.com/resource body: string mediaKind: image buttons: - {} templateId: clxx... variables: {} headerMediaUrl: https://example.com/resource carouselCardMediaUrls: - string schedule: sendAt: '2025-02-10T14:00:00.000Z' options: priority: normal maxRetries: 3 webhook: secret: string autoReplyText: string fallback: channel: sms interactiveFallback: true metadata: {} localization: mode: 'off' sourceLocale: string i18n: {} variables: {} from: clxx... ntfWa_PostV1WhatsappSendResponse: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/NtfWa_SendWhatsAppMessageResponse' example: success: true data: messageIds: - clxx... status: QUEUED scheduledAt: '2025-02-10T14:00:00.000Z' count: 1 sandbox: true localization: appliedAiLocales: - string fallbackLocales: - string aiTranslatedRecipientCount: 1 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 example: success: false error: string message: string code: string details: - field: string message: string note: string 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' example: title: string rows: - rowId: clxx... title: string description: string NtfWa_WhatsAppButtonItem: oneOf: - $ref: '#/components/schemas/NtfWa_WhatsAppButtonReply' - $ref: '#/components/schemas/NtfWa_WhatsAppButtonUrl' - $ref: '#/components/schemas/NtfWa_WhatsAppButtonCall' - $ref: '#/components/schemas/NtfWa_WhatsAppButtonCopy' - $ref: '#/components/schemas/NtfWa_WhatsAppButtonPix' discriminator: propertyName: type mapping: reply: $ref: '#/components/schemas/NtfWa_WhatsAppButtonReply' url: $ref: '#/components/schemas/NtfWa_WhatsAppButtonUrl' call: $ref: '#/components/schemas/NtfWa_WhatsAppButtonCall' copy: $ref: '#/components/schemas/NtfWa_WhatsAppButtonCopy' pix: $ref: '#/components/schemas/NtfWa_WhatsAppButtonPix' NtfWa_WhatsAppCarouselCard: type: object required: - mediaUrl - body properties: mediaUrl: type: string format: uri description: URL pública HTTPS de la media de la card. mediaKind: type: string enum: - image - video default: image description: Tipo de media de la card. body: type: string description: Texto de la card. buttons: type: array maxItems: 2 description: Hasta 2 botones por card (mismo shape que type=buttons). items: $ref: '#/components/schemas/NtfWa_WhatsAppButtonItem' example: mediaUrl: https://example.com/resource body: string mediaKind: image buttons: - type: reply displayText: string id: clxx... 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. count: type: integer description: Quantidade de mensagens criadas. sandbox: type: boolean description: true quando o envio foi interceptado pelo sandbox (sk_test_...). localization: type: object description: Presente quando localization.mode é manual ou ai e houve tradução. properties: appliedAiLocales: type: array items: type: string description: Locales traduzidos por IA neste envio. fallbackLocales: type: array items: type: string description: Locales sem tradução manual/IA; usou texto base. aiTranslatedRecipientCount: type: integer description: >- Destinatários que receberam pelo menos um campo traduzido por IA. from: type: string description: >- Remetente WhatsApp: id da instância, id ou nome do pool, telefone E.164 ou nome da instância. example: messageIds: - clxx... status: QUEUED scheduledAt: '2025-02-10T14:00:00.000Z' count: 1 sandbox: true localization: appliedAiLocales: - string fallbackLocales: - string aiTranslatedRecipientCount: 1 required: - from 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). example: rowId: clxx... title: string description: string 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). example: type: reply displayText: string id: clxx... 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. example: type: url displayText: string url: https://example.com/resource 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. example: type: call displayText: string phoneNumber: string mode: UNOFFICIAL NtfWa_WhatsAppButtonCopy: type: object required: - type - displayText - copyCode description: Botão copiar código (PIX copia e cola, cupom, etc.). properties: type: type: string enum: - copy displayText: type: string copyCode: type: string description: Código copiado ao tocar. id: type: string description: Opcional. Identificador interno. example: type: copy displayText: string copyCode: string id: clxx... NtfWa_WhatsAppButtonPix: type: object required: - type - name - keyType - key description: Botão PIX (deve ser o único botão da mensagem). properties: type: type: string enum: - pix displayText: type: string description: Opcional. Padrão PIX. currency: type: string default: BRL description: 'Moeda ISO (ex.: BRL).' name: type: string description: Nome do recebedor no card PIX. keyType: type: string enum: - phone - email - cpf - cnpj - random description: Tipo da chave PIX. key: type: string description: Valor da chave PIX. example: type: pix name: Exemplo keyType: phone key: string displayText: string currency: BRL 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. ````