WhatsApp - seven.io API

Utilice esta API para enviar mensajes de WhatsApp a través de la API de WhatsApp Business (WABA). Puede enviar mensajes de plantilla, mensajes de texto libre, medios (imagen, vídeo, audio, documento, sticker), ubicaciones, contactos y mensajes interactivos. Las reacciones se envían a través del punto final de eventos.

Para utilizar este punto final, su clave API debe tener el alcance waba habilitado. También necesita un número de remitente de WhatsApp Business registrado.

POST/api/waba/messages

Enviar mensaje

Envíe un mensaje de WhatsApp a un destinatario. Puede enviar mensajes de plantilla, mensajes de texto libre, medios (imagen, vídeo, audio, documento, sticker), ubicaciones, contactos y mensajes interactivos (botones, listas).

Parámetros obligatorios

Name
from
Type
string
Description
Su número de remitente de WhatsApp Business registrado en formato internacional (ej. 4915112345678).
Name
to
Type
string
Description
Número de teléfono del destinatario en formato internacional (ej. 4917612345678).

Parámetros de mensaje de plantilla

Name
type
Type
string
Description
Establezca template para enviar un mensaje de plantilla de WhatsApp pre-aprobado.
Name
template
Type
string
Description
El nombre de la plantilla de WhatsApp aprobada (ej. hello_world).
Name
language
Type
string
Description
Código de idioma de la plantilla (ej. de, en, es).
Name
components
Type
object
Optional
Optional
Description
Valores de parámetros de la plantilla. Contiene arrays opcionales para header, body y buttons. Los valores son posicionales y reemplazan {{1}}, {{2}}, etc. en la plantilla.

components

object

Parámetros de componentes de la plantilla

Name
header
Type
array
Optional
Optional
Description
Valores para los marcadores de posición del encabezado. Para encabezados de texto, proporcione cadenas. Para encabezados de imagen, proporcione una URL.
Name
body
Type
array
Optional
Optional
Description
Valores para los marcadores de posición del cuerpo. Cada entrada reemplaza la variable {{n}} correspondiente.
Name
buttons
Type
array
Optional
Optional
Description
Valores de parámetros de botones. Cada entrada es un objeto con type, sub_type y parameters.

Parámetros de mensaje de texto libre

Name
type
Type
string
Description
Establezca text u omítalo. El texto del mensaje se envía dentro de una ventana de conversación de 24 horas.
Name
text
Type
string
Description
El texto del mensaje. Solo puede enviarse dentro de una ventana de conversación activa de 24 horas.

Parámetros de mensaje de imagen

Name
type
Type
string
Description
Establezca image.
Name
url
Type
string
Description
URL pública del archivo de imagen (JPEG, PNG).
Name
caption
Type
string
Optional
Optional
Description
Leyenda opcional para la imagen.

Parámetros de mensaje de vídeo

Name
type
Type
string
Description
Establezca video.
Name
url
Type
string
Description
URL pública del archivo de vídeo (MP4, 3GPP).
Name
caption
Type
string
Optional
Optional
Description
Leyenda opcional para el vídeo.

Parámetros de mensaje de audio

Name
type
Type
string
Description
Establezca audio.
Name
url
Type
string
Description
URL pública del archivo de audio (MP3, OGG, AMR, AAC).

Parámetros de mensaje de documento

Name
type
Type
string
Description
Establezca document.
Name
url
Type
string
Description
URL pública del archivo de documento (PDF, DOC, etc.).
Name
filename
Type
string
Description
El nombre de archivo mostrado al destinatario.
Name
caption
Type
string
Optional
Optional
Description
Leyenda opcional para el documento.

Parámetros de mensaje de sticker

Name
type
Type
string
Description
Establezca sticker.
Name
url
Type
string
Description
URL pública del archivo de sticker (WebP). Stickers estáticos: 512x512px, máx. 100KB. Stickers animados: 512x512px, máx. 500KB.

Parámetros de mensaje de ubicación

Name
type
Type
string
Description
Establezca location.
Name
latitude
Type
number
Description
Latitud de la ubicación.
Name
longitude
Type
number
Description
Longitud de la ubicación.
Name
name
Type
string
Optional
Optional
Description
Nombre de la ubicación.
Name
address
Type
string
Optional
Optional
Description
Dirección de la ubicación.

Parámetros de mensaje de contactos

Name
type
Type
string
Description
Establezca contacts.
Name
contacts
Type
array
Description
Array de objetos de contacto. Cada contacto debe tener un objeto name (con first_name y last_name opcional) y un array phones (cada uno con phone y type opcional: cell, main, iphone, home, work).

Parámetros de mensaje interactivo de botones

Name
type
Type
string
Description
Establezca interactive.
Name
interactive_type
Type
string
Description
Establezca button.
Name
body
Type
string
Description
Texto del cuerpo mostrado al usuario.
Name
buttons
Type
array
Description
Array de 2-3 objetos de botón, cada uno con id (identificador único) y title (texto de visualización, máx. 20 caracteres).
Name
header
Type
string
Optional
Optional
Description
Texto de encabezado opcional.
Name
footer
Type
string
Optional
Optional
Description
Texto de pie de página opcional.

