Enviar WhatsApp

Envía un mensaje de WhatsApp. Soporta texto, imagen, video, audio y documentos

post/whatsapp/send

Para códigos de verificación o 2FA no necesitas instancia: POST /v2/otp con channel: "whatsapp" envía por la integración oficial de SMS Masivos, sin instance_id ni cuenta de Meta, y la API genera y valida el código por ti.

Para los tipos multimedia (image, video, audio, document), el campo message contiene la URL del archivo. Esa URL debe usar HTTPS, ser accesible públicamente desde Internet sin autenticación y permanecer disponible mientras se procesa el envío. El caption agrega un texto descriptivo al medio.

Este canal es para mensajes transaccionales: uno a uno, derivados de una acción del usuario. Si disparas dos mensajes simultáneos, ya es masivo (promociones y cobranza incluidas) y WhatsApp puede restringir tu línea; para volumen usa SMS Masivos. La instancia de WhatsApp (instance_id) debe estar conectada y operativa al momento del envío; se conecta desde el panel escaneando un QR (guía).

Autorización

apikeystringheaderrequerido

Cuerpo de la solicitud

application/json

instance_idstringrequerido

Identificador de la instancia de WhatsApp vinculada a tu cuenta. La instancia debe existir y estar activa.

numberstringrequerido

Número de teléfono destino de 10 dígitos, sin código de país. Actualmente el envío está disponible para números de México (código de país 52).

messagestringrequerido

Contenido del mensaje (máximo 1000 caracteres). Para mensajes multimedia, es la URL pública HTTPS del archivo; la URL debe terminar con la extensión del archivo, sin parámetros adicionales.

typeenum

Tipo de mensaje. Extensiones aceptadas por tipo:

image: jpg, jpeg, png, svg, webp
video: mp4
audio: ogg, amr, 3gp, aac, mpeg
document: pdf, doc, docx, pptx, xlsx, xls, csv

enum:textimagevideoaudiodocument

country_codestring

Código de país (por defecto 52). Actualmente solo se admite 52 (México).

find_country_codeenum

Con valor 1, el código de país se extrae del propio número en lugar de tomarse de country_code.

enum:01

datestring

Fecha de programación para envío diferido (formato YYYY-MM-DD HH:MM:SS). Debe ser futura.

namestring

Nombre del contacto

captionstring

Texto que acompaña al archivo multimedia (imagen, video, audio o documento). Máximo 1000 caracteres. No aplica para mensajes de texto.

read_confirmationobject

Configuración de confirmación de lectura por URL.

▸ Ver atributos hijos▾ Ocultar atributos hijos

urlstring· uri

URL dentro del mensaje a la que se agrega un identificador de seguimiento.

contactinteger

Identificador de contacto a asociar (opcional).

Respuesta

200Operación exitosa

successboolean

messagestring

Mensaje de estado

statusinteger

codestring

Código de respuesta

creditnumber

Créditos consumidos

referencestring

ID de referencia del mensaje

idinteger

ID del mensaje (solo cuando show_id=1)

400Error de validación (whatsapp_04 instancia no definida, whatsapp_05 type inválido, whatsapp_06 mensaje no definido, whatsapp_07 número no definido, whatsapp_22 país inválido, whatsapp_23 número con formato incorrecto, whatsapp_24 fecha pasada, whatsapp_28/whatsapp_38 texto/caption de más de 1000 caracteres, whatsapp_29 formato de fecha, whatsapp_35 país no soportado, whatsapp_37 URL multimedia inválida). Si tu integración aún requiere el comportamiento anterior, envía el header X-Api-Http-Semantics: 0 y la respuesta llegará con HTTP 200 y el error en el cuerpo.

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

Campo legado dentro del cuerpo. Conserva su valor histórico (normalmente 200) y NO coincide con el status HTTP real: la respuesta puede llegar con HTTP 400/402/404/409/502 mientras este campo sigue en su valor legado. Usa el status HTTP de transporte y el code, no este campo.

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

401No autorizado: API Key no provista, inválida o expirada

successboolean

Siempre false

messagestring

Descripción del error de autenticación en español

statusinteger

Campo legado en el cuerpo. Es el status HTTP de transporte; para autenticación coincide con el status real (401). Usa el status HTTP y el code, no este campo.

codestring

Código de error de autenticación (auth_01, auth_03, auth_05)

402Saldo insuficiente para completar el envío (code: sms_07, contrato de compatibilidad).

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

403Prohibido: La dirección IP no está autorizada para acceder (IP whitelist)

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Campo legado en el cuerpo. Puede NO coincidir con el status HTTP real: para auth_06 y auth_07 este campo vale 401 (valor histórico congelado) mientras el status HTTP de transporte es 403. Usa el status HTTP y el code, no este campo.

codestring

Código de error: auth_04 (IP no autorizada), auth_06 (cuenta deshabilitada), auth_07 (admin inválido)

404La instancia de WhatsApp indicada no existe o está inactiva (code: whatsapp_08).

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

429Demasiadas peticiones. Límite propio de este endpoint contra envíos masivos por WhatsApp: máximo 1 envío cada 60 segundos (no aplica aquí el límite general de 100 mensajes/segundo del resto de la API). Al excederlo, la cuenta queda bloqueada 2 minutos con un cuerpo de error distinto al resto de la API (sin success ni code). Usa SMS para volumen.

errorbooleanrequerido

Siempre true

messagestringrequerido

Descripción del error

rate-limitedstringrequerido

Duración del bloqueo activo

reasonstringrequerido

Motivo del throttle

500Error interno del servidor. Códigos posibles: whatsapp_30/whatsapp_31/whatsapp_32 (resolución de servidor / confirmación de lectura / URLs de WhatsApp), whatsapp_36 (generación del mensaje), sms_12 (créditos), err_03 (inesperado).

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Campo legado dentro del cuerpo. Conserva su valor histórico (p.ej. 200 o 401 según el endpoint) y NO coincide con el status HTTP real (500). Usa el status HTTP de transporte y el code, no este campo.

codestring

Código de error interno (p.ej. server_01, o auth_99 en un error interno de autenticación)

request_idstring· uuid

Identificador único de la petición. Inclúyelo al contactar a soporte.

502La línea o proveedor de WhatsApp no está disponible aguas abajo (code: whatsapp_20). Reintenta con backoff.

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

Código	Cuándo ocurre	Qué hacer
`whatsapp_04` / `whatsapp_08`	`instance_id` ausente, o la instancia no existe o está inactiva.	Verifica el identificador y el estado de tu instancia en el panel.
`whatsapp_05` / `whatsapp_06` / `whatsapp_07`	`type`, `message` o `number` ausentes o inválidos.	Revisa los campos obligatorios.
`whatsapp_22` / `whatsapp_35`	Código de país ausente o no soportado.	Actualmente solo se admite México (`52`).
`whatsapp_23`	Número con formato incorrecto.	Envía 10 dígitos sin código de país.
`whatsapp_24` / `whatsapp_29`	Fecha programada en el pasado o con formato inválido.	Usa `YYYY-MM-DD HH:MM:SS` futuro.
`whatsapp_28` / `whatsapp_38`	`message` o `caption` de más de 1000 caracteres.	Acorta el texto.
`whatsapp_37`	URL multimedia inválida o con extensión no permitida.	La URL debe ser pública y terminar en la extensión del archivo, sin query string.
`sms_07`	Créditos insuficientes.	Consulta tu saldo con `/credits/consult`.

El éxito responde whatsapp_21.