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

# Resumen de API

> Visión general de la API de Whaapy

# Resumen de API

La API de Whaapy te permite enviar mensajes de WhatsApp de forma programática. Está diseñada para ser **compatible con Meta WhatsApp Cloud API** mientras ofrece shortcuts que simplifican casos de uso comunes.

***

## Base URL

```
https://api.whaapy.com
```

Todas las rutas documentadas son relativas a esta URL base.

***

## Autenticación

Todas las requests requieren un header `Authorization` con tu API Key:

```http theme={null}
Authorization: Bearer wha_TU_API_KEY
Content-Type: application/json
```

Ver [Autenticación](/api-reference/authentication) para más detalles.

***

## Formato Híbrido

Nuestra API acepta **dos estilos** de request, dándote flexibilidad para usar el formato que prefieras:

<Tabs>
  <Tab title="Estilo Whaapy">
    Formato simplificado para casos comunes:

    ```json theme={null}
    {
      "to": "+5215512345678",
      "content": "Hola!"
    }
    ```
  </Tab>

  <Tab title="Estilo Meta">
    100% compatible con WhatsApp Cloud API:

    ```json theme={null}
    {
      "messaging_product": "whatsapp",
      "to": "+5215512345678",
      "type": "text",
      "text": { "body": "Hola!" }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  El estilo Whaapy es más corto y fácil de usar. El estilo Meta es útil si ya tienes código funcionando con la API oficial de WhatsApp.
</Tip>

***

## Endpoints Disponibles

### Mensajes

| Método | Endpoint                 | Descripción                     | Documentación                             |
| ------ | ------------------------ | ------------------------------- | ----------------------------------------- |
| `POST` | `/messages/v1`           | Envía cualquier tipo de mensaje | [Ver docs](/api-reference/messages/send)  |
| `POST` | `/messages/v1/:id/retry` | Reintenta un mensaje fallido    | [Ver docs](/api-reference/messages/retry) |

### Media

| Método | Endpoint    | Descripción              | Documentación                                 |
| ------ | ----------- | ------------------------ | --------------------------------------------- |
| `POST` | `/media/v1` | Sube archivos a Meta CDN | [Ver docs](/api-reference/media/upload-media) |

***

## Tipos de Mensaje Soportados

<CardGroup cols={4}>
  <Card title="text" icon="font" href="/api-reference/messages/send">
    Texto simple
  </Card>

  <Card title="image" icon="image" href="/api-reference/messages/send-media">
    JPEG, PNG, WebP
  </Card>

  <Card title="video" icon="video" href="/api-reference/messages/send-media">
    MP4 hasta 16MB
  </Card>

  <Card title="audio" icon="volume-high" href="/api-reference/messages/send-media">
    MP3, OGG, AAC
  </Card>

  <Card title="document" icon="file" href="/api-reference/messages/send-media">
    PDF, Word, Excel
  </Card>

  <Card title="sticker" icon="note-sticky" href="/api-reference/messages/send-media">
    WebP hasta 500KB
  </Card>

  <Card title="template" icon="table-layout" href="/api-reference/messages/send-templates">
    Pre-aprobados por Meta
  </Card>

  <Card title="interactive" icon="hand-pointer" href="/api-reference/messages/send-interactive">
    Botones y listas
  </Card>

  <Card title="location" icon="location-dot" href="/api-reference/messages/send-location">
    Coordenadas GPS
  </Card>

  <Card title="contacts" icon="address-book" href="/api-reference/messages/send-contacts">
    Tarjetas vCard
  </Card>

  <Card title="reaction" icon="face-smile" href="/api-reference/messages/send-reactions">
    Emojis en mensajes
  </Card>
</CardGroup>

***

## Códigos de Respuesta HTTP

| Código | Significado           | Descripción                       |
| ------ | --------------------- | --------------------------------- |
| `200`  | OK                    | Request exitoso                   |
| `400`  | Bad Request           | Error de validación en el request |
| `401`  | Unauthorized          | API Key inválida o faltante       |
| `403`  | Forbidden             | Sin permisos para este scope      |
| `404`  | Not Found             | Recurso no encontrado             |
| `429`  | Too Many Requests     | Rate limit excedido               |
| `500`  | Internal Server Error | Error interno del servidor        |

Ver [Códigos de Error](/api-reference/errors) para errores específicos de WhatsApp.

***

## Rate Limits

| Tipo                | Límite |
| ------------------- | ------ |
| Mensajes por minuto | 1,000  |
| Requests por minuto | 100    |

<Note>
  Los rate limits pueden variar según tu plan. Contacta soporte para límites personalizados.
</Note>

***

## Límites de Tamaño de Media

| Tipo       | Formatos                | Tamaño Máximo |
| ---------- | ----------------------- | ------------- |
| `image`    | JPEG, PNG, WebP         | 5 MB          |
| `video`    | MP4, 3GPP               | 16 MB         |
| `audio`    | AAC, MP3, OGG, AMR      | 16 MB         |
| `document` | PDF, DOC, XLS, PPT, TXT | 100 MB        |
| `sticker`  | WebP                    | 500 KB        |

***

## Ventana de 24 Horas

<Warning>
  WhatsApp tiene una regla de **ventana de 24 horas**: solo puedes enviar mensajes de texto libre a usuarios que te han escrito en las últimas 24 horas.
</Warning>

**Dentro de la ventana** (24h desde último mensaje del usuario):

* Puedes enviar cualquier tipo de mensaje
* Texto, imágenes, videos, interactivos, etc.

**Fuera de la ventana** (>24h sin respuesta):

* Solo puedes enviar **template messages** pre-aprobados por Meta
* Ver [Enviar Templates](/api-reference/messages/send-templates)

***

## Estructura de Respuesta Exitosa

Todas las respuestas exitosas siguen esta estructura:

```json theme={null}
{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "+5215512345678", "wa_id": "5215512345678" }
  ],
  "messages": [
    { "id": "uuid-whaapy", "wamid": "wamid.HBgLNTIxNTUx..." }
  ],
  "data": {
    "id": "uuid-del-mensaje",
    "conversationId": "uuid-de-conversacion",
    "messageType": "text",
    "direction": "outbound",
    "status": "sent",
    "createdAt": "2026-01-22T10:30:00Z"
  }
}
```

| Campo                 | Descripción                             |
| --------------------- | --------------------------------------- |
| `messaging_product`   | Siempre `"whatsapp"`                    |
| `contacts[].wa_id`    | ID de WhatsApp del destinatario         |
| `messages[].id`       | UUID del mensaje en Whaapy              |
| `messages[].wamid`    | ID del mensaje en Meta                  |
| `data.conversationId` | UUID de la conversación                 |
| `data.status`         | `sent`, `delivered`, `read`, o `failed` |

***

## Estructura de Respuesta de Error

```json theme={null}
{
  "error": "message_delivery_failed",
  "message": "Descripción legible del error",
  "code": "131047",
  "action_required": "Acción sugerida",
  "instructions": "Pasos detallados para resolver",
  "data": {
    "id": "uuid-del-mensaje",
    "status": "failed"
  }
}
```

Ver [Códigos de Error](/api-reference/errors) para la lista completa.

***

## SDKs y Ejemplos

Actualmente no tenemos SDKs oficiales, pero la API es simple de usar con cualquier cliente HTTP:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/messages/v1 \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"to": "+5215512345678", "content": "Hola!"}'
  ```

  ```javascript Node.js (fetch) theme={null}
  const response = await fetch('https://api.whaapy.com/messages/v1', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wha_TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+5215512345678',
      content: 'Hola!'
    })
  });
  ```

  ```python Python (requests) theme={null}
  import requests

  response = requests.post(
      'https://api.whaapy.com/messages/v1',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'to': '+5215512345678',
          'content': 'Hola!'
      }
  )
  ```

  ```php PHP (cURL) theme={null}
  $ch = curl_init('https://api.whaapy.com/messages/v1');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer wha_TU_API_KEY',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'to' => '+5215512345678',
      'content' => 'Hola!'
  ]));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  ```
</CodeGroup>

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Autenticación" icon="key" href="/api-reference/authentication">
    Configura tu API Key
  </Card>

  <Card title="Enviar Mensaje" icon="paper-plane" href="/api-reference/messages/send">
    Envía tu primer mensaje
  </Card>

  <Card title="Templates" icon="table-layout" href="/api-reference/messages/send-templates">
    Mensajes fuera de ventana 24h
  </Card>

  <Card title="Códigos de Error" icon="circle-exclamation" href="/api-reference/errors">
    Manejo de errores
  </Card>
</CardGroup>