API de envíos masivos por WhatsApp y Telegram

API de envíos masivos por WhatsApp y Telegram: conecta una cuenta, crea el envío y recibe los estados desde tu CRM o tu sitio web.

Los mensajes a clientes casi nunca son para «cuando haya tiempo». Hacen falta en el momento del evento: pagó su pedido, agendó una cita, no llegó, lleva un mes sin aparecer. El evento ya ocurrió en tu sistema, y entrar después al panel para armar el envío a mano no tiene mucho sentido.

Para eso existe la API pública. Por ella pasa el envío completo: la audiencia, la revisión del texto, un ritmo seguro, el estado de cada destinatario y su respuesta. No tienes que construir la cola, las pausas entre mensajes, los reintentos ni la protección del número contra bloqueos: de eso se encarga el servicio, y en tu sistema queda una sola llamada.

Además, el conjunto de métodos es el mismo para todo: cuentas de WhatsApp y Telegram, y bots de Telegram. Para pasar de WhatsApp a Telegram o a un bot no hace falta escribir una integración nueva: basta con cambiar un valor en la misma solicitud.

Qué hace la API de envíos masivos en WhatsApp y Telegram

Todo lo que haces a mano en el panel está disponible por HTTP:

• Conexión de cuentas y bots. Con una sola solicitud: la cuenta de mensajería se conecta con código QR o con número de teléfono, y el bot, con su token. El servicio te avisa el resultado de la conexión. Si la cuenta tiene contraseña de verificación en dos pasos, también se pasa por la API.
• Audiencia. Crear un segmento y cargar números de teléfono, hasta 100 números por solicitud; una lista más grande se carga en varias solicitudes. Los números que el proyecto ya conoce no se duplican.
• Envíos. Crear el envío, agregar texto o archivos (imagen, video, audio, documento; hasta diez mensajes por envío) y elegir a los destinatarios: un segmento de contactos, la agenda de la cuenta o los chats existentes. Después vienen la revisión del texto, el lanzamiento, la pausa y la cancelación.
• Edición del borrador. Mientras no lances el envío, con la misma API cambias el texto y los archivos de los mensajes, borras los que sobran y le cambias el nombre al envío. Editar el texto anula la revisión ya aprobada: para lanzarlo, el envío pasa otra vez por moderación.
• Resultado por cada destinatario. Enviado, entregado, leído, respondió, el número no está registrado en la plataforma.
• Respuestas de los destinatarios. No solo el hecho de que respondió, sino también el texto: qué escribió exactamente la persona en respuesta al envío.
• Envío de un solo mensaje. Para los casos transaccionales hay un método aparte: texto y adjunto propios en cada solicitud, sin armar un envío masivo para un único número.
• La conversación completa. El historial de la conversación con una persona: entrantes y salientes en un mismo hilo. Cuando llega un mensaje nuevo, el servicio avisa con un evento; puedes responder con el mismo método de envío puntual e incluso citar el mensaje al que respondes. En los bots, el mensaje entrante llega de inmediato; en las cuentas de mensajería, la conversación se trae por sincronización, es decir, con retraso. En ambos casos hace falta un plan con analítica de respuestas; más abajo lo explicamos.
• Webhooks. La cuenta se conectó o se desconectó, la plataforma restringió la cuenta, el envío arrancó, se pausó o terminó, el destinatario respondió, llegó un mensaje entrante. No hace falta consultar la API en bucle.

Algo importante sobre el remitente: los mensajes salen desde tus cuentas, las que conectas tú. El servicio no da números propios, y eso juega a tu favor: el número y su reputación siguen siendo tuyos, y las respuestas de los clientes te llegan a la aplicación de mensajería de siempre.

Cómo obtener la clave de API

1. Entra al panel de envíos y abre la sección API.
2. Haz clic en «Crear clave», ponle un nombre (después te servirá para saber a qué integración se la diste) y, si quieres, una fecha de vencimiento.
3. Copia el token. Se muestra una sola vez: el servicio guarda solo su hash y no puede recuperar el valor. Si lo pierdes, crea una clave nueva y borra la anterior.

