Envía mensajes con la API WhatsApp WTOCRM: curl y Node.js

Para enviar un mensaje de WhatsApp con WTOCRM, haz un POST con el número de destino y textMessage.text a https://waapi.wtocrm.com/message/sendText/{instanceName}, incluyendo el encabezado apikey. Los ejemplos utilizan tu backend y una instancia que ya está conectada. No necesitas un SDK. Empieza aquí si añades avisos para clientes a tu SaaS o desarrollas una automatización para otra empresa. Primero comprueba que un mensaje llega a tu propio teléfono de prueba. Después añade archivos, notificaciones de eventos y reintentos controlados.

Puntos clave

Envía texto con un POST JSON a /message/sendText/{instanceName} y autentica con apikey.

Crea y conecta la instancia antes. Un QR o código de vinculación no confirma la conexión.

Subir archivos, usar plantillas comerciales aprobadas y abrir enlaces wa.me son tareas diferentes.

Corrige las credenciales ante un 401; revisa la respuesta y reduce la presión de peticiones ante un 429. Comprueba los envíos de resultado incierto antes de repetir.

Módulo de backend, puerta de enlace translúcida y teléfono conectados por una ruta de mensaje en una ilustración conceptual — Ilustración conceptual de un backend que envía un mensaje por una puerta de enlace de API a un teléfono; no es una captura del producto.

Envía tu primer mensaje de texto con curl o Node.js

Antes de ejecutar los ejemplos, crea una instancia, conecta mediante QR o código de vinculación y confirma que instance.state es open con el endpoint de estado de conexión. Estos pasos describen el acceso por protocolo de dispositivo vinculado de WTOCRM, separado del alta oficial en WhatsApp Business Platform / Cloud API de Meta. Utiliza una terminal con curl o Node.js 22 o posterior para el ejemplo de JavaScript. Node incluye fetch nativo. Conserva las credenciales en el backend. Define estas variables en la terminal que ejecutará el ejemplo, sustituyendo los tres valores:

export WTO_API_KEY='YOUR_API_KEY'
export WTO_INSTANCE='YOUR_CONNECTED_INSTANCE'
export WTO_TO='COUNTRY_CODE_AND_YOUR_TEST_NUMBER'

Introduce tu propio número de prueba de WhatsApp con código de país y solo dígitos, sin +, espacios ni puntuación. Las variables configuran los ejemplos; no crean ni conectan una instancia. En una aplicación en producción, proporciona la clave mediante tu sistema habitual de gestión de secretos.

curl: una petición POST

La referencia de envío de texto define esta estructura:

curl --request POST "https://waapi.wtocrm.com/message/sendText/${WTO_INSTANCE}" \
  --header "apikey: ${WTO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data "{\"number\":\"${WTO_TO}\",\"textMessage\":{\"text\":\"WTOCRM API test\"}}"

Después de preparar la conexión, esta es la petición mínima para enviar el texto fijo de prueba. La referencia documenta HTTP 200 y los campos de respuesta key, message y status. Examina el resultado real y comprueba el teléfono receptor: una respuesta de la API no demuestra la entrega final.

Node.js: fetch nativo, sin SDK

Guarda el código como send-message.mjs y ejecuta node send-message.mjs desde la terminal configurada:

const response = await fetch(`https://waapi.wtocrm.com/message/sendText/${encodeURIComponent(process.env.WTO_INSTANCE)}`, {
  method: 'POST',
  headers: { apikey: process.env.WTO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ number: process.env.WTO_TO, textMessage: { text: 'WTOCRM API test' } })
});
const body = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`);
console.log(body);

fetch no lanza una excepción solo porque el servidor devuelve 401 o 429. La comprobación explícita de response.ok convierte esas respuestas en errores que puedes gestionar. Durante el diagnóstico, conserva la respuesta completa en un registro de desarrollo restringido; elimina credenciales, números y contenido de mensajes antes de compartir registros.

Entiende el endpoint REST y la URL

Un endpoint identifica una operación mediante su método HTTP y su URL. Para enviar texto con WTOCRM, combina estas partes:

Parte	Valor	Función
Método	`POST`	Presentar una operación de mensaje
URL base de la API	`https://waapi.wtocrm.com`	Acceder al servicio WTO WA API
Ruta	`/message/sendText/{instanceName}`	Elegir el envío de texto para una instancia
Autenticación	Encabezado `apikey`	Proporcionar una clave autorizada para la instancia
Cuerpo JSON	`number`, `textMessage.text`	Definir destinatario y mensaje

