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

> Envía una imagen 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 una imagen desde una de tus líneas de WhatsApp. El texto de `caption` aparece debajo de la imagen.

## Endpoint

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

## Parámetro de ruta

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

## Body

A diferencia de documento y video, los campos de la imagen van al nivel raíz del body.

| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `to` | `string` | Sí | Teléfono destino en E.164, solo dígitos y sin `+`. |
| `imageUrl` | `string` | Sí | URL pública (HTTPS) de la imagen. |
| `caption` | `string` | No | Texto debajo de la imagen. Máximo 1,024 caracteres. |

## Formatos y tamaño

JPEG y PNG. Tamaño máximo: 5 MB.

## Ejemplo

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

Para enviar solo la imagen, 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 imagen en el header](https://developers.insuranceboosters.com/whatsapp/enviar-plantilla/header-imagen.md).

## Errores frecuentes

| HTTP | Qué significa | Qué hacer |
| - | - | - |
| `400` | Falta `to` o `imageUrl`. | 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 la imagen sea JPEG o PNG de máximo 5 MB. |


## OpenAPI

````yaml openapi/whatsapp-v1.json POST /whatsapp/{phoneNumberId}/image
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}/image:
    post:
      tags:
        - WhatsApp
      summary: Enviar imagen con texto
      description: >-
        Envía una imagen JPEG o PNG con un texto opcional debajo de la imagen.


        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: sendWhatsAppImage
      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/SendImageRequest'
            example:
              to: ''
              imageUrl: https://tu-dominio.com/imagen.png
              caption: Esta es tu credencial.
      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:
    SendImageRequest:
      type: object
      required:
        - to
        - imageUrl
      properties:
        to:
          type: string
          description: >-
            Teléfono del destinatario en formato E.164 (solo dígitos, sin `+`).
            Ejemplo México: 5215512345678.
          x-default: ''
        imageUrl:
          type: string
          format: uri
          description: URL pública (HTTPS) de la imagen JPEG o PNG.
        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.