La sección API solo la ve el dueño del proyecto: él es quien crea las claves y ve la lista. Así que, si la integración la hace un desarrollador o un proveedor externo, el dueño emite la clave y le pasa el token, en lugar de darle acceso al panel.

La clave se emite para el proyecto, no para un empleado. Guárdala como una contraseña. Puedes crear varias claves, por ejemplo una por integración, para revocarlas por separado.

La clave tiene permisos, y se marcan al crearla: leer los datos del proyecto, preparar envíos y audiencias, lanzar envíos y enviar mensajes, gestionar las cuentas, configurar el webhook. Por defecto, una clave nueva puede leer y preparar; lo demás lo habilitas tú de forma deliberada. Los permisos se pueden cambiar después sin cambiar la clave: no tendrás que detener la integración que ya la usa.

El token va en una cabecera de cada solicitud. Para comprobar que todo funciona, pide la lista de cuentas conectadas:

curl https://api.wsender.io/v1/channel \
  -H "Authorization: key TU_TOKEN"

Todos los métodos están descritos en la documentación de la API, y puedes ejecutar una solicitud con tu clave directamente desde el navegador, sin escribir una sola línea de código. Al lado está la especificación para máquinas, el archivo OpenAPI: con él, herramientas como Swagger Codegen o NSwag generan solas un cliente en tu lenguaje, y no tienes que describir a mano las solicitudes ni los modelos.

Un envío masivo en siete solicitudes

El escenario mínimo es este: armar el segmento → crear el envío → agregar el texto → indicar los destinatarios → mandar a moderación → lanzar.

1. PUT /v1/segment crea el segmento.
2. PUT /v1/segment/{segmentId}/contact carga los números.
3. PUT /v1/mailing crea el envío.
4. PUT /v1/mailing/{mailingId}/message/text agrega el texto del mensaje.
5. PUT /v1/mailing/{mailingId}/recipient/source indica que los destinatarios salen del segmento.
6. POST /v1/mailing/{mailingId}/moderate manda el texto a revisión.
7. POST /v1/mailing/{mailingId}/start lanza el envío desde la cuenta elegida.

Las solicitudes son las mismas en todos los casos: un envío por WhatsApp se crea igual que uno por Telegram o desde un bot. Solo cambia lo que tienes conectado. Después no hace falta consultar nada: los estados llegan por webhooks.

Repetir la solicitud no crea un segundo envío

Pasa con frecuencia en las integraciones: la solicitud salió y la respuesta nunca volvió. La red falló un instante, saltó un timeout, tu servicio se reinició en mal momento. Y no queda claro qué hacer: si repites, te arriesgas a crear un segundo envío o a lanzarlo dos veces; si no repites, puede que no se haya enviado nada.

Por eso cada solicitud que cambia algo admite una clave de idempotencia. Inventas una cadena (normalmente un UUID) y la pasas en una cabecera:

Idempotency-Key: 3f0c1b7e-8a2e-4a51-9d2b-6a1e0f2c4d88

La regla es una sola: para una operación nueva, una clave nueva; para repetir la misma operación, la misma clave. Del resto se encarga el servicio. La primera solicitud se ejecuta y su respuesta se guarda durante un día. Una repetición con la misma clave no ejecuta nada: devuelve la misma respuesta que la primera vez. Si la primera solicitud todavía está en proceso, la repetición recibe el código 409: espera y vuelve a preguntar.

Si con la misma clave mandas una solicitud distinta, llega el código 422. Es una protección contra la reutilización accidental de una clave: no vas a recibir el resultado de otra operación.

En la práctica, en tu integración conviene repetir lo que no tuvo resultado: una conexión cortada, los errores del servidor y la respuesta 429 (demasiadas solicitudes). Esas respuestas no se guardan, y la repetición sí ejecuta la operación. En cambio, un rechazo de fondo, por ejemplo «falta un campo obligatorio en el texto», ya es un resultado, y la repetición devuelve lo mismo.

De dónde salen los destinatarios