Sustituye {instanceName}; no envíes las llaves literalmente. Usa el nombre de la instancia, no el número del destinatario. Abrir la URL en el navegador suele generar un GET sin el encabezado ni el cuerpo JSON necesarios, y no ejecuta esta operación POST. Esta URL y esta estructura corresponden a WTOCRM. No las mezcles con ejemplos de token Bearer, rutas de Graph API o campos de otros proveedores. WTOCRM publica esta guía; las referencias de producto enlazadas definen los contratos actuales de las peticiones. Cómo comprobamos los ejemplos: el 3 de noviembre de 2026 comprobamos los fragmentos de curl y Node.js con un servicio HTTP simulado localmente y Node.js v24.22.2. Las pruebas cubrieron rutas, apikey, JSON de texto, carga multipart y el tratamiento de HTTP 200/401/429 en Node. No enviamos mensajes reales por WhatsApp.

Elige texto, archivos multimedia o plantillas

Elige el formato según el contenido y el canal conectado, en vez de cambiar de endpoint hasta obtener una respuesta.

Tipo	Cuándo elegirlo	Referencia WTOCRM	Qué comprobar primero
Texto	Una respuesta de texto o mensaje de prueba	`/message/sendText/{instanceName}`	Instancia conectada y campos JSON documentados
Multimedia	PDF de cotización, imagen, vídeo o audio	`/message/sendMedia/{instanceName}`	Formato de carga y tipo de archivo
Plantilla	Notificación comercial en un canal que exige plantillas aprobadas	`/message/sendTemplate/{instanceName}`	Compatibilidad del canal, aprobación y parámetros del proveedor

Sube archivos mediante un formulario multipart

La referencia actual de mensajes multimedia exige number, mediatype y un archivo binario en media. Para un PDF que tú prepares como quote.pdf en el directorio actual:

curl --request POST "https://waapi.wtocrm.com/message/sendMedia/${WTO_INSTANCE}" \
  --header "apikey: ${WTO_API_KEY}" \
  --form "number=${WTO_TO}" \
  --form 'mediatype=document' \
  --form 'media=@./quote.pdf;type=application/pdf'

Deja que curl establezca el delimitador multipart. No reutilices Content-Type: application/json del ejemplo de texto. Los tipos documentados son image, video, audio y document; también están disponibles los campos opcionales caption y fileName. El ejemplo sube tu archivo local, sin suponer que media acepte una URL remota.

Confirma la compatibilidad con plantillas antes de implementar

Una plantilla comercial aprobada es diferente de un texto reutilizable guardado en tu aplicación. Usa plantillas cuando el canal comercial elegido exija ese formato aprobado para la notificación que quieras enviar. Un enlace wa.me o una petición de texto normal no sustituye la aprobación de una plantilla. WTOCRM incluye un endpoint de mensajes de plantilla, pero su contrato público actual muestra number y textMessage.text sin definir el nombre, el idioma o el mapeo de componentes de una plantilla aprobada. Tampoco especifica qué modos de conexión admiten la operación. Confirma el canal y los parámetros antes de implementarla; cambiar sendText por sendTemplate no es una conversión verificada. Para configurar el canal oficial Cloud API de WTOCRM, sigue la configuración independiente del canal WhatsApp. No supongas que la instancia vinculada por QR de este ejemplo tenga el mismo flujo ni las mismas capacidades de plantillas.

Distingue tres significados de enlace de la API WhatsApp

“Enlace de la API WhatsApp” puede referirse a tres destinos. Identifica quién abre el enlace y qué acción debe realizar.

Significado	Ejemplo o destino	Qué hace
Endpoint REST	`https://waapi.wtocrm.com/message/sendText/{instanceName}`	Tu backend envía una petición estructurada de mensaje
Enlace para iniciar un chat	`https://wa.me/<international-number>?text=<encoded-text>`	Una persona abre el chat con texto opcional predefinido y decide si lo envía
Entrada de vinculación de cuenta o canal	Guía de conexión o configuración de canales de WTOCRM	La persona responsable vincula un dispositivo o autoriza el canal elegido