Parámetros de mensaje interactivo de lista

Name
type
Type
string
Description
Establezca interactive.
Name
interactive_type
Type
string
Description
Establezca list.
Name
body
Type
string
Description
Texto del cuerpo mostrado al usuario.
Name
button_text
Type
string
Description
Texto mostrado en el botón de lista.
Name
sections
Type
array
Description
Array de objetos de sección, cada uno con title y rows (array de objetos de fila con id, title y description opcional).
Name
header
Type
string
Optional
Optional
Description
Texto de encabezado opcional.
Name
footer
Type
string
Optional
Optional
Description
Texto de pie de página opcional.

Parámetros opcionales

Name
delay
Type
timestamp
Optional
Optional
Description
Fecha/hora para envío programado. Formato: AAAA-MM-DD hh:mm:ss o marca de tiempo Unix.
Name
ttl
Type
integer
Optional
Optional
Description
Especifica el período de validez del mensaje en minutos. El valor predeterminado es 2880, es decir, 48 horas.
Name
label
Type
string
Optional
Optional
Description
Etiqueta personalizada para estadísticas. Máx. 100 caracteres, caracteres permitidos: a-z, A-Z, 0-9, .-_@.
Name
performance_tracking
Type
boolean
Optional
Optional
Description
Activar el seguimiento de clics y rendimiento para las URL encontradas en el texto del mensaje. Esto también activa el acortador de URL.
Name
foreign_id
Type
string
Optional
Optional
Description
Su propio ID para este mensaje. Se devuelve en los callbacks de informes de estado. Máx. 64 caracteres, caracteres permitidos: a-z, A-Z, 0-9, .-_@.

Mensaje de plantilla

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "template",
      "template": "hello_world",
      "language": "de"
    }'

Respuesta

{
    "success": "100",
    "total_price": 0.0735,
    "balance": 123.45,
    "debug": "false",
    "sms_type": "WA",
    "messages": [
        {
            "id": "12345678",
            "sender": "4915112345678",
            "recipient": "4917612345678",
            "text": "{\"type\":\"template\",\"template\":\"hello_world\",\"language\":\"de\",\"rendered\":{\"body\":\"Hallo Welt!\"}}",
            "encoding": "gsm",
            "label": null,
            "parts": 1,
            "udh": null,
            "is_binary": false,
            "price": 0.0735,
            "channel": "WA",
            "success": true,
            "error": null,
            "error_text": null
        }
    ]
}

Plantilla con parámetros

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "template",
      "template": "order_confirmation",
      "language": "de",
      "components": {
        "body": ["Max Mustermann", "ORD-12345"],
        "buttons": [
          {
            "type": "button",
            "sub_type": "url",
            "parameters": [{"type": "text", "text": "ORD-12345"}]
          }
        ]
      }
    }'

Mensaje de texto libre

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "text": "Gracias por su mensaje, nos ocuparemos de ello."
    }'

Mensaje de imagen

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "image",
      "url": "https://example.com/photo.jpg",
      "caption": "¡Mire esta imagen!"
    }'

Mensaje de vídeo

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "video",
      "url": "https://example.com/video.mp4",
      "caption": "Vea este vídeo"
    }'

Mensaje de audio

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "audio",
      "url": "https://example.com/audio.mp3"
    }'

Mensaje de documento

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "document",
      "url": "https://example.com/factura.pdf",
      "filename": "factura.pdf",
      "caption": "Su factura"
    }'

Mensaje de sticker

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "sticker",
      "url": "https://example.com/sticker.webp"
    }'

Mensaje de ubicación

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "location",
      "latitude": 48.8566,
      "longitude": 2.3522,
      "name": "Torre Eiffel",
      "address": "5 Avenue Anatole France, 75007 París"
    }'

Mensaje de contactos

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "contacts",
      "contacts": [
        {
          "name": {
            "first_name": "Juan",
            "last_name": "García"
          },
          "phones": [
            {
              "phone": "+34123456789"
            }
          ]
        }
      ]
    }'

Mensaje interactivo de botones

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "interactive",
      "interactive_type": "button",
      "header": "Soporte",
      "body": "¿Cómo podemos ayudarle?",
      "footer": "Toque un botón",
      "buttons": [
        {"id": "btn_ventas", "title": "Ventas"},
        {"id": "btn_soporte", "title": "Soporte"},
        {"id": "btn_otro", "title": "Otro"}
      ]
    }'

Mensaje interactivo de lista

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "interactive",
      "interactive_type": "list",
      "header": "Nuestros Productos",
      "body": "Explore nuestras categorías:",
      "footer": "Seleccione una opción",
      "button_text": "Ver opciones",
      "sections": [
        {
          "title": "Electrónica",
          "rows": [
            {"id": "smartphones", "title": "Smartphones", "description": "Últimos modelos"},
            {"id": "portatiles", "title": "Portátiles", "description": "Business & Gaming"}
          ]
        }
      ]
    }'