El quinto paso merece un análisis aparte: de la fuente dependen tanto el resultado como el riesgo para la cuenta. Hay tres.

• Segmento de contactos. Los números los cargas tú. Un envío vinculado a un segmento sigue enviando mensajes a los contactos que agregues después. Para una integración es la fuente principal, y más abajo tiene su propia sección.
• Contactos de la cuenta. La agenda del número conectado. Por defecto, los mensajes solo les llegan a quienes ya tuvieron una conversación contigo: esa audiencia responde mejor y casi no genera reportes. La restricción se puede quitar, pero es mejor no hacerlo.
• Chats de la cuenta. Las conversaciones existentes. Aquí también puedes dejar solo a las personas con las que ya hablaste y excluir aparte las conversaciones con bots, para no escribir en chats de servicio.

Un detalle importante al diseñar: en el primer lanzamiento, la fuente queda fija junto con la plataforma de mensajería y ya no cambia. Para usar otra fuente hace falta un envío nuevo.

Bots de Telegram: la misma API

No tenemos una «API para bots» aparte, y es a propósito: una integración escrita para enviar desde una cuenta funciona con un bot sin cambios. Los mismos métodos de conexión, los mismos estados, los mismos webhooks, el mismo camino del envío, desde el borrador hasta el informe por destinatario.

Hay exactamente dos diferencias, y las dos se ven enseguida.

Conexión con token. El token lo obtienes en Telegram, te lo da @BotFather. Después va la misma solicitud que para una cuenta, solo que en lugar del método de inicio de sesión lleva el token. Si generaste un token nuevo, el bot no se pierde: una solicitud aparte de actualización de token lo cambia en el bot ya conectado, y los suscriptores, los envíos y el historial se quedan donde estaban (en el panel, lo mismo se hace desde la página del bot).

Destinatarios: los suscriptores del bot. El bot les escribe a quienes le escribieron primero: un segmento de números cargado no le sirve. Así funciona la propia plataforma: la Bot API de Telegram no permite escribir primero, y nadie puede saltarse esa regla.

De ahí sale una división de roles simple en la integración. La cuenta de mensajería sigue siendo la única forma de llegar a alguien con quien todavía no has hablado. El bot sirve para trabajar con quienes ya están suscritos: un envío así no tiene por qué causar un bloqueo, el número de teléfono no participa para nada, y la velocidad depende de los límites de la plataforma, no de un arranque prudente para cuidar la cuenta.

Envíos automáticos por evento: una llamada por cada evento

La propiedad más útil del segmento: un envío vinculado a él no termina cuando les llegó a todos los que estaban en el segmento. Sigue activo y espera contactos nuevos: en cuanto los agregas al segmento, el envío se reanuda de inmediato.

En la práctica, un envío lanzado funciona como una cola de envío. Por eso el esquema es este:

1. Creas una sola vez el segmento y su envío, agregas el texto y lo lanzas. Por API o a mano en el panel, de ahí en adelante da igual.
2. Después, por cada evento en tu sistema haces una solicitud: agregar el número al segmento.

Eso es todo. El mensaje sale solo, a un ritmo seguro, con el texto ya revisado y respetando los límites. Pagó su pedido, agendó una cita, no llegó, lleva un mes sin aparecer: tienes tus propios envíos automáticos por evento, y solo hay que mantener una llamada por cada motivo.

La baja es igual de simple, y conviene pensarla desde el principio: si alguien pidió que no le escriban más, borra su número del segmento con una solicitud y la cola ya no lo toma. El contacto sigue en el proyecto con su historial; solo sale de esa audiencia.

El texto de un envío así es el mismo para todos los destinatarios, con el nombre insertado y variantes de redacción. Por eso para cada motivo se arma su propio par «segmento más envío»: bienvenida, recordatorio de cita, recuperación de clientes. Se crean una vez y después solo esperan números.

Las respuestas de los clientes vuelven a tu sistema

El envío no termina cuando sale el mensaje: la gente responde, y la respuesta suele ser justo el resultado que buscabas. Por la API ves que la persona respondió y también qué escribió exactamente.

