Enviar WhatsApp

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

post/whatsapp/send

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 individuales o transaccionales, no para envío masivo no solicitado. La instancia de WhatsApp (instance_id) debe estar conectada y operativa al momento del envío.

Autorización

apikeystringheaderrequerido

Cuerpo de la petición

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 o lógica de negocio. Códigos posibles: whatsapp_04 (instancia no definida), whatsapp_08 (instancia no encontrada), whatsapp_23 (número con formato incorrecto), whatsapp_28 (mensaje de más de 1000 caracteres), whatsapp_37 (URL multimedia inválida).

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

Código HTTP de la respuesta

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

Código HTTP

codestring

Código de error de autenticación (auth_01, auth_05, auth_06, auth_07, auth_99)

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

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error: auth_04 (IP no autorizada en whitelist)

429Demasiadas peticiones: Límite de rate limit excedido (100 mensajes/segundo producción, 1000 envíos de prueba por día en sandbox)

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error de rate limit

500Error interno del servidor

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error interno

request_idstring· uuid

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

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.