> ## 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 video con texto

> Envía un video con un texto debajo en un solo mensaje de WhatsApp.

Guía de [Mensajes con archivo y texto](https://developers.insuranceboosters.com/whatsapp/mensajes-con-archivo)

Envía un video desde una de tus líneas de WhatsApp. El texto de `caption` aparece debajo del video.

## Endpoint

```text theme={null}
POST /whatsapp/{phoneNumberId}/video
```

## Parámetro de ruta

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

## Body

| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `to` | `string` | Sí | Teléfono destino en E.164, solo dígitos y sin `+`. |
| `video` | `object` | Sí | Archivo y texto a enviar. |
| `video.videoUrl` | `string` | Sí | URL pública (HTTPS) del video. |
| `video.caption` | `string` | No | Texto debajo del video. Máximo 1,024 caracteres. |

## Formatos y tamaño

MP4 y 3GP. Tamaño máximo: 16 MB.

## Ejemplo

```bash theme={null}
curl -X POST "https://api.insuranceboosters.com/api/v1/whatsapp/{phoneNumberId}/video" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "to": "<numero-e164>",
    "video": {
      "videoUrl": "https://tu-dominio.com/cobertura.mp4",
      "caption": "Mira cómo funciona tu cobertura."
    }
  }'
```

Para enviar solo el video, omite `caption`.

## Respuesta

```json theme={null}
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<numero-e164>",
      "wa_id": "<numero-e164>"
    }
  ],
  "messages": [
    {
      "id": "<id-del-mensaje>"
    }
  ]
}
```

> [!WARNING]
>
> Este mensaje solo se entrega si el cliente te escribió en las últimas 24 horas. Fuera de esa ventana, envía una [plantilla con video en el header](https://developers.insuranceboosters.com/whatsapp/enviar-plantilla/header-video.md).

## Errores frecuentes

| HTTP | Qué significa | Qué hacer |
| - | - | - |
| `400` | Falta `to` o `video.videoUrl`. | Completa los campos requeridos. |
| `401` | API key inválida o faltante. | Verifica `x-ib-api-key`. |
| `403` | La línea no pertenece a tu cuenta. | Confirma `phoneNumberId`. |
| `404` | La línea de WhatsApp no existe. | Confirma `phoneNumberId`. |
| `500` | No se pudo enviar el mensaje. | Verifica la ventana de 24 horas, que la URL sea pública y que el video sea MP4 o 3GP de máximo 16 MB. |


## OpenAPI

````yaml openapi/whatsapp-v1.json POST /whatsapp/{phoneNumberId}/video
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}/video:
    post:
      tags:
        - WhatsApp
      summary: Enviar video con texto
      description: >-
        Envía un video MP4 o 3GP con un texto opcional debajo del video.


        El mensaje solo se entrega dentro de las 24 horas posteriores al último
        mensaje del cliente. Fuera de esa ventana, envía una plantilla con
        archivo en el header.
      operationId: sendWhatsAppVideo
      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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendVideoRequest'
            example:
              to: ''
              video:
                videoUrl: https://tu-dominio.com/video.mp4
                caption: Mira cómo funciona tu cobertura.
      responses:
        '200':
          description: Mensaje enviado correctamente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMediaResponse'
        '400':
          description: 'Solicitud inválida: falta un campo requerido.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                error: Missing Recipient Phone Number (to).
        '401':
          description: API key inválida o faltante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                message: Invalid API key.
        '403':
          description: La línea de WhatsApp no pertenece a tu cuenta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                error: Phone line access denied
        '404':
          description: Línea de WhatsApp no encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                error: Phone line not found
        '500':
          description: >-
            No se pudo enviar el mensaje. Revisa la ventana de 24 horas, que la
            URL sea pública y que el archivo cumpla los requisitos; después
            reintenta o contacta soporte.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                error: Internal server error
components:
  schemas:
    SendVideoRequest:
      type: object
      required:
        - to
        - video
      properties:
        to:
          type: string
          description: >-
            Teléfono del destinatario en formato E.164 (solo dígitos, sin `+`).
            Ejemplo México: 5215512345678.
          x-default: ''
        video:
          type: object
          required:
            - videoUrl
          properties:
            videoUrl:
              type: string
              format: uri
              description: URL pública (HTTPS) del video MP4 o 3GP.
            caption:
              type: string
              description: >-
                Texto que acompaña al archivo. Máximo 1,024 caracteres. Si lo
                omites o lo envías vacío, se envía solo el archivo.
    SendMediaResponse:
      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
  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.