El orden es este: llega el webhook «el destinatario respondió», con él consultas las respuestas de ese destinatario y recibes la hora, el texto, el tipo de mensaje y los nombres de los archivos adjuntos.

curl https://api.wsender.io/v1/mailing/{ID_DEL_ENVIO}/recipient/{ID_DEL_DESTINATARIO}/reply \
  -H "Authorization: key TU_TOKEN"

Se devuelven justamente las respuestas a este envío, no toda la conversación con la persona: el servicio toma los mensajes posteriores al envío a ese destinatario. Con la misma regla se marca el estado «respondió», así que el estado y el contenido siempre coinciden.

Después la respuesta entra a tu CRM: como tarea para el vendedor, al chat del equipo de ventas, a un dashboard. Un par de salvedades para no contar con lo que no hay: la conversación se trae de la cuenta cada cierto tiempo, así que entre la respuesta de la persona y su aparición en la API pasa un rato, y la lista puede venir vacía si, en lugar de escribir, la persona reaccionó al mensaje.

Si todavía no tienes CRM propio, esas mismas respuestas se ven en Dialogs, que se abre desde el panel: el operador las lee y responde desde ahí. Los mensajes enviados por API aparecen firmados como «API», y al pasar el cursor por la firma se ve con qué clave se enviaron.

Y lo más importante sobre los planes. Las respuestas, y con ellas las conversaciones y los contactos de la cuenta, salen de la sincronización de la cuenta conectada, y no todos los planes la incluyen: el gratuito no la tiene. Ahí puedes armar y probar la integración, los envíos se crean y salen, pero no hay retorno: el webhook de respuesta no llega, y la consulta de respuestas devuelve el error 403 con la explicación de que el plan no incluye esa función. Lo hicimos así a propósito, en vez de devolver una lista vacía: una respuesta vacía la leerías como «la persona no respondió» y buscarías el error en tu código.

Lo mismo pasa con los bots. En el plan gratuito, el bot solo funciona de salida: los envíos salen, pero los mensajes entrantes de los suscriptores no se reciben ni se guardan en ningún lado, ni en la API ni en el panel. Los suscriptores, eso sí, siguen sumándose, y puedes enviarles mensajes.

Webhooks: el servicio te avisa qué pasó

No hace falta consultar la API en bucle «a ver qué hay». Indica tu dirección y los eventos te llegan solos:

curl -X PUT https://api.wsender.io/v1/webhook \
  -H "Authorization: key TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/wsender","secret":"tu-secreto"}'

Hay un webhook por proyecto, y la dirección tiene que ser HTTPS. Cambia la dirección y el secreto del ejemplo por los tuyos: el secreto admite letras latinas sin tildes, números, guion y guion bajo. El servicio lo devuelve en la cabecera X-WSender-Secret-Token de cada solicitud, y así distingues tus eventos de otras llamadas a la misma dirección.

Llegan eventos de cuatro grupos:

• Cuenta: conectada, desconectada y, durante la conexión: que el código QR está listo, que el código de vinculación está listo, que se espera el código de confirmación o la contraseña de verificación en dos pasos, que todo salió bien.
• Restricciones de la plataforma: la cuenta fue restringida y la restricción se levantó. Quizá lo más valioso: con un bloqueo, la cuenta sigue conectada, y sin el evento el envío se detiene en silencio.
• Envío: pasó la moderación, no la pasó y trae observaciones, arrancó, se pausó con un motivo, terminó, se canceló.
• Destinatarios: mensajes enviados, la persona respondió, el envío falló, el número no está registrado en la plataforma.

Los eventos de destinatarios y de mensajes sueltos solo llegan con suscripción explícita. Indica los tipos que necesitas en events: una lista vacía no los activa, para que un envío grande no genere un flujo de eventos innecesario.

Primero guarda el evento entrante de forma segura, luego responde con un código 2xx y después procésalo. Si tu servidor no responde en 10 segundos o devuelve un error, el servicio reintenta con pausas de entre 30 segundos y media hora. Cada evento se guarda en la cola como máximo un día desde que se creó.