Componentes de plantilla

La estructura components admite tres arrays opcionales: header, body y buttons. Los valores son posicionales y reemplazan {{1}}, {{2}}, etc. en la plantilla.

Parámetros de encabezado

Encabezado de texto: Proporcione valores de cadena para los marcadores de posición
Encabezado de imagen: Proporcione una URL a la imagen

Parámetros del cuerpo

Proporcione valores de cadena que reemplacen {{1}}, {{2}}, etc. en el cuerpo de la plantilla.

Parámetros de botón

Para botones URL con sufijos dinámicos, proporcione un array de objetos de botón:

Name
type
Type
string
Description
Siempre button.
Name
sub_type
Type
string
Description
El tipo de botón, ej. url.
Name
parameters
Type
array
Description
Array de objetos de parámetros con propiedades type y text.

Encabezado + Cuerpo + Botones

{
    "from": "4915112345678",
    "to": "4917612345678",
    "type": "template",
    "template": "appointment_reminder",
    "language": "es",
    "components": {
        "header": ["Confirmación de cita"],
        "body": ["Max Mustermann", "15/02/2026", "14:00", "Dr. Schmidt"],
        "buttons": [
            {
                "type": "button",
                "sub_type": "url",
                "parameters": [{"type": "text", "text": "abc123"}]
            }
        ]
    }
}

Encabezado de imagen + Cuerpo

{
    "from": "4915112345678",
    "to": "4917612345678",
    "type": "template",
    "template": "product_available",
    "language": "es",
    "components": {
        "header": ["https://example.com/product.jpg"],
        "body": ["Premium Widget"]
    }
}

DELETE/api/waba/messages/{id}

Eliminar mensaje

Elimine un mensaje de WhatsApp programado antes de que se haya enviado.

Name
id
Type
string
Description
El ID del mensaje a eliminar. Se pasa como parámetro de ruta URL.

Los mensajes ya enviados no pueden eliminarse. WhatsApp no admite la revocación de mensajes.

Solicitud

DELETE

/api/waba/messages/{id}

curl -X DELETE https://gateway.seven.io/api/waba/messages/12345678 \
    -H "X-Api-Key: SU_CLAVE_API"

Respuesta (éxito)

{
    "success": true
}

Respuesta (ya enviado)

{
    "error_code": 400,
    "error_message": "Message already sent. WhatsApp does not support message revocation."
}

Respuesta (no encontrado)

{
    "code": 404,
    "message": "Page not found",
    "errors": []
}

POST/api/waba/events

Enviar evento

Envíe eventos de conversación como confirmaciones de lectura, indicadores de escritura o reacciones a un contacto de WhatsApp.

Los eventos solo pueden enviarse para mensajes de los últimos 7 días. Las conversaciones más antiguas ya no son elegibles para la entrega de eventos.

Al menos uno de los parámetros to o msg_id debe proporcionarse para identificar la conversación o mensaje objetivo.

Parámetros de evento de lectura/escritura

Name
from
Type
string
Description
Su número de remitente de WhatsApp Business registrado.
Name
to
Type
string
Optional
Optional
Description
Número de teléfono del destinatario en formato internacional. Al menos to o msg_id debe proporcionarse.
Name
event
Type
string
Description
El tipo de evento. Valores disponibles: read, is_typing.
Name
msg_id
Type
string
Optional
Optional
Description
ID de mensaje explícito para marcar como leído. Al menos to o msg_id debe proporcionarse.

Parámetros de evento de reacción

Name
event
Type
string
Description
Establezca reaction.
Name
msg_id
Type
string
Description
El ID del mensaje de WhatsApp al que reaccionar.
Name
emoji
Type
string
Description
El emoji para la reacción (ej. 👍). Envíe una cadena vacía para eliminar la reacción.

Confirmación de lectura

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "event": "read"
    }'

Indicador de escritura

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "event": "is_typing"
    }'

Reacción

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: SU_CLAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "event": "reaction",
      "msg_id": "123456789",
      "emoji": "👍"
    }'

Respuesta

{
    "success": true
}

Respuesta de error

{
    "success": false,
    "error_code": 400,
    "error_message": "Invalid WhatsApp sender number"
}

Respuestas de error

Name
100
Description
El mensaje ha sido aceptado por la pasarela y se está enviando.
Name
7002001
Description
Sin conversación activa. Los mensajes de texto libre solo pueden enviarse dentro de una ventana de conversación activa de 24 horas. Use un mensaje de plantilla para iniciar una conversación.
Name
400
Description
Solicitud inválida. Puede indicar un número de remitente inválido, número de destinatario inválido u otros errores de validación.
Name
404
Description
Mensaje no encontrado. El ID de mensaje especificado no existe o no pertenece a su cuenta.
Name
900
Description
La autenticación ha fallado. Verifique la clave API utilizada en Autenticación.
Name
902
Description
La clave API no tiene derechos de acceso a este punto final. Asegúrese de que el alcance waba esté habilitado.