> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nuvia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar plantilla en masa

> 
Envía una plantilla aprobada de WhatsApp a varios contactos en una única
solicitud (`multipart/form-data`).

Los contactos se envían mediante el campo `contacts` (JSON) **o** mediante un archivo CSV/XLSX en el
campo `file`, con las columnas `name` y `phone` — uno de los dos es obligatorio.
Los parámetros de la plantilla van en `components` y deben coincidir en número y tipo
con la plantilla aprobada.

El procesamiento es síncrono y parcial: la respuesta incluye `totalProcessed`,
`sentCount`, `errorCount`, los contactos enviados y la lista de `errors` por
fila. Un contacto con error no interrumpe a los demás.

Por ser plantillas, los envíos son válidos fuera de la ventana de 24 horas, pero siguen
sujetos al límite diario del tier de la cuenta en WhatsApp.




## OpenAPI

````yaml /es/openapi.json post /v1/messages/send-bulk-template
openapi: 3.0.0
info:
  title: Nuvia API - Empresa
  description: Documentación de la API para empresas
  version: '1.0'
  contact: {}
servers:
  - url: https://api.nuvia.ai
security: []
tags:
  - name: messages
    x-group: Mensagens
  - name: contacts
    x-group: Contatos
  - name: campaigns
    x-group: Campanhas
  - name: tables
    x-group: Tabelas e Listas
  - name: agents
    x-group: Agentes
  - name: conversations
    x-group: Conversas
  - name: inboxes
    x-group: Caixas de Entrada
  - name: knowledge
    x-group: Base de Conhecimento
  - name: Webhooks
    x-group: Webhooks
  - name: campaign-enrollments
    x-group: Inscrições em Campanha
  - name: custom-fields
    x-group: Campos Customizados
paths:
  /v1/messages/send-bulk-template:
    post:
      tags:
        - messages
      summary: Enviar plantilla en masa
      description: >

        Envía una plantilla aprobada de WhatsApp a varios contactos en una única

        solicitud (`multipart/form-data`).


        Los contactos se envían mediante el campo `contacts` (JSON) **o**
        mediante un archivo CSV/XLSX en el

        campo `file`, con las columnas `name` y `phone` — uno de los dos es
        obligatorio.

        Los parámetros de la plantilla van en `components` y deben coincidir en
        número y tipo

        con la plantilla aprobada.


        El procesamiento es síncrono y parcial: la respuesta incluye
        `totalProcessed`,

        `sentCount`, `errorCount`, los contactos enviados y la lista de `errors`
        por

        fila. Un contacto con error no interrumpe a los demás.


        Por ser plantillas, los envíos son válidos fuera de la ventana de 24
        horas, pero siguen

        sujetos al límite diario del tier de la cuenta en WhatsApp.
      operationId: MessageController_sendBulkTemplate
      parameters:
        - name: x-company-id
          in: header
          description: >-
            Identificador de la empresa objetivo. Obligatorio solo para API keys
            globales (type=global). Se ignora para API keys de empresa y
            usuarios humanos.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SendBulkTemplateMessageDto'
      responses:
        '201':
          description: >-
            Envío en masa ejecutado correctamente (devuelve estadísticas
            detalladas)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTemplateResponseDto'
        '400':
          description: Datos inválidos
        '401':
          description: Token inválido o expirado
        '403':
          description: Sin permiso para acceder a este recurso
      security:
        - JWT-auth: []
components:
  schemas:
    SendBulkTemplateMessageDto:
      type: object
      properties:
        inboxId:
          type: string
          minLength: 1
          description: ID del inbox/conexión de WhatsApp que se usará para enviar
        templateName:
          type: string
          minLength: 1
          description: Nombre de la plantilla registrada en WhatsApp Business
        languageCode:
          type: string
          default: pt_BR
          description: 'Código de idioma de la plantilla (formato: pt_BR, en_US, en, etc.)'
        components:
          type: array
          description: >-
            Lista de componentes de la plantilla con sus parámetros/variables.
            Úsela para personalizar header, body y buttons con datos dinámicos.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - header
                  - body
                  - button
                description: Tipo do componente (header, body, button)
              sub_type:
                description: Subtipo do componente (usado principalmente para botões)
                type: string
                enum:
                  - quick_reply
                  - url
                  - phone_number
              index:
                description: >-
                  Índice do componente (usado para identificar botões
                  específicos)
                anyOf:
                  - type: string
                  - type: number
              parameters:
                description: Lista de parâmetros/variáveis deste componente
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - text
                        - image
                        - document
                        - video
                        - currency
                        - date_time
                        - payload
                      description: Tipo do parâmetro
                    image:
                      description: Configurações de imagem (quando type = "image")
                      type: object
                      properties:
                        link:
                          description: URL da imagem
                          type: string
                        id:
                          description: ID da imagem já carregada
                          type: string
                    document:
                      description: Configurações de documento (quando type = "document")
                      type: object
                      properties:
                        link:
                          description: URL do documento
                          type: string
                        filename:
                          description: Nome do arquivo do documento
                          type: string
                    video:
                      description: Configurações de vídeo (quando type = "video")
                      type: object
                      properties:
                        link:
                          description: URL do vídeo
                          type: string
                    text:
                      description: Texto do parâmetro
                      type: string
                    value:
                      description: Valor genérico do parâmetro (alias para text)
                      type: string
                    link:
                      description: Link genérico
                      type: string
                    imageUrl:
                      description: URL alternativa para imagem
                      type: string
                    imageId:
                      description: ID da imagem (quando já carregada)
                      type: string
                    documentUrl:
                      description: URL alternativa para documento
                      type: string
                    documentFilename:
                      description: Nome alternativo do arquivo
                      type: string
                    videoUrl:
                      description: URL alternativa para vídeo
                      type: string
                    currencyCode:
                      description: 'Código da moeda (ex: BRL, USD, EUR)'
                      type: string
                    currencyAmount:
                      description: Valor monetário
                      type: number
                    dateTime:
                      description: Data/hora no formato ISO 8601
                      type: string
                    payload:
                      description: Dados customizados em formato string
                      type: string
                    parameter_name:
                      description: Nome do parâmetro (para templates nomeados)
                      type: string
                    variable_ref:
                      description: >-
                        Referência a variável automática (ex: V_contact_name).
                        Se presente, o valor será resolvido automaticamente do
                        contact/business/conversation.
                      type: string
                    variable_type:
                      description: >-
                        Tipo da variável: "auto" = resolvida automaticamente,
                        "free" = input manual
                      type: string
                      enum:
                        - auto
                        - free
                  required:
                    - type
            required:
              - type
        contacts:
          type: array
          description: >-
            Lista de contactos que recibirán la plantilla. Opcional si envía un
            archivo CSV/Excel con los contactos.
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                description: Nome completo do contato
              phone:
                type: string
                minLength: 8
                description: 'Número de telefone com código de país (ex: 5511999999999)'
            required:
              - name
              - phone
        who_will_answer:
          type: string
          default: AGENT
          description: >-
            Define quién responderá después del envío de la plantilla. Valores:
            AGENT (agente de IA), HUMAN (agente humano). Predeterminado: AGENT
          enum:
            - AGENT
            - HUMAN
            - UNASSIGNED
        agentToActivate:
          type: string
          description: >-
            ID del agente de IA que se activará para responder. Se usa junto con
            who_will_answer=AGENT
        keep_existing_assignment:
          type: boolean
          default: false
          description: >-
            Si es true, preserva la asignación actual de la conversación: no se
            escribe nada en propietario/agente y el who_will_answer NO se aplica
            (la IA no asume). Default false para no alterar el comportamiento de
            integraciones existentes por API key — el front de atención envía
            true.
        owner_user_id:
          description: >-
            ID del usuario propietario de la conversación. `null` es la elección
            explícita de "No asignado" (autoriza a borrar el propietario
            actual); su ausencia significa que el caller no opinó sobre la
            asignación.
          type: string
          nullable: true
        attendant_user_id:
          description: >-
            ID del usuario agente humano. Aplica cuando who_will_answer=HUMAN.
            `null` es "No asignado" explícito; su ausencia significa que el
            caller no opinó. El propietario tiene precedencia: conversation.user
            = owner ?? attendant.
          type: string
          nullable: true
      required:
        - inboxId
        - templateName
    BulkTemplateResponseDto:
      type: object
      properties:
        totalProcessed:
          type: number
          description: Total de contactos procesados
        sentCount:
          type: number
          description: Cantidad de mensajes enviados correctamente
        errorCount:
          type: number
          description: Cantidad de errores durante el envío
        errors:
          type: array
          items:
            type: object
            properties:
              row:
                type: number
                description: Linha do erro no arquivo/lista
              contact:
                type: string
                description: Contato que falhou
              error:
                type: string
                description: Descrição do erro
            required:
              - row
              - contact
              - error
          description: Lista detallada de errores ocurridos
        sentContacts:
          type: array
          items:
            type: object
            properties:
              conversationId:
                type: string
                description: ID da conversa criada/utilizada
              phoneNumber:
                type: string
                description: Número de telefone do contato
            required:
              - conversationId
              - phoneNumber
          description: Lista de contactos que recibieron el mensaje correctamente
      required:
        - totalProcessed
        - sentCount
        - errorCount
        - errors
        - sentContacts
  securitySchemes:
    JWT-auth:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Token JWT de autenticação

````