Un mismo evento puede llegar dos veces: revisa su id para no ejecutar dos veces la acción en tu CRM.

Si pasó un día desde el primer rechazo y en ese tiempo no hubo ninguna entrega exitosa, el webhook se pausa automáticamente. El dueño del proyecto recibe un aviso por el bot de notificaciones de WSENDER en Telegram, si lo tiene conectado. El estado se consulta con GET /v1/webhook: el objeto health trae el estado Active o Suspended, el último error y las fechas.

Cuando corrijas tu receptor, llama a POST /v1/webhook/resume con una clave que tenga el permiso de configurar el webhook:

curl -X POST https://api.wsender.io/v1/webhook/resume \
  -H "Authorization: key TU_TOKEN"

El servicio enviará a tu dirección el evento de prueba webhook.test con el secreto de siempre. Solo una respuesta 2xx reanuda la entrega. El POST /v1/webhook/test normal sirve para comprobar la dirección, pero no quita la pausa.

Durante la pausa, los eventos nuevos no se acumulan y el plazo de los que ya se crearon no se extiende. Los eventos vencidos y los que surgieron durante la pausa no llegan después de reanudar. Por eso, tras una caída larga, consulta por la API los estados actuales de los mensajes y los envíos. Los detalles de campos y errores están en la documentación de la API.

Velocidad: por qué la API no envía todo de golpe

Aquí es donde más chocan las expectativas de los desarrolladores con la realidad de las plataformas de mensajería. La API acepta la solicitud al instante, pero el ritmo de envío lo marca la Autoestrategia: empieza despacio y sube la velocidad a medida que la cuenta acumula historial de envíos. Si la plataforma frena la cuenta, el servicio pausa el envío y sigue más despacio.

Así cuida el servicio tu número: si mandas toda la base en una hora, lo más probable es que la plataforma restrinja la cuenta. Por eso el servicio no ofrece esa opción.

Hay otros cuatro puntos que conviene tener en cuenta antes de integrar:

• El texto se revisa antes del lanzamiento. La IA revisa el mensaje y puede devolver observaciones: la lista se lee por API, y en cada una se ve qué está mal y en qué mensaje. Las observaciones que son recomendaciones se aceptan con una solicitud; los temas prohibidos solo se corrigen editando el texto.
• Los límites del plan funcionan igual que en el panel. Los mensajes consumen el límite diario: cuando se agota, el envío se pausa y no se reanuda solo; hay que lanzarlo de nuevo, desde el panel o por API.
• El límite de solicitudes es por proyecto. Lo comparten todas las claves del proyecto: crear claves nuevas no lo aumenta.
• Los números fríos van más lento. Si el número no está en tus conversaciones, primero hay que consultar a la plataforma si está registrado. Telegram limita esa búsqueda con más rigor, así que ahí un envío a números desconocidos va bastante más despacio que en WhatsApp.

Dónde sirve la API de envíos masivos

• CRM: avisos sobre el estado de la venta y del pedido, y las respuestas de los clientes vuelven a la ficha.
• Tienda online: confirmación del pedido, pago, entrega.
• Sitio web o landing: respuesta inmediata cuando alguien deja sus datos, por la app de mensajería que usa.
• Agenda en línea: recordatorio de la cita un día antes.
• Reactivación: el segmento «no compró en 3 meses» se llena desde tu base, y el envío va despachando la cola solo.

Qué sigue

La API no se paga aparte: se aplican los planes habituales, y está disponible incluso en el gratuito. El plan gratuito incluye 15 mensajes al día, suficiente para armar y probar la integración.

Empieza por algo pequeño: crea una clave, pide la lista de cuentas, conecta una cuenta y lanza un envío a un segmento con un solo número, el tuyo. En media hora vas a entender todo el circuito. Después solo queda armar el par «segmento más envío» que vas a usar de verdad y agregarle números desde el punto de tu sistema donde nace el evento.

La descripción completa de los métodos está en la documentación de la API, y la especificación para generar un cliente, en el archivo OpenAPI.