Para un enlace wa.me, utiliza el número internacional completo sin + ni puntuación y codifica el texto opcional para URL. El enlace no autentica tu backend ni envía un mensaje automáticamente. Para vincular dispositivos, GET /instance/connect/{instanceName} solicita la información del QR o del código de vinculación; la persona responsable todavía debe completar el paso en el teléfono. Un enlace de vinculación de canal es una entrada de configuración, no una URL universal de envío. Protege los QR y códigos de acceso y sigue el flujo documentado.

Resuelve 401 y 429 sin duplicar mensajes

Empieza registrando el estado HTTP, los encabezados y el cuerpo de respuesta. Durante el diagnóstico, añade --include a la petición curl anterior; en Node, examina response.status, response.headers y body. Elimina datos personales antes de compartir el registro.

401: corrige la autenticación antes de reintentar

Las referencias de texto y multimedia de WTOCRM definen 401 como autenticación ausente o inválida. Comprueba que WTO_API_KEY esté definida, que el encabezado se llame apikey y que la clave pertenezca al entorno de destino y esté autorizada para la instancia. Si utilizas un proxy, verifica que reenvíe ese encabezado. La ausencia del nombre de instancia es un problema de ruta diferente. Estas referencias definen HTTP 403 como permisos insuficientes, mientras que 404 puede indicar una instancia desconocida. Repetir la misma petición sin autorización no corrige estos problemas.

429: reduce la presión y sigue la respuesta

HTTP 429 significa demasiadas peticiones durante un periodo. El estándar permite el encabezado Retry-After, pero no lo exige. Si el servicio lo proporciona, respeta la espera indicada. En caso contrario, utiliza esperas progresivas con límite máximo, variación aleatoria, un número finito de intentos y una cola que limite la concurrencia. Las referencias de envío de WTOCRM todavía no publican un contrato para 429 ni una cuota fija de peticiones por segundo. Esta es una pauta general para un 429 devuelto por la ruta real de la API, una puerta de enlace o el proveedor. Examina cuerpo y encabezados para identificar el origen; no importes límites numéricos de otros proveedores ni supongas que repetir elude una restricción de cuenta. Si desarrollas automatizaciones para clientes, coordina los procesos que comparten una cuenta o cuota de servicio. Los procesos independientes que reintentan a la vez pueden mantener la presión elevada. Conserva la identidad de la tarea original y detén los reintentos al agotar el presupuesto configurado.

Separa datos incorrectos, tiempos de espera y problemas de entrega

Resultado	Próxima acción
`400`	Compara cuerpo, formato del número y campos multimedia con la referencia
`403`	Revisa permisos de la clave; no lo trates como límite temporal
`404`	Comprueba URL base, ruta y nombre de instancia
Tiempo de espera agotado o respuesta perdida	Determina si el envío terminó antes de presentarlo de nuevo
Respuesta correcta, mensaje ausente en el teléfono	Revisa la conexión y los eventos disponibles; registra el resultado real

No supongas que existe un encabezado de idempotencia: las referencias actuales de envío no lo documentan. Tu aplicación debe registrar tareas y los identificadores de mensaje devueltos, cuando estén disponibles, y comprobar resultados inciertos antes de repetir. Un identificador local de tarea, por sí solo, no evita un segundo envío tras un fallo de red ambiguo.

Verifica un mensaje y conecta tu flujo

La primera prueba debe confirmar tres observaciones: respuesta de la API, mensaje recibido en el teléfono de prueba y una respuesta que llega a la aplicación. Utiliza la referencia de configuración de webhook para elegir eventos admitidos por la instancia y asociar la notificación con la instancia y el contacto correctos. Envía solo mensajes que los destinatarios hayan aceptado recibir. Separa fallos de conexión de fallos de autenticación y verifica los reintentos antes de añadir procesos o clientes. Abre la guía de conexión de la API WTOCRM para conectar tu instancia, confirmar open y ejecutar tu primera petición de texto.

​Envía tu primer mensaje de texto con curl o Node.js

​curl: una petición POST

​Node.js: fetch nativo, sin SDK

​Entiende el endpoint REST y la URL

​Elige texto, archivos multimedia o plantillas

​Sube archivos mediante un formulario multipart

​Confirma la compatibilidad con plantillas antes de implementar

​Distingue tres significados de enlace de la API WhatsApp

​Resuelve 401 y 429 sin duplicar mensajes

​401: corrige la autenticación antes de reintentar

​429: reduce la presión y sigue la respuesta

​Separa datos incorrectos, tiempos de espera y problemas de entrega

​Verifica un mensaje y conecta tu flujo