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

# Enviar plantilla

> Envía una plantilla de WhatsApp aprobada a un destinatario.

Envía una plantilla de WhatsApp a un número de teléfono. La plantilla debe estar **aprobada** y asociada a la línea identificada por `phoneNumberId`.

Consulta primero las plantillas disponibles con [Listar plantillas](/whatsapp/listar-plantillas).

## Endpoint

```
POST /whatsapp/{phoneNumberId}/template
```

**URL completa:** `https://api.insuranceboosters.com/api/v1/whatsapp/{phoneNumberId}/template`

## Autenticación

```http theme={null}
x-ib-api-key: <tu-api-key>
Content-Type: application/json
```

## Parámetros de ruta

| Parámetro       | Descripción                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------- |
| `phoneNumberId` | Identificador de tu línea de WhatsApp. Solicítalo con tu ejecutivo de cuenta si no lo tienes. |

## Body base

Incluye siempre `to` y `name` con tus datos reales (no se muestran en los ejemplos). El resto del body depende del tipo de plantilla:

```json theme={null}
{
  "language": "es",
  "components": []
}
```

Consulta [Tipos de plantilla](/whatsapp/tipos-de-plantilla) para el flujo completo de listar → armar payload → enviar.

## Campos del body

| Campo        | Requerido | Descripción                                                                                                           |
| ------------ | --------- | --------------------------------------------------------------------------------------------------------------------- |
| `to`         | Sí        | Número destino en formato [E.164](https://www.itu.int/rec/T-REC-E.164/) (solo dígitos, sin `+`).                      |
| `name`       | Sí        | Nombre exacto de la plantilla aprobada (cópialo del listado).                                                         |
| `language`   | Sí\*      | Idioma exacto con el que se aprobó la plantilla (ej. `es`, `es_MX`). \*Si no lo envías, el valor por defecto es `es`. |
| `components` | Sí        | Componentes dinámicos. Usa `[]` si la plantilla no tiene variables.                                                   |

## Siguiente paso: elige tu tipo de plantilla

El endpoint es el mismo en todos los casos; lo que cambia es el arreglo `components`. Revisa primero tu plantilla con [Listar plantillas](/whatsapp/listar-plantillas) y fíjate en `parameter_format` y la estructura de `components`.

En el menú lateral, abre **Tipos de plantilla** para ver las guías por escenario. Cada una precarga el playground con el payload completo de ese caso (`components` incluidos); solo completas `to`, `name` y tu API key.

| Escenario                                                                   | Cuándo usarlo                               |
| --------------------------------------------------------------------------- | ------------------------------------------- |
| [Sin variables](/whatsapp/enviar-plantilla/sin-variables)                   | Plantilla fija, sin placeholders.           |
| [Variables posicionales](/whatsapp/enviar-plantilla/variables-posicionales) | Body con `{{1}}`, `{{2}}`, etc.             |
| [Variables con nombre](/whatsapp/enviar-plantilla/variables-con-nombre)     | Body con `{{nombre}}`, `{{monto}}`, etc.    |
| [Header con imagen](/whatsapp/enviar-plantilla/header-imagen)               | Imagen en el header y variables en el body. |
| [Header con PDF](/whatsapp/enviar-plantilla/header-pdf)                     | Documento PDF en el header.                 |
| [Header con video](/whatsapp/enviar-plantilla/header-video)                 | Video en el header.                         |
| [Botones dinámicos](/whatsapp/enviar-plantilla/botones-dinamicos)           | Botones URL, quick reply y copiar código.   |

## Reglas importantes

1. `name` y `language` deben coincidir **exactamente** con la plantilla aprobada.
2. La cantidad y el orden de `parameters` deben coincidir con los placeholders de la plantilla.
3. Incluye siempre `Content-Type: application/json`.
4. El número `to` debe estar en formato E.164.

## Respuesta exitosa (`200`)

```json theme={null}
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "5215512345678",
      "wa_id": "5215512345678"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgNNTIxNTUxMjM0NTY3OBUCABIYFDNBM0U0QzNCM0U0QzNCM0U0QzNCA"
    }
  ]
}
```

`messages[0].id` es el identificador del mensaje enviado.

## Errores frecuentes

| HTTP          | Qué significa                                                                       | Qué hacer                                                                                   |
| ------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `401`         | API key inválida, faltante o línea sin credenciales de WhatsApp.                    | Verifica `x-ib-api-key` o confirma la configuración de la línea con tu ejecutivo de cuenta. |
| `404`         | `phoneNumberId` incorrecto.                                                         | Confirma el identificador de la línea.                                                      |
| `400`         | Falta `to`/`name`, estructura de `components` inválida o URL de media no accesible. | Revisa nombre, idioma, orden y nombres de variables.                                        |
| `4xx` / `5xx` | WhatsApp rechazó el mensaje.                                                        | Revisa que la plantilla esté aprobada y que el destinatario tenga WhatsApp.                 |

La respuesta incluye un mensaje descriptivo en el cuerpo JSON.

## Probar en el playground

1. Tu **API key** en `x-ib-api-key`
2. El **phoneNumberId** de tu línea
3. Abre la guía del escenario en [Tipos de plantilla](/whatsapp/tipos-de-plantilla) — el payload viene precargado
4. Completa **`to`** y **`name`** con tus datos reales antes de enviar


## OpenAPI

````yaml openapi/whatsapp-v1.json POST /whatsapp/{phoneNumberId}/template
openapi: 3.1.0
info:
  title: Insurance Boosters API
  version: 1.0.0
  description: >-
    API pública de Insurance Boosters. Consulta y envío de plantillas de
    WhatsApp.
servers:
  - url: https://api.insuranceboosters.com/api/v1
    description: Producción
security:
  - IbApiKey: []
tags:
  - name: WhatsApp
    description: Mensajería de WhatsApp Business.
paths:
  /whatsapp/{phoneNumberId}/template:
    post:
      tags:
        - WhatsApp
      summary: Enviar plantilla de WhatsApp
      description: >-
        Envía una plantilla de WhatsApp aprobada a un destinatario.


        El `phoneNumberId` identifica la línea de WhatsApp desde la que se envía
        el mensaje.
      operationId: sendWhatsAppTemplate
      parameters:
        - name: phoneNumberId
          in: path
          required: true
          description: >-
            Identificador de tu línea de WhatsApp. Solicítalo con tu ejecutivo
            de cuenta.
          schema:
            type: string
            example: '123456789012345'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendTemplateRequest'
            examples:
              sinVariables:
                summary: Plantilla sin variables
                value:
                  to: ''
                  name: ''
                  language: es
                  components: []
              bodyPosicional:
                summary: Variables posicionales en el body
                value:
                  to: ''
                  name: ''
                  language: es
                  components:
                    - type: body
                      parameters:
                        - type: text
                          text: '1000'
                        - type: text
                          text: '2000'
                        - type: text
                          text: '3000'
              bodyNombrado:
                summary: Variables con nombre en el body
                value:
                  to: ''
                  name: ''
                  language: es
                  components:
                    - type: body
                      parameters:
                        - type: text
                          parameter_name: nombre
                          text: María
                        - type: text
                          parameter_name: monto
                          text: $1,500
                        - type: text
                          parameter_name: fecha_limite
                          text: 15/08/2026
              headerImagen:
                summary: Header con imagen y variables en el body
                value:
                  to: ''
                  name: ''
                  language: es
                  components:
                    - type: header
                      parameters:
                        - type: image
                          image:
                            link: https://tu-dominio.com/imagen.png
                    - type: body
                      parameters:
                        - type: text
                          parameter_name: agente
                          text: María
              headerDocumento:
                summary: Header con documento PDF
                value:
                  to: ''
                  name: ''
                  language: es
                  components:
                    - type: header
                      parameters:
                        - type: document
                          document:
                            link: https://tu-dominio.com/poliza.pdf
                            filename: poliza.pdf
              headerVideo:
                summary: Header con video
                value:
                  to: ''
                  name: ''
                  language: es
                  components:
                    - type: header
                      parameters:
                        - type: video
                          video:
                            link: https://tu-dominio.com/video.mp4
              botonUrl:
                summary: Botón URL dinámico
                value:
                  to: ''
                  name: ''
                  language: es_MX
                  components:
                    - type: button
                      sub_type: url
                      index: '0'
                      parameters:
                        - type: text
                          text: '?ref=abc123'
              botonQuickReply:
                summary: Botón quick reply con variable
                value:
                  to: ''
                  name: ''
                  language: es
                  components:
                    - type: button
                      sub_type: quick_reply
                      index: '0'
                      parameters:
                        - type: payload
                          payload: ACCION_OK
              botonCopyCode:
                summary: Botón copiar código con variable
                value:
                  to: ''
                  name: ''
                  language: es
                  components:
                    - type: button
                      sub_type: copy_code
                      index: '0'
                      parameters:
                        - type: coupon_code
                          coupon_code: CODIGO123
      responses:
        '200':
          description: Plantilla enviada correctamente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendTemplateResponse'
        '400':
          description: >-
            Solicitud inválida (campos faltantes, components incorrectos o URL
            de media no accesible).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SimpleErrorResponse'
                  - $ref: '#/components/schemas/TemplateMediaErrorResponse'
        '401':
          description: API key inválida o línea no autorizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
        '404':
          description: Línea de WhatsApp no encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
        '500':
          description: Error del servicio. Reintenta o contacta soporte.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
components:
  schemas:
    SendTemplateRequest:
      type: object
      required:
        - to
        - name
      properties:
        to:
          type: string
          description: >-
            Teléfono del destinatario en formato E.164 (solo dígitos, sin `+`).
            Ejemplo México: 5215512345678.
          x-default: ''
        name:
          type: string
          description: Nombre exacto de la plantilla aprobada.
          x-default: ''
        language:
          type: string
          description: Código de idioma de la plantilla. Por defecto `es`.
          default: es
          example: es
        components:
          type: array
          description: >-
            Componentes dinámicos (`header`, `body`, `button`). Omitir o enviar
            `[]` si la plantilla no tiene variables.
          items:
            $ref: '#/components/schemas/TemplateComponent'
          default: []
        inactiveBot:
          type: boolean
          description: >-
            Si es `true`, desactiva respuestas automáticas para ese contacto
            tras el envío.
          default: false
    SendTemplateResponse:
      type: object
      properties:
        messaging_product:
          type: string
          enum:
            - whatsapp
        contacts:
          type: array
          items:
            type: object
            properties:
              input:
                type: string
              wa_id:
                type: string
        messages:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Identificador del mensaje enviado.
    SimpleErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    TemplateMediaErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Descripción del problema con el archivo multimedia.
    TemplateComponent:
      oneOf:
        - $ref: '#/components/schemas/HeaderComponent'
        - $ref: '#/components/schemas/BodyComponent'
        - $ref: '#/components/schemas/ButtonComponent'
      discriminator:
        propertyName: type
        mapping:
          header:
            $ref: '#/components/schemas/HeaderComponent'
          body:
            $ref: '#/components/schemas/BodyComponent'
          button:
            $ref: '#/components/schemas/ButtonComponent'
    HeaderComponent:
      title: Encabezado (header)
      type: object
      required:
        - type
        - parameters
      properties:
        type:
          type: string
          enum:
            - header
        parameters:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/ImageParameter'
              - $ref: '#/components/schemas/VideoParameter'
              - $ref: '#/components/schemas/DocumentParameter'
            discriminator:
              propertyName: type
              mapping:
                image:
                  $ref: '#/components/schemas/ImageParameter'
                video:
                  $ref: '#/components/schemas/VideoParameter'
                document:
                  $ref: '#/components/schemas/DocumentParameter'
    BodyComponent:
      title: Cuerpo (body)
      type: object
      required:
        - type
        - parameters
      properties:
        type:
          type: string
          enum:
            - body
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/TextParameter'
    ButtonComponent:
      title: Botón (button)
      type: object
      required:
        - type
        - sub_type
        - index
        - parameters
      properties:
        type:
          type: string
          enum:
            - button
        sub_type:
          type: string
          enum:
            - url
            - quick_reply
            - copy_code
          description: Tipo de botón dinámico.
        index:
          type: string
          description: Índice del botón en la plantilla (base 0, como string).
          example: '0'
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/ButtonParameter'
    ImageParameter:
      title: Imagen
      type: object
      required:
        - type
        - image
      properties:
        type:
          type: string
          enum:
            - image
        image:
          title: Archivo de imagen
          type: object
          required:
            - link
          properties:
            link:
              type: string
              format: uri
              description: URL pública de la imagen (HTTPS). Es el único campo requerido.
    VideoParameter:
      title: Video
      type: object
      required:
        - type
        - video
      properties:
        type:
          type: string
          enum:
            - video
        video:
          title: Archivo de video
          type: object
          required:
            - link
          properties:
            link:
              type: string
              format: uri
    DocumentParameter:
      title: Documento
      type: object
      required:
        - type
        - document
      properties:
        type:
          type: string
          enum:
            - document
        document:
          title: Archivo PDF
          type: object
          required:
            - link
          properties:
            link:
              type: string
              format: uri
            filename:
              type: string
    TextParameter:
      title: Texto
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
        parameter_name:
          type: string
          description: Nombre del parámetro cuando la plantilla usa variables con nombre.
    ButtonParameter:
      oneOf:
        - $ref: '#/components/schemas/ButtonTextParameter'
        - $ref: '#/components/schemas/ButtonPayloadParameter'
        - $ref: '#/components/schemas/ButtonCouponParameter'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/ButtonTextParameter'
          payload:
            $ref: '#/components/schemas/ButtonPayloadParameter'
          coupon_code:
            $ref: '#/components/schemas/ButtonCouponParameter'
    ButtonTextParameter:
      title: Texto para URL
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
          description: Fragmento que se concatena al final de la URL del botón.
    ButtonPayloadParameter:
      title: Payload quick reply
      type: object
      required:
        - type
        - payload
      properties:
        type:
          type: string
          enum:
            - payload
        payload:
          type: string
    ButtonCouponParameter:
      title: Código copiar
      type: object
      required:
        - type
        - coupon_code
      properties:
        type:
          type: string
          enum:
            - coupon_code
        coupon_code:
          type: string
  securitySchemes:
    IbApiKey:
      type: apiKey
      in: header
      name: x-ib-api-key
      description: API key emitida por Insurance Boosters.

````