# Wazend API - Documentación Completa

Wazend API es un wrapper de la API de WhatsApp (WAHA) que te permite enviar y recibir mensajes de WhatsApp mediante HTTP. Base URL y autenticación se obtienen desde el Dashboard.

## Introducción
Todos los endpoints de la API de Wazend empiezan con la URL de tu servidor (Base URL), que encuentras en tu Dashboard. Para consumir la API necesitas esa URL y una API Key, que también se crea desde el Dashboard. Desde el panel de sesiones puedes ajustar la configuración general, crear y gestionar API Keys, crear apps y compartir sesiones.

## Base URL
```
https://eu-central-1.wazend.net/
```

La URL del servidor aparece en tu Dashboard (panel de control).

## Autenticación
Todas las peticiones requieren el header:
```
X-Api-Key: TU_API_KEY
```

Las API Keys se crean desde el panel de Wazend con alcance limitado por sesión.

## Formato de chatId
- Usuarios: `5215551234567@c.us` (número internacional sin +)
- Grupos: `123456789@g.us`
- Canales: `123456789@newsletter`
- Estados: `status@broadcast`

## Docs
- [Bienvenido a Wazend](https://portal.wazend.net/docs): API de mensajería WhatsApp para desarrolladores. Crea números virtuales, obtén credenciales y automatiza conversaciones en minutos.
- [Cómo evitar bloqueo](https://portal.wazend.net/docs/como-evitar-bloqueo): Guía para evitar bloqueos en WhatsApp al desarrollar bots: responde mensajes, evita el spam y procesa los mensajes de forma compatible con las políticas de WhatsApp.
- [Inicio rápido](https://portal.wazend.net/docs/introduccion): Conoce la URL del servidor (Base URL) y la API Key para consumir la API, y explora el panel de sesiones.
- [Sesiones](https://portal.wazend.net/docs/sesiones): Crea, configura y controla sesiones de WhatsApp: ciclo de vida, estados, QR, código de emparejamiento y eventos.
- [Enviar mensajes](https://portal.wazend.net/docs/mensajes): Envía texto, imágenes, audio, video, archivos, encuestas, ubicaciones, contactos, reacciones y más a través de WhatsApp.
- [Recibir mensajes](https://portal.wazend.net/docs/recibir-mensajes): Cómo recibir mensajes de WhatsApp: leer el historial y recibir mensajes en tiempo real mediante webhooks.
- [Eventos](https://portal.wazend.net/docs/eventos): Recibe eventos de WhatsApp en tiempo real con Webhooks y WebSockets: estructura del payload, HMAC, reintentos y lista completa de eventos.
- [Perfil](https://portal.wazend.net/docs/perfil): Gestiona el nombre, estado y foto de perfil de tu número de WhatsApp.
- [Proxy](https://portal.wazend.net/docs/proxy): Configura un proxy para evitar errores al escanear el QR de WhatsApp.
- [Encuestas](https://portal.wazend.net/docs/polls): Envía encuestas y recibe votos en WhatsApp.
- [Chats](https://portal.wazend.net/docs/chats): Lista chats, obtén historial de mensajes y gestiona mensajes (editar, eliminar).
- [Contactos](https://portal.wazend.net/docs/contactos): Lista tus contactos de WhatsApp y verifica si un número tiene WhatsApp.
- [Canales](https://portal.wazend.net/docs/canales): Gestiona canales de WhatsApp (Newsletter): listar, crear, buscar, eliminar y enviar mensajes a canales.
- [Estados](https://portal.wazend.net/docs/estados): Publica y gestiona estados de WhatsApp (Stories): texto, imagen, video y nota de voz.
- [Grupos](https://portal.wazend.net/docs/grupos): Obtén información de los grupos de WhatsApp donde participa tu número.
- [Etiquetas](https://portal.wazend.net/docs/etiquetas): Gestiona etiquetas de WhatsApp Business: crear, listar, actualizar, eliminar y asignar etiquetas a chats.
- [Presencia](https://portal.wazend.net/docs/presencia): Controla el estado online y los indicadores de escritura de tu número WhatsApp.
- [Mensajes de evento](https://portal.wazend.net/docs/event-message): Envía mensajes de evento de WhatsApp y recibe las respuestas de los asistentes.
- [Llamadas](https://portal.wazend.net/docs/llamadas): Gestiona llamadas de WhatsApp: rechazar llamadas y recibir eventos de llamadas entrantes.
- [Integración con Make](https://portal.wazend.net/docs/integraciones/make): Instala Wazend en Make y automatiza el envío de mensajes de WhatsApp en tus escenarios.
- [Integración con n8n](https://portal.wazend.net/docs/integraciones/n8n): Instala el nodo comunitario de Wazend en n8n y automatiza flujos de trabajo de WhatsApp.

## Endpoints

### Sesiones
- `POST /api/sessions` - Crear sesión
- `GET /api/sessions` - Listar sesiones
- `GET /api/sessions/{session}` - Obtener sesión
- `PUT /api/sessions/{session}` - Actualizar sesión
- `POST /api/sessions/{session}/start` - Iniciar sesión
- `POST /api/sessions/{session}/stop` - Detener sesión
- `POST /api/sessions/{session}/restart` - Reiniciar sesión
- `POST /api/sessions/{session}/logout` - Cerrar sesión
- `POST /api/{session}/auth/qr` - Obtener código QR
- `POST /api/{session}/auth/request-code` - Código de emparejamiento
- `GET /api/sessions/{session}/me` - Información del perfil

Configuración de sesión (body):
```json
{
  "name": "S0001",
  "config": {
    "webhooks": [{ "url": "https://tu-servidor.com/webhook", "events": ["message"] }],
    "proxy": { "server": "localhost:3128" },
    "metadata": { "user.id": "123" }
  }
}
```

### Enviar mensajes

#### POST /api/sendText
Envía un mensaje de texto.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "text": "¡Hola! ¿Cómo estás?"
}
```

Opcional: `reply_to` (responder), `mentions` (mencionar, `["all"]` para todos), `linkPreview` (vista previa de enlaces).

#### POST /api/sendImage
Envía una imagen (JPEG recomendado).

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "file": { "mimetype": "image/jpeg", "url": "https://ejemplo.com/foto.jpg", "filename": "foto.jpg" },
  "caption": "Mira esta foto"
}
```

#### POST /api/sendVoice
Envía una nota de voz (OGG/Opus). Usa `convert: true` para convertir automáticamente.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "file": { "mimetype": "audio/ogg; codecs=opus", "url": "https://ejemplo.com/audio.ogg" },
  "convert": false
}
```

#### POST /api/sendVideo
Envía un video. Usa `convert: true` para convertir a MP4.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "file": { "mimetype": "video/mp4", "url": "https://ejemplo.com/video.mp4" },
  "convert": false
}
```

#### POST /api/sendFile
Envía un archivo.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "file": { "mimetype": "application/pdf", "url": "https://ejemplo.com/documento.pdf", "filename": "documento.pdf" }
}
```

#### POST /api/sendSeen
Marca un chat como leído.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us"
}
```

#### POST /api/sendPoll
Envía una encuesta.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "poll": { "name": "¿Cómo estás?", "options": ["¡Genial!", "¡Bien!", "No tan bien"], "multipleAnswers": false }
}
```

#### POST /api/sendPollVote
Vota en una encuesta.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "pollMessageId": "false_5215551234567@c.us_AAAA",
  "pollServerId": null,
  "votes": ["¡Genial!"]
}
```

#### POST /api/sendList
Envía una lista interactiva.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "title": "Menú principal",
  "text": "Selecciona una opción",
  "buttonText": "Abrir menú",
  "sections": [{ "title": "Opciones", "rows": [{ "title": "Opción 1" }, { "title": "Opción 2" }] }]
}
```

#### POST /api/send/link-custom-preview
Envía un link con vista previa personalizada.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "title": "Título personalizado",
  "description": "Descripción del enlace",
  "url": "https://ejemplo.com",
  "imageUrl": "https://ejemplo.com/preview.jpg"
}
```

#### POST /api/forwardMessage
Reenvía un mensaje.

Body:
```json
{
  "session": "S0001",
  "messageId": "false_5215551234567@c.us_ABC123",
  "chatId": "5215559876543@c.us"
}
```

#### POST /api/reaction
Reacciona a un mensaje.

Body:
```json
{
  "session": "S0001",
  "messageId": "false_5215551234567@c.us_ABC123",
  "chatId": "5215551234567@c.us",
  "reaction": "👍"
}
```

#### POST /api/star
Destaca un mensaje.

Body:
```json
{
  "session": "S0001",
  "messageId": "false_5215551234567@c.us_ABC123",
  "chatId": "5215551234567@c.us",
  "star": true
}
```

#### POST /api/sendContactVcard
Envía un contacto.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "contacts": [{ "fullName": "Juan Pérez", "phoneNumber": "+5215551234567" }]
}
```

#### POST /api/sendLocation
Envía una ubicación.

Body:
```json
{
  "session": "S0001",
  "chatId": "5215551234567@c.us",
  "lat": 19.4326,
  "lng": -99.1332,
  "title": "Ciudad de México"
}
```

#### POST /api/{session}/media/convert/voice y /api/{session}/media/convert/video
Convierte audio a OGG/Opus y video a MP4. Body: `{ "url": "https://ejemplo.com/audio.mp3" }`.

#### POST /api/startTyping / POST /api/stopTyping
Indicador de escritura. Body: `{ "session": "S0001", "chatId": "5215551234567@c.us" }`.

### Chats
- `GET /api/{session}/chats?limit=100&offset=0` - Listar chats
- `POST /api/{session}/chats/overview` - Resumen de chats. Body: `{ "pagination": { "limit": 20, "offset": 0 }, "filter": { "ids": ["5215551234567@c.us"] } }`
- `GET /api/{session}/chats/{chatId}/picture` - Foto del chat
- `POST /api/{session}/chats/{chatId}/archive` / `unarchive` / `unread` - Archivar, desarchivar, marcar no leído
- `DELETE /api/{session}/chats/{chatId}` - Eliminar chat
- `POST /api/{session}/chats/{chatId}/messages/read` - Marcar leídos. Body: `{ "messages": 30, "days": 7 }` o `{ "ids": ["..."] }`
- `GET /api/{session}/chats/{chatId}/messages?limit=10` - Obtener mensajes
- `GET /api/{session}/chats/{chatId}/messages/{messageId}` - Obtener mensaje
- `POST /api/{session}/chats/{chatId}/messages/{messageId}/pin` - Fijar. Body: `{ "duration": 86400 }`
- `PUT /api/{session}/chats/{chatId}/messages/{messageId}` - Editar. Body: `{ "text": "Mensaje editado" }`
- `DELETE /api/{session}/chats/{chatId}/messages/{messageId}` - Eliminar mensaje
- `DELETE /api/{session}/chats/{chatId}/messages` - Eliminar todos los mensajes

### Contactos
- `GET /api/contacts/all?session=S0001` - Listar contactos
- `GET /api/contacts?contactId=5215551234567&session=S0001` - Obtener contacto
- `PUT /api/{session}/contacts/{chatId}` - Actualizar contacto. Body: `{ "firstName": "Juan", "lastName": "Pérez" }`
- `GET /api/contacts/check-exists?phone=5215551234567&session=S0001` - Verificar si el número tiene WhatsApp
- `GET /api/contacts/about?contactId=...&session=S0001` - Obtener estado (about)
- `GET /api/contacts/profile-picture?contactId=...&session=S0001` - Foto de perfil
- `POST /api/contacts/block` / `unblock` - Bloquear/desbloquear. Body: `{ "contactId": "5215551234567", "session": "S0001" }`
- `GET /api/{session}/lids` - LIDs conocidos

### Grupos
- `POST /api/{session}/groups` - Crear grupo. Body: `{ "name": "Mi grupo", "participants": [{ "id": "5215551234567@c.us" }] }`
- `GET /api/{session}/groups?limit=20&offset=0` - Listar grupos
- `GET /api/{session}/groups/count` - Número de grupos
- `POST /api/{session}/groups/join` - Unirse. Body: `{ "code": "https://chat.whatsapp.com/INVITECODE" }`
- `GET /api/{session}/groups/join-info?code=...` - Info de invitación
- `POST /api/{session}/groups/refresh` - Refrescar grupos
- `GET/DELETE /api/{session}/groups/{groupId}` - Obtener/eliminar grupo
- `POST /api/{session}/groups/{groupId}/leave` - Salir del grupo
- `GET/PUT/DELETE /api/{session}/groups/{groupId}/picture` - Foto del grupo
- `PUT /api/{session}/groups/{groupId}/subject` - Cambiar asunto. Body: `{ "subject": "Nuevo asunto" }`
- `PUT /api/{session}/groups/{groupId}/description` - Cambiar descripción. Body: `{ "description": "Nueva descripción" }`
- `PUT /api/{session}/groups/{groupId}/settings/security/info-admin-only` y `messages-admin-only` - Body: `{ "adminsOnly": true }`
- `PUT /api/{session}/groups/{groupId}/settings/security/member-add-mode` - Body: `{ "membersCanAddNewMember": true }`
- `GET /api/{session}/groups/{groupId}/participants` - Participantes
- `POST /api/{session}/groups/{groupId}/participants/add` y `remove` - Body: `{ "participants": [{ "id": "5215551234567@c.us" }] }`
- `POST /api/{session}/groups/{groupId}/admin/promote` y `demote` - Body: `{ "participants": [{ "id": "5215551234567@c.us" }] }`
- `GET /api/{session}/groups/{groupId}/invite-code` y `POST .../invite-code/revoke` - Código de invitación

### Canales
- `GET /api/{session}/channels?role=OWNER` - Listar canales
- `POST /api/{session}/channels` - Crear canal. Body: `{ "name": "Mi Canal", "description": "Descripción", "picture": { "url": "https://ejemplo.com/portada.jpg" } }`
- `GET /api/{session}/channels/{id}` - Obtener canal
- `POST /api/{session}/channels/search/by-text` - Buscar canales. Body: `{ "text": "noticias", "categories": [], "limit": 20, "startCursor": null }`
- `DELETE /api/{session}/channels/{id}` - Eliminar canal

### Estados (Stories)
- `POST /api/{session}/status/text` - Body: `{ "text": "¡Novedades!", "backgroundColor": "#000000", "font": 0 }`
- `POST /api/{session}/status/image` - Body: `{ "file": { "url": "https://ejemplo.com/foto.jpg" }, "caption": "Mira esta foto" }`
- `POST /api/{session}/status/video` - Body: `{ "file": { "url": "https://ejemplo.com/video.mp4" } }`
- `POST /api/{session}/status/voice` - Body: `{ "file": { "url": "https://ejemplo.com/audio.ogg" } }`
- `POST /api/{session}/status/delete` - Body: `{ "id": "id-del-estado" }`

### Etiquetas
- `GET /api/{session}/labels` - Listar etiquetas
- `POST /api/{session}/labels` - Crear. Body: `{ "name": "Cliente VIP", "color": 1 }`
- `PUT /api/{session}/labels/{labelId}` - Actualizar
- `DELETE /api/{session}/labels/{labelId}` - Eliminar
- `PUT /api/{session}/labels/chats/{chatId}` - Asignar/quitar etiquetas. Body: `{ "labels": [{ "id": "1" }] }`

### Perfil
- `GET /api/{session}/profile` - Obtener perfil
- `PUT /api/{session}/profile/name` - Body: `{ "name": "Nuevo Nombre" }`
- `PUT /api/{session}/profile/status` - Body: `{ "status": "Disponible por WhatsApp API" }`
- `PUT /api/{session}/profile/picture` - Body: `{ "file": { "url": "https://ejemplo.com/foto.jpg" } }` o `{ "file": { "data": "BASE64" } }`
- `DELETE /api/{session}/profile/picture` - Eliminar foto

### Presencia
- `POST /api/{session}/presence` - Cambiar presencia. Body: `{ "chatId": "5215551234567@c.us", "presence": "typing" }`. Valores: `online`, `offline`, `typing`, `recording`, `paused`
- `GET /api/{session}/presence` - Presencia de todos los chats
- `GET /api/{session}/presence/{chatId}` - Presencia de un chat
- `POST /api/{session}/presence/{chatId}/subscribe` - Suscribirse a actualizaciones

### Llamadas
- `POST /api/{session}/calls/reject` - Rechazar llamada. Body: `{ "from": "5215551234567@c.us", "id": "id-de-la-llamada" }`

### Mensajes de evento
- `POST /api/{session}/events` - Enviar invitación a evento. Body:
```json
{
  "chatId": "5215551234567@c.us",
  "event": { "name": "Reunión de equipo", "description": "Revisión del proyecto", "startTime": "2026-09-01T10:00:00Z", "endTime": "2026-09-01T11:00:00Z" }
}
```

## Webhooks
Configura los webhooks por sesión en la configuración de la sesión:
```json
{
  "name": "S0001",
  "config": {
    "webhooks": [
      {
        "url": "https://tu-servidor.com/webhook",
        "events": ["message"],
        "hmac": { "key": "tu-clave-secreta" },
        "retries": { "policy": "constant", "delaySeconds": 2, "attempts": 15 },
        "customHeaders": [{ "name": "X-Mi-Header", "value": "Valor" }]
      }
    ]
  }
}
```

Politicas de reintento: `constant` (2, 2, 2), `linear` (2, 4, 6, 8), `exponential` (retroceso exponencial con jitter).

Headers del webhook: `X-Webhook-Request-Id`, `X-Webhook-Timestamp`, `X-Webhook-Hmac`, `X-Webhook-Hmac-Algorithm` (`sha512`). Valida siempre la firma HMAC para proteger tu endpoint.

Estructura del payload del evento:
```json
{
  "id": "evt_1111111111111111111111111111",
  "timestamp": 1741249702485,
  "event": "message",
  "session": "S0001",
  "metadata": { "user.id": "123", "user.email": "cliente@ejemplo.com" },
  "me": { "id": "5215551234567@c.us", "pushName": "Mi Nombre" },
  "payload": {},
  "environment": { "tier": "CORE", "version": "2023.10.12" },
  "engine": "NOWEB"
}
```

La `metadata` se envía al crear la sesión y se incluye en cada evento.

## Eventos
Lista completa de eventos (con payload en /docs/eventos):
- `session.status` - Cambio de estado de la sesión (incluye datos de Reachout Timelock y Message Capping)
- `engine.event` - Evento de bajo nivel del motor (debug)
- `message` - Mensaje entrante (texto, audio, archivos)
- `message.any` - Todos los mensajes, incluidos los tuyos
- `message.reaction` - Reacción a un mensaje
- `message.ack` - Confirmación de entrega, lectura o reproducción
- `message.ack.group` - Confirmación de un participante en un grupo
- `message.waiting` - Mensaje en espera
- `message.edited` - Mensaje editado
- `message.revoked` - Mensaje eliminado (revocado)
- `chat.archive` - Chat archivado o desarchivado
- `group.v2.join` - Te unes o te añaden a un grupo
- `group.v2.leave` - Sales o te quitan de un grupo
- `group.v2.participants` - Alguien entra, sale, es promovido o degradado
- `group.v2.update` - Se actualiza la información del grupo
- `presence.update` - Actualización de presencia
- `poll.vote` - Nuevos votos de encuesta
- `poll.vote.failed` - Voto de encuesta no descifrable
- `event.response` - Respuesta a un mensaje de evento (GOING, NOT_GOING, MAYBE)
- `event.response.failed` - Respuesta de evento no descifrable
- `label.upsert` - Etiqueta creada o actualizada
- `label.deleted` - Etiqueta eliminada
- `label.chat.added` - Etiqueta añadida a un chat
- `label.chat.deleted` - Etiqueta quitada de un chat
- `call.received` - Llamada entrante
- `call.accepted` - Llamada aceptada
- `call.rejected` - Llamada rechazada o terminada

Puedes recibir los eventos mediante Webhooks (HTTP POST) o WebSockets (`ws://tu-servidor.wazend.net/ws`).

## Configuración avanzada
- Proxy por sesión: `{ "proxy": { "server": "localhost:3128", "username": "usuario", "password": "contraseña" } }`
- Ignorar tipos de chat: `{ "ignore": { "status": true, "groups": false, "channels": true, "broadcast": true } }`
- Metadatos personalizados: `{ "metadata": { "user.id": "123", "user.email": "cliente@ejemplo.com" } }`
- Nombre del dispositivo: `{ "client": { "deviceName": "MyApp", "browserName": "Chrome" } }`
- Modo debug: `{ "debug": true }`
- Auto-inicio: `{ "start": false }`

Estas opciones se aplican al crear o actualizar una sesión (ver /docs/sesiones).