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

# Plantilla con WhatsApp Flow

> Envía una plantilla aprobada con botón Flow y correlaciona cada sesión mediante flow_token.

Guía de [Enviar plantilla](https://developers.insuranceboosters.com/whatsapp/enviar-plantilla.md) · [Tipos de plantilla](https://developers.insuranceboosters.com/whatsapp/tipos-de-plantilla)

Usa este payload cuando la plantilla aprobada en Meta contiene un botón
`FLOW`. El `flow_id` ya forma parte de la plantilla aprobada y no se repite al
enviar el mensaje.

```json theme={null}
{
  "to": "5215512345678",
  "name": "cotizacion_autos",
  "language": "es",
  "components": [
    {
      "type": "button",
      "sub_type": "flow",
      "index": "0",
      "parameters": [
        {
          "type": "action",
          "action": {
            "flow_token": "550e8400-e29b-41d4-a716-446655440000"
          }
        }
      ]
    }
  ]
}
```

## Qué representa `flow_token`

`flow_token` es el identificador opaco de una instancia o sesión del Flow. No
es una API key ni una credencial de autenticación.

Permite correlacionar:

* el envío de la plantilla;
* las consultas intermedias al Data Endpoint;
* la respuesta final;
* el contacto, mensaje y contexto de negocio originales.

Si el Flow usa un Data Endpoint, cada envío necesita un valor único. Puedes
proporcionar tu propio UUID u omitir `flow_token` para que la API genere uno.
No uses valores secuenciales ni incluyas datos personales. Meta devuelve
exactamente el valor enviado al Data Endpoint.

> [!WARNING]
>
> Cuando omites `flow_token`, Insurance Boosters genera un UUID antes de enviar
> la plantilla a Meta y registra automáticamente ese mismo valor con el Flow y
> el contexto del envío. Si envías la plantilla directamente a Meta, esta
> generación y asociación automáticas no ocurren.

## Datos iniciales opcionales

Puedes agregar `flow_action_data` dentro de `action` para enviar datos
iniciales definidos por la primera pantalla:

```json theme={null}
{
  "type": "action",
  "action": {
    "flow_token": "550e8400-e29b-41d4-a716-446655440000",
    "flow_action_data": {
      "cliente_id": "cli_123"
    }
  }
}
```

> [!NOTE]
>
> `message_status: "accepted"` confirma que Meta aceptó la solicitud; no
> confirma todavía la entrega al destinatario ni la finalización del Flow.

## Errores frecuentes

| Error | Causa probable |
| - | - |
| `Components sub_type invalid` | Se omitió el componente del botón `flow` o se envió `components: []`. |
| El Data Endpoint no encuentra la sesión | El token no se registró, cambió o fue reutilizado. |
| Meta rechaza la plantilla | El nombre, idioma o índice del botón no coincide con la plantilla aprobada. |


## 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, y envío de documentos, imágenes y videos con texto.
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'
              botonFlow:
                summary: Plantilla con botón de WhatsApp Flow
                value:
                  to: ''
                  name: ''
                  language: es
                  components:
                    - type: button
                      sub_type: flow
                      index: '0'
                      parameters:
                        - type: action
                          action: {}
              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: '{"action":"confirm_payment","recordId":"rec_123"}'
              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'
        '429':
          description: >-
            Envíos pausados para esta plantilla tras rechazos repetidos de
            WhatsApp por errores de la plantilla (no existe en el idioma, faltan
            parámetros o no coinciden). Los límites de envío de WhatsApp y los
            errores de un destinatario no pausan la plantilla. No reintentes
            hasta corregir el nombre, el idioma o los parámetros. Respeta el
            header `Retry-After`.
          headers:
            Retry-After:
              description: Segundos hasta que se permite un nuevo intento.
              schema:
                type: integer
          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: '#/components/schemas/HeaderComponent'
          body: '#/components/schemas/BodyComponent'
          button: '#/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: '#/components/schemas/ImageParameter'
                video: '#/components/schemas/VideoParameter'
                document: '#/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
            - flow
          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'
        - $ref: '#/components/schemas/FlowActionParameter'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/ButtonTextParameter'
          payload: '#/components/schemas/ButtonPayloadParameter'
          coupon_code: '#/components/schemas/ButtonCouponParameter'
          action: '#/components/schemas/FlowActionParameter'
    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
    FlowActionParameter:
      title: Sesión de WhatsApp Flow
      type: object
      required:
        - type
        - action
      properties:
        type:
          type: string
          enum:
            - action
        action:
          type: object
          properties:
            flow_token:
              type: string
              minLength: 1
              description: >-
                Identificador opaco y único de esta sesión del Flow. Es
                opcional: si se omite, la API genera uno. No es una credencial
                de autenticación.
            flow_action_data:
              type: object
              description: Datos iniciales opcionales para la primera pantalla.
              additionalProperties: true
  securitySchemes:
    IbApiKey:
      type: apiKey
      in: header
      name: x-ib-api-key
      description: API key emitida por Insurance Boosters.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.