> ## Documentation Index > Fetch the complete documentation index at: https://docs.wtocrm.com/llms.txt > Use this file to discover all available pages before exploring further. # Envía mensajes con la API WhatsApp WTOCRM: curl y Node.js > Envía tu primer mensaje por la API WhatsApp con curl o Node.js. Consulta el endpoint REST, elige texto, archivos o plantillas y resuelve respuestas 401 y 429. **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](https://assets.wtocrm.com/blog/2026/send-whatsapp-message-api/cover-e5bfbefd61.webp) 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](https://docs.wtocrm.com/es/waapi/create-instance.md), [conecta mediante QR o código de vinculación](https://docs.wtocrm.com/es/waapi/connect-instance.md) y confirma que `instance.state` es `open` con el [endpoint de estado de conexión](https://docs.wtocrm.com/es/waapi/get-connection-state.md). 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](https://nodejs.org/docs/latest-v22.x/api/globals.html#fetch). Conserva las credenciales en el backend. Define estas variables en la terminal que ejecutará el ejemplo, sustituyendo los tres valores: ```bash theme={null} 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](https://docs.wtocrm.com/es/waapi/send-text-message.md) define esta estructura: ```bash theme={null} 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: ```javascript theme={null} 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](https://wtocrm.com) 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](https://docs.wtocrm.com/es/waapi/send-media-message.md) exige `number`, `mediatype` y un archivo binario en `media`. Para un PDF que tú prepares como `quote.pdf` en el directorio actual: ```bash theme={null} 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](https://docs.wtocrm.com/es/waapi/send-template-message.md), 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](https://docs.wtocrm.com/es/user-guides/channels/whatsapp-setup.md). 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/?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](https://www.rfc-editor.org/rfc/rfc6585.html#section-4) 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](https://docs.wtocrm.com/es/waapi/set-webhook.md) 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](https://docs.wtocrm.com/es/waapi/connect-instance.md)** para conectar tu instancia, confirmar `open` y ejecutar tu primera petición de texto. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.