> ## 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 template em massa > Dispara um template aprovado do WhatsApp para vários contatos em uma única requisição (`multipart/form-data`). Os contatos vêm pelo campo `contacts` (JSON) **ou** por um arquivo CSV/XLSX no campo `file`, com as colunas `name` e `phone` — um dos dois é obrigatório. Os parâmetros do template vão em `components` e precisam casar em número e tipo com o template aprovado. O processamento é síncrono e parcial: a resposta traz `totalProcessed`, `sentCount`, `errorCount`, os contatos enviados e a lista de `errors` por linha. Contato com erro não interrompe os demais. Por serem templates, os envios valem fora da janela de 24 horas, mas continuam sujeitos ao limite diário do tier da conta no WhatsApp. ## OpenAPI ````yaml https://api.nuvia.ai/api/docs/user-json post /v1/messages/send-bulk-template openapi: 3.0.0 info: title: Nuvia API - Empresa description: Documentação da 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 paths: /v1/messages/send-bulk-template: post: tags: - messages summary: Enviar template em massa description: > Dispara um template aprovado do WhatsApp para vários contatos em uma única requisição (`multipart/form-data`). Os contatos vêm pelo campo `contacts` (JSON) **ou** por um arquivo CSV/XLSX no campo `file`, com as colunas `name` e `phone` — um dos dois é obrigatório. Os parâmetros do template vão em `components` e precisam casar em número e tipo com o template aprovado. O processamento é síncrono e parcial: a resposta traz `totalProcessed`, `sentCount`, `errorCount`, os contatos enviados e a lista de `errors` por linha. Contato com erro não interrompe os demais. Por serem templates, os envios valem fora da janela de 24 horas, mas continuam sujeitos ao limite diário do tier da conta no WhatsApp. operationId: MessageController_sendBulkTemplate parameters: - name: x-company-id in: header description: >- Identificador da empresa-alvo. Obrigatório apenas para API Keys globais (type=global). Ignorado para API Keys de empresa e usuários humanos. required: false schema: type: string requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/SendBulkTemplateMessageDto' responses: '201': description: >- Envio em massa executado com sucesso (retorna estatísticas detalhadas) content: application/json: schema: $ref: '#/components/schemas/BulkTemplateResponseDto' '400': description: Dados inválidos '401': description: Token inválido ou expirado '403': description: Sem permissão para acessar este recurso security: - JWT-auth: [] components: schemas: SendBulkTemplateMessageDto: type: object properties: inboxId: type: string minLength: 1 description: ID do inbox/conexão WhatsApp que será usado para enviar templateName: type: string minLength: 1 description: Nome do template registrado no WhatsApp Business languageCode: type: string default: pt_BR description: 'Código de idioma do template (formato: pt_BR, en_US, en, etc)' components: type: array description: >- Lista de componentes do template com seus parâmetros/variáveis. Use para personalizar header, body e buttons com dados 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 contatos que receberão o template. Opcional se você enviar um arquivo CSV/Excel com os contatos. 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 quem responderá após o envio do template. Valores: AGENT (agente IA), HUMAN (atendente humano). Padrão: AGENT enum: - AGENT - HUMAN - UNASSIGNED agentToActivate: type: string description: >- ID do agente IA que será ativado para responder. Usado em conjunto com who_will_answer=AGENT required: - inboxId - templateName BulkTemplateResponseDto: type: object properties: totalProcessed: type: number description: Total de contatos processados sentCount: type: number description: Quantidade de mensagens enviadas com sucesso errorCount: type: number description: Quantidade de erros durante o envio 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 detalhada de erros ocorridos 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 contatos que receberam a mensagem com sucesso required: - totalProcessed - sentCount - errorCount - errors - sentContacts securitySchemes: JWT-auth: scheme: bearer bearerFormat: JWT type: http description: Token JWT de autenticação ````