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

# Mensajes con archivo y texto

> Envía un documento, imagen o video con un texto debajo en un solo mensaje de WhatsApp.

Un mensaje con **archivo y texto** llega al cliente como un solo mensaje de WhatsApp: el archivo arriba y tu texto debajo, como pie del archivo. Se usa, por ejemplo, para enviar una póliza en PDF con un saludo o una credencial en imagen con instrucciones.

## Qué puedes enviar

| Tipo de archivo | Endpoint | Formatos | Tamaño máximo |
| - | - | - | - |
| [Documento](https://developers.insuranceboosters.com/whatsapp/enviar-documento.md) | `POST .../document` | PDF, Word, Excel, PowerPoint y TXT | 100 MB |
| [Imagen](https://developers.insuranceboosters.com/whatsapp/enviar-imagen.md) | `POST .../image` | JPEG y PNG | 5 MB |
| [Video](https://developers.insuranceboosters.com/whatsapp/enviar-video.md) | `POST .../video` | MP4 y 3GP | 16 MB |

Todos los endpoints usan la ruta `/whatsapp/{phoneNumberId}/`.

El texto es **opcional** y tiene un máximo de **1,024 caracteres**. Si no lo envías, el cliente recibe solo el archivo.

> [!NOTE]
>
> Los mensajes de audio no admiten texto. Si necesitas enviar audio y texto, mándalos como mensajes separados.

## Antes de enviar

**1. Configura tu API key**

Envía `x-ib-api-key` en cada solicitud. Consulta [Autenticación](https://developers.insuranceboosters.com/autenticacion.md).

**2. Verifica la ventana de 24 horas**

Los mensajes con archivo y texto solo se entregan si el cliente te escribió en las últimas 24 horas. Para iniciar una conversación o escribir fuera de esa ventana, usa una [plantilla aprobada](https://developers.insuranceboosters.com/whatsapp/plantillas) con archivo en el header.

**3. Publica el archivo en una URL pública**

El archivo debe estar disponible en una URL **HTTPS** accesible sin autenticación ni cookies. No se aceptan archivos en base64 ni cargas directas en esta solicitud.

**4. Elige el endpoint según el tipo de archivo**

Usa `/document`, `/image` o `/video` según la tabla anterior.

## Estructura del body

Los tres endpoints reciben `to` y la URL del archivo, pero la estructura cambia según el tipo. Revisa la guía del endpoint antes de armar el body.

| Tipo | Estructura | Campos del archivo |
| - | - | - |
| Documento | Objeto `document` | `documentUrl`, `filename`, `caption` |
| Imagen | Campos al nivel raíz | `imageUrl`, `caption` |
| Video | Objeto `video` | `videoUrl`, `caption` |

`to` es el teléfono del destinatario en formato E.164, solo dígitos y sin `+`.

## Ejemplos

```bash Documento theme={null}
curl -X POST "https://api.insuranceboosters.com/api/v1/whatsapp/{phoneNumberId}/document" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "to": "<numero-e164>",
    "document": {
      "documentUrl": "https://tu-dominio.com/poliza.pdf",
      "filename": "poliza.pdf",
      "caption": "Aquí está tu póliza."
    }
  }'
```

```bash Imagen theme={null}
curl -X POST "https://api.insuranceboosters.com/api/v1/whatsapp/{phoneNumberId}/image" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "to": "<numero-e164>",
    "imageUrl": "https://tu-dominio.com/credencial.png",
    "caption": "Esta es tu credencial."
  }'
```

```bash Video 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."
    }
  }'
```

## Respuesta

Los tres endpoints responden `200` con el identificador del mensaje en `messages[0].id`.

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

> [!TIP]
>
> Guarda `messages[0].id` para relacionar el envío con tu registro interno.

## Errores frecuentes

| HTTP | Qué significa | Qué hacer |
| - | - | - |
| `400` | Falta `to`, la URL del archivo o `filename` (documentos). | Compara el body con la estructura del endpoint. |
| `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. | Revisa que la conversación esté dentro de la ventana de 24 horas, que la URL sea pública y que el archivo cumpla formato y tamaño. Después reintenta o contacta soporte. |

> [card] [Enviar documento](https://developers.insuranceboosters.com/whatsapp/enviar-documento.md)
>
> PDF, Word, Excel, PowerPoint o TXT con texto.

> [card] [Enviar imagen](https://developers.insuranceboosters.com/whatsapp/enviar-imagen.md)
>
> Imagen JPEG o PNG con texto.

> [card] [Enviar video](https://developers.insuranceboosters.com/whatsapp/enviar-video.md)
>
> Video MP4 o 3GP con texto.


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