cargo add soblendwa
cargo add tokio --features full

npm install soblendwa-node

pip install soblendwa

npm install soblendwa-client

Elige por dónde empezar#

Rendimiento#

Un bot de eco contra el mismo servidor, comparado con zapo-js 1.11 con su acelerador activado.

Es una prueba de laboratorio sin red real, con el método y sus límites explicados en Rendimiento.

Antes de usarlo#

Qué paquete necesitas#

No necesitas Rust instalado para usar los paquetes de Node.js, Python ni los binarios del servidor.

Rust#

Necesitas Rust 1.89 o más reciente.

cargo add soblendwa
cargo add tokio --features full

O en tu Cargo.toml, activando las features que quieras:

[dependencies]
soblendwa = { version = "0.1", features = ["sqlite"] }
tokio = { version = "1", features = ["full"] }

Sin features ya tienes FileStore y MemoryStore.

Node.js y TypeScript#

npm install soblendwa-node

Funciona con Node.js 18 o más reciente, y los tipos de TypeScript vienen incluidos.

El paquete trae los binarios de las cinco plataformas, así que la descarga ronda los 40 MB. En Alpine y otras distribuciones con musl, usa el servidor con soblendwa-client.

Python#

pip install soblendwa

Funciona con Python 3.9 o más reciente gracias al ABI estable, en Windows x64, macOS (Intel y ARM) y Linux x64 o ARM64 (manylinux 2.28).

Cliente JavaScript#

npm install soblendwa-client

No tiene dependencias y funciona en Node.js 18+, Bun, Deno y el navegador. En Node.js 22+, Bun y Deno usa el WebSocket incluido; en Node.js 18 a 21 instala también ws. Necesita un soblendwa-server corriendo.

Servidor sin compilar#

Cada versión publica binarios en Releases. Los de Linux con musl son estáticos: funcionan en cualquier VPS sin instalar nada.

curl -L -o soblendwa.tar.gz https://github.com/Soblend-Development-Studio/SoblendWA/releases/latest/download/soblendwa-server-x86_64-unknown-linux-musl.tar.gz
tar -xzf soblendwa.tar.gz
./soblendwa-server --token "una-clave-larga" --session bot

También puedes compilarlo con Rust:

cargo install --git https://github.com/Soblend-Development-Studio/SoblendWA soblendwa-server

Compilar los módulos desde el código#

git clone https://github.com/Soblend-Development-Studio/SoblendWA
cd SoblendWA/bindings/node
npm install
npm run build
npm test

cd SoblendWA/bindings/python
pip install maturin
maturin develop --release

Lo que necesitas#

• Un teléfono con WhatsApp, para escanear el QR. Usa una cuenta de pruebas si puedes.
• Rust, Node.js o Python instalados, según el lenguaje que elijas.

1. Escribe el bot#

use soblendwa::{Client, Event, FileStore};

#[tokio::main]
async fn main() -> soblendwa::Result<()> {
    let store = FileStore::open("session").await?;
    let (client, mut events) = Client::builder()
        .store(store)
        .push_name("Mi Bot")
        .build()
        .await?;
    client.connect().await?;

    while let Some(event) = events.recv().await {
        match event {
            Event::Qr(code) => println!("Escanea este QR: {code}"),
            Event::Connected => println!("Conectado como {:?}", client.me()),
            Event::Message(msg) if !msg.info.from_me => {
                if msg.text() == Some("!ping") {
                    let ms = msg.info.elapsed().as_secs_f64() * 1000.0;
                    client.reply(&msg, format!("Pong\n{ms:.2} ms")).await?;
                }
            }
            Event::LoggedOut { reason } => {
                println!("Sesión cerrada: {reason}");
                break;
            }
            _ => {}
        }
    }
    Ok(())
}

const { SoblendWA } = require('soblendwa-node')

async function main() {
  const bot = await SoblendWA.create({ store: { type: 'sqlite', path: 'session/auth.db' } })

  bot.on('qr', ({ code }) => console.log('Escanea este QR:', code))
  bot.on('connected', () => console.log('Conectado como', bot.me))
  bot.on('message', async (message) => {
    if (message.info.fromMe) return
    if (message.text === '!ping') await bot.reply(message, `Pong\n${bot.elapsed(message).toFixed(2)} ms`)
  })

  await bot.connect()
}

main()

import asyncio
from soblendwa import SoblendWA


async def main():
    bot = await SoblendWA.create(store={"type": "sqlite", "path": "session/auth.db"})

    @bot.on("qr")
    def show_qr(event):
        print("Escanea este QR:", event["code"])

    @bot.on("message")
    async def answer(message):
        if message["info"]["fromMe"]:
            return
        if message["text"] == "!ping":
            await bot.reply(message, f"Pong\n{bot.elapsed(message):.2f} ms")

    await bot.run()


asyncio.run(main())

import { connect } from 'soblendwa-client'

const bot = await connect('ws://127.0.0.1:8787', { session: 'bot', token: 'una-clave-larga' })

bot.on('qr', ({ code }) => console.log('Escanea este QR:', code))
bot.on('message', async (message) => {
  if (message.info.fromMe) return
  if (message.text === '!ping') {
    const ms = await bot.elapsed(message)
    await bot.reply(message, `Pong\n${ms.toFixed(2)} ms`)
  }
})

Si usas el cliente JS, primero arranca el servidor con soblendwa-server --token "una-clave-larga" --session bot. El servidor dibuja el QR en la terminal.

2. Vincula tu teléfono#

El texto del evento qr es el contenido del código QR, no una imagen. Conviértelo en imagen con cualquier librería de QR, como qrcode-terminal en Node.js o qrcode en Python, o usa un código de 8 caracteres.

1. Ejecuta el bot.
2. En el teléfono, abre WhatsApp > Dispositivos vinculados > Vincular un dispositivo.
3. Escanea el QR. El bot se reinicia solo una vez y emite connected.
4. Desde otro número, envía !ping a la cuenta vinculada.
5. Recibes Pong y el tiempo que tardó el bot.

3. Qué acaba de pasar#

Tu bot abrió un WebSocket con WhatsApp, verificó su certificado y se registró como un dispositivo vinculado más, igual que WhatsApp Web. Las claves se guardaron en la carpeta o base de datos que elegiste, así que la próxima vez conectará sin QR.

Todo lo que ocurre llega como un evento. Tu bot reacciona a los que le interesan y llama métodos para actuar.

Siguientes pasos#

Vincular con QR#

Después de connect(), si la sesión no está vinculada, llega un evento Qr con el contenido del código. El primero dura 60 segundos y los siguientes 20. Mientras no se escanee, llegan códigos nuevos. Si se agotan, la conexión termina con el motivo QrTimeout y, con la reconexión automática activada, empieza otra tanda de códigos.

Al escanearlo llegan, en este orden:

Vincular con código#

Sirve cuando no puedes escanear, por ejemplo en un servidor sin pantalla. Pide el código después del primer evento qr y escríbelo en Dispositivos vinculados > Vincular con el número de teléfono.

if let Event::Qr(_) = event {
    let code = client.request_pair_code("5215512345678").await?;
    println!("Escribe este código en tu teléfono: {code}");
}

bot.once('qr', async () => {
  const code = await bot.requestPairCode('5215512345678')
  console.log('Escribe este código en tu teléfono:', code)
})

@bot.on("qr")
async def pair(event):
    print("Código:", await bot.request_pair_code("5215512345678"))

bot.once('qr', async () => {
  console.log('Código:', await bot.requestPairCode('5215512345678'))
})

Escribe el número con código de país y sin espacios. También hay un ejemplo listo: cargo run --release --example pair_code -- 5215512345678.

Cuánto dura la sesión#

La sesión queda en el almacenamiento que elegiste y sobrevive a los reinicios. Termina solo si cierras la vinculación desde el teléfono, si llamas a logout() o si WhatsApp la invalida. En esos casos llega LoggedOut { reason }, los datos se borran y el siguiente connect() muestra un QR nuevo.

Motivos de desconexión#

Cada desconexión llega como Disconnected { reason, reconnecting }.

La espera entre reintentos está explicada en Confiabilidad.

Cerrar la conexión#

Estado de la conexión#

Dispositivo vinculado#

SoblendWA es un dispositivo más de tu cuenta, como WhatsApp Web. No se registra como teléfono: necesita un teléfono real que apruebe la vinculación, con WhatsApp instalado.

JID: la dirección de todo#

Cada cuenta, grupo o canal tiene un JID con la forma usuario:dispositivo@servidor.

Un JID también se puede leer desde un texto:

let jid: Jid = "5215512345678@s.whatsapp.net".parse()?;
let same = jid.same_user(&Jid::phone("52 1 55 1234 5678"));

Jid::phone conserva solo los dígitos, así que acepta números con espacios o signos. En Node.js, Python y el servidor, cualquier parámetro chat acepta un JID completo o solo el número.

LID: cuando WhatsApp oculta el número#

WhatsApp identifica a muchas cuentas con un LID, un identificador que no revela el teléfono, sobre todo en grupos. Una misma persona puede aparecer por su número o por su LID.

SoblendWA resuelve ambos por ti. Cada mensaje trae info.sender_phone e info.sender_lid, y group.is_admin(&sender) funciona con cualquiera de los dos. Si WhatsApp no comparte el número de alguien, sender_phone queda vacío; el LID sigue sirviendo para identificarlo. Puedes consultar la relación con client.lid_for_phone y client.phone_for_lid.

Chat y remitente#

info.chat es la conversación y info.sender es quien escribió. En un chat privado suelen coincidir; en un grupo, chat es el grupo y sender es la persona. Responde siempre a chat.

Identificador y clave de un mensaje#

Cada mensaje tiene un id de texto. Para editarlo, borrarlo o fijarlo necesitas su clave (MessageKey): el chat, el id, si es tuyo y, en grupos, quién lo envió. msg.key() te la da hecha.

Mensajes envueltos#

WhatsApp mete los mensajes dentro de otros: ephemeral, viewOnce, documentWithCaption, hijos de álbum, Meta AI, estados de grupo. SoblendWA los desenvuelve, así que msg.text(), msg.message.media() y msg.quoted() funcionan igual en todos. Si necesitas el original, está en msg.raw.

Eventos#

Todo lo que ocurre llega por un único canal de eventos: mensajes, recibos, cambios de grupo, desconexiones. En Rust es un enum, y en los demás lenguajes es JSON con un campo type. La lista completa está en Eventos.

Colas por chat#

Los chats distintos se atienden en paralelo y cada chat conserva su orden, al recibir y al enviar. Un texto nunca espera detrás de un video pesado de otro chat, y en el mismo chat los mensajes salen en el orden en que los pediste.

Sesiones, cuentas y almacenamiento#

Una sesión es una cuenta vinculada con sus claves, guardadas en un store. Puedes tener varias en el mismo proceso, cada una con su propio cliente. El servidor maneja varias a la vez por nombre.

Todos los envíos devuelven el id del mensaje. Los ejemplos usan client en Rust y bot en los demás lenguajes.

Texto#

use soblendwa::Jid;

let chat = Jid::phone("5215512345678");
let id = client.send_text(&chat, "Hola desde SoblendWA").await?;

const id = await bot.sendText('5215512345678', 'Hola desde SoblendWA')

id = await bot.send_text("5215512345678", "Hola desde SoblendWA")

const id = await bot.sendText('5215512345678', 'Hola desde SoblendWA')

curl -X POST http://127.0.0.1:8787/api/bot/sendText \
  -H "Authorization: Bearer mi-clave" \
  -d '{"chat":"5215512345678","text":"Hola desde SoblendWA"}'

Si el texto trae un enlace, la vista previa se genera sola.

Responder#

reply cita el mensaje original y responde en el mismo chat.

client.reply(&msg, "Respondiendo a tu mensaje").await?;

await bot.reply(message, 'Respondiendo a tu mensaje')

await bot.reply(message, "Respondiendo a tu mensaje")

await bot.reply(message, 'Respondiendo a tu mensaje')

También puedes citar en cualquier otro mensaje: Message::text("hola").reply_to(&msg) en Rust, o { quoted: message } en las opciones de JavaScript.

Reaccionar#

client.react(&msg, "🔥").await?;

await bot.react(message, '🔥')

await bot.react(message, "🔥")

await bot.react(message, '🔥')

Para quitar tu reacción, envía un emoji vacío.

Menciones#

Una mención necesita dos cosas: el @número en el texto y el JID en la lista de mencionados.

use soblendwa::Message;

let usuario = Jid::phone("5215511111111");
client.send_message(&chat, Message::text("hola @5215511111111").mention([&usuario])).await?;
client.send_message(&grupo, Message::text("Atención a todos").mention_all()).await?;

await bot.sendMentionAll(grupo, 'Atención a todos')

await bot.send_mention_all(grupo, "Atención a todos")

await bot.sendMentionAll(grupo, 'Atención a todos')

Editar y eliminar#

let id = client.send_text(&chat, "versión 1").await?;
client.edit_message(&chat, &id, "versión 2").await?;
client.revoke_message(&chat, msg.key()).await?;

const id = await bot.sendText(chat, 'versión 1')
await bot.edit(chat, id, 'versión 2')
await bot.revoke(chat, id)

id = await bot.send_text(chat, "versión 1")
await bot.edit(chat, id, "versión 2")
await bot.revoke(chat, id)

const id = await bot.sendText(chat, 'versión 1')
await bot.edit(chat, id, 'versión 2')
await bot.revoke(chat, id)

Fijar y desfijar#

client.pin_message(&chat, msg.key(), 7 * 24 * 60 * 60).await?;
client.unpin_message(&chat, msg.key()).await?;

Reenviar#

.forwarded() marca el mensaje como reenviado.

client.send_message(&chat, Message::text("reenviado").forwarded()).await?;

Ubicación#

client.send_message(&chat, Message::location(19.4326, -99.1332)).await?;

Contactos#

let tarjeta = Message::vcard("Ana", "+52 1 55 1111 1111");
client.send_message(&chat, Message::contacts("Ana", [("Ana", tarjeta)])).await?;

await bot.sendContacts(chat, [{ name: 'Ana', phone: '5215511111111' }])

await bot.send_contacts(chat, [("Ana", "5215511111111")])

await bot.sendContacts(chat, [{ name: 'Ana', phone: '5215511111111' }])

Invitar a un grupo#

Envía una tarjeta de invitación. SoblendWA pide el código del grupo por ti, así que debes ser administrador.

client.send_group_invite(&chat, &grupo, Some("Únete al equipo")).await?;

await bot.sendGroupInvite(chat, grupo, 'Únete al equipo')

await bot.send_group_invite(chat, grupo, "Únete al equipo")

await bot.sendGroupInvite(chat, grupo, 'Únete al equipo')

Compartir o pedir un número#

client.send_message(&chat, Message::share_phone_number()).await?;
client.send_message(&chat, Message::request_phone_number()).await?;

Limitar el reenvío#

Activa o desactiva el límite de reenvío de una conversación.

client.send_message(&chat, Message::limit_sharing(true)).await?;

Estados#

Publica una historia para una lista de contactos.

client.send_status(Message::text("Mi primer estado"), &[Jid::phone("5215511111111")]).await?;

Etiqueta de miembro#

Pone tu etiqueta dentro de un grupo, de hasta 30 caracteres. Experimental

client.set_member_label(&grupo, "Soporte").await?;

await bot.setMemberLabel(grupo, 'Soporte')

await bot.set_member_label(grupo, "Soporte")

await bot.setMemberLabel(grupo, 'Soporte')

Cualquier otro mensaje#

Message es el protobuf de WhatsApp con todos sus campos públicos, así que puedes construir cualquier mensaje. En otros lenguajes, sendProto acepta los bytes del protobuf.

let mensaje = Message { conversation: Some("Hecho a mano".into()), ..Default::default() };
client.send_message(&chat, mensaje).await?;

await bot.sendProto(chat, bytes)

await bot.send_proto(chat, data)

await bot.sendProto(chat, bytes)

Opciones de envío#

send_message_with da control total sobre un envío.

use soblendwa::{PreviewChoice, SendOptions};

let options = SendOptions { id: Some("3EB0MIID".into()), link_preview: PreviewChoice::Off, ..Default::default() };
client.send_message_with(&chat, Message::text("hola"), options).await?;

Qué puede fallar#

Si no hay conexión, el mensaje se guarda en el outbox y sale al reconectar. La confirmación de WhatsApp llega después en Event::ServerAck.

El bucle de eventos#

while let Some(event) = events.recv().await {
    if let Event::Message(msg) = event {
        if msg.info.from_me {
            continue;
        }
        println!("{}: {:?}", msg.info.sender, msg.text());
    }
}

bot.on('message', (message) => {
  if (message.info.fromMe) return
  console.log(message.info.sender, message.text)
})

@bot.on("message")
def show(message):
    if not message["info"]["fromMe"]:
        print(message["info"]["sender"], message["text"])

bot.on('message', (message) => {
  if (message.info.fromMe) return
  console.log(message.info.sender, message.text)
})

También llegan tus propios mensajes, enviados desde el teléfono o desde el bot: revisa siempre from_me.

Datos del mensaje#

msg.info trae el contexto y msg.message el contenido, ya desenvuelto.

Leer el contenido#

Evitar comandos viejos#

Los mensajes que llegaron con el bot apagado traen info.offline = true. is_stale combina eso con la antigüedad.

use std::time::Duration;

if msg.info.is_stale(Duration::from_secs(120)) {
    return Ok(());
}

if (message.info.offline || message.ageSecs > 120) return

if message["info"]["offline"] or message["ageSecs"] > 120:
    return

if (message.info.offline || message.ageSecs > 120) return

Cuando terminan de llegar los mensajes pendientes se emite Event::OfflineSyncComplete { count }.

Duplicados#

SoblendWA descarta por id los duplicados que llegan, y los cuenta en stats().duplicates, así que no tienes que hacerlo tú.

Mensajes que no se pudieron descifrar#

Si un mensaje no se puede descifrar llega Event::UndecryptableMessage { info, error }, y SoblendWA pide un reintento al remitente y una copia a tu teléfono. Si después llega bien, recibes Event::Message normal y Event::MessageRecovered { id, chat, sender }. Los que siguen esperando se cuentan en stats().awaiting_recovery.

Marcar como leído#

client.read_message(&msg).await?;
client.mark_read(&chat, None, &[msg.info.id.clone()]).await?;
client.mark_played(&msg).await?;

await bot.read(message)
await bot.markPlayed(message)

await bot.markPlayed(message)

await bot.mark_played(message)

mark_played es para notas de voz y videos circulares. Para otros tipos de recibo está send_receipt.

Recibos de los demás#

Event::Receipt avisa de lo que pasa con lo que enviaste: Delivered, Read, Played, Retry y otros tipos, que están en Eventos.

Responder por id en otros lenguajes#

En Node.js, Python y el servidor, reply, react, download y otros aceptan el mensaje o su id. El id se busca entre los últimos 4.096 mensajes recibidos y, si activaste el store de chats, también ahí. Si es más viejo, recibes el error message … is not among the recent messages.

Enviar#

client.send_image(&chat, &std::fs::read("foto.jpg")?, Some("mi foto")).await?;
client.send_video(&chat, &std::fs::read("clip.mp4")?, Some("mi video")).await?;
client.send_audio(&chat, &std::fs::read("nota.ogg")?, true).await?;
client.send_document(&chat, &std::fs::read("reporte.pdf")?, "reporte.pdf", "application/pdf").await?;
client.send_sticker(&chat, &std::fs::read("sticker.webp")?).await?;

const fs = require('node:fs')

await bot.sendImage(chat, fs.readFileSync('foto.jpg'), { caption: 'mi foto' })
await bot.sendVideo(chat, fs.readFileSync('clip.mp4'), { caption: 'mi video' })
await bot.sendAudio(chat, fs.readFileSync('nota.ogg'), { voiceNote: true })
await bot.sendDocument(chat, fs.readFileSync('reporte.pdf'), { fileName: 'reporte.pdf', mimetype: 'application/pdf' })
await bot.sendSticker(chat, fs.readFileSync('sticker.webp'))

with open("foto.jpg", "rb") as photo:
    await bot.send_image(chat, photo.read(), caption="mi foto")

with open("nota.ogg", "rb") as audio:
    await bot.send_audio(chat, audio.read(), voice_note=True)

with open("reporte.pdf", "rb") as document:
    await bot.send_document(chat, document.read(), file_name="reporte.pdf", mimetype="application/pdf")

await bot.sendImage(chat, bytes, { caption: 'mi foto' })
await bot.sendAudio(chat, bytes, { voiceNote: true })
await bot.sendDocument(chat, bytes, { fileName: 'reporte.pdf', mimetype: 'application/pdf' })

Las dimensiones y las miniaturas se calculan solas. Para notas de voz usa audio Opus en un contenedor OGG, que es lo que espera WhatsApp.

Opciones#

Preparar antes de enviar#

prepare_media sube el archivo y te devuelve un Message al que puedes añadir lo que quieras antes de enviarlo.

use soblendwa::{MediaKind, MediaOptions};

let options = MediaOptions { caption: Some("una sola vez".into()), view_once: true, ..Default::default() };
let mensaje = client.prepare_media(&std::fs::read("foto.jpg")?, MediaKind::Image, options).await?;
client.send_message(&chat, mensaje.reply_to(&msg)).await?;

GIF y video circular#

let gif = MediaOptions { gif: true, ..Default::default() };
client.send_media(&chat, &std::fs::read("anim.mp4")?, MediaKind::Video, gif).await?;

let video = client.prepare_media(&std::fs::read("clip.mp4")?, MediaKind::Video, MediaOptions::default()).await?;
client.send_message(&chat, Message::video_note(video)).await?;

Álbumes#

let a = client.prepare_media(&std::fs::read("a.jpg")?, MediaKind::Image, MediaOptions::default()).await?;
let b = client.prepare_media(&std::fs::read("b.jpg")?, MediaKind::Image, MediaOptions::default()).await?;
let ids = client.send_album(&chat, vec![a, b]).await?;

El primer id de la lista es el del álbum y los siguientes, los de cada foto o video.

Descargar#

if msg.message.media().is_some() {
    let bytes = client.download_message(&msg.message).await?;
    std::fs::write(format!("{}.bin", msg.info.id), bytes)?;
}

if (message.media) {
  const bytes = await bot.download(message)
  require('node:fs').writeFileSync(`${message.info.id}.bin`, bytes)
}

if message["media"]:
    data = await bot.download(message)
    with open(message["info"]["id"] + ".bin", "wb") as output:
        output.write(data)

if (message.media) {
  const bytes = await bot.download(message)
}

La descarga verifica el HMAC y los dos SHA-256 antes de entregarte los bytes. Si el archivo ya caducó en el servidor, download_event y download_event_to_file le piden al remitente que lo vuelva a subir, y lo descargan de nuevo. Experimental

Archivos grandes#

Con estos métodos la memoria no depende del tamaño del archivo.

client.send_media_file(&chat, "pelicula.mp4", MediaKind::Video, MediaOptions::default()).await?;
client.send_media_file(&chat, "reporte.pdf", MediaKind::Document, MediaOptions::default()).await?;
let bytes = client.download_event_to_file(&msg, "descargas/video.mp4").await?;

await bot.sendFile(chat, 'video', 'pelicula.mp4')
const bytes = await bot.downloadToFile(message, 'descargas/video.mp4')

await bot.send_file(chat, "video", "pelicula.mp4")
size = await bot.download_to_file(message, "descargas/video.mp4")

await bot.sendFile(chat, 'video', '/ruta/en/el/servidor/pelicula.mp4')
const bytes = await bot.downloadToFile(message, '/ruta/en/el/servidor/video.mp4')

send_media_file lee el archivo dos veces por bloques de 256 KB: una para calcular los hashes que WhatsApp pide antes de subir y otra para cifrar mientras sube. No crea archivos temporales. El tipo MIME y el nombre del documento se deducen de la extensión.

download_to_file escribe en archivo.part y solo lo renombra cuando la verificación pasa, así que un archivo corrupto nunca aparece con su nombre final.

Reutilización automática#

Si envías el mismo archivo otra vez, como un sticker o la imagen de un comando, no se vuelve a cifrar ni a subir: sale tan rápido como un texto. En una cuenta real, una imagen repetida pasó de 1.420 ms a 4 ms.

• El archivo se recuerda 7 días. Lo cambias con .media_cache(Some(duración)) o lo desactivas con .media_cache(None).
• Pasada una hora se comprueba en el CDN que sigue disponible. Experimental
• client.forget_upload(kind, sha256) olvida un archivo concreto.
• stats().media_uploaded y stats().media_reused muestran cuánto ahorras.

Herramientas de imagen#

El módulo soblendwa::imaging tiene las funciones que SoblendWA usa por dentro.

use soblendwa::imaging::{image_dimensions, profile_picture, thumbnail};

let datos = std::fs::read("foto.jpg")?;
let tamano = image_dimensions(&datos);
let miniatura = thumbnail(&datos, 100)?;
let perfil = profile_picture(&datos)?;

Incluye título, descripción, miniatura y, si la página tiene video, la marca de video. No tienes que llamar a nada distinto.

Por mensaje#

use soblendwa::{LinkPreview, PreviewChoice, SendOptions};

client.send_text(&chat, "Mira esto: https://www.rust-lang.org").await?;

let sin_vista = SendOptions { link_preview: PreviewChoice::Off, ..Default::default() };
client.send_message_with(&chat, Message::text("https://www.rust-lang.org"), sin_vista).await?;

let propia = LinkPreview { title: Some("Mi título".into()), description: Some("Escrito a mano".into()), ..Default::default() };
let opciones = SendOptions { link_preview: PreviewChoice::Custom(Box::new(propia)), ..Default::default() };
client.send_message_with(&chat, Message::text("https://www.rust-lang.org"), opciones).await?;

await bot.sendText(chat, 'Mira esto: https://www.rust-lang.org')
await bot.sendText(chat, 'https://www.rust-lang.org', { preview: false })
await bot.sendText(chat, 'https://www.rust-lang.org', { preview: { title: 'Mi título', description: 'Escrito a mano' } })

await bot.send_text(chat, "Mira esto: https://www.rust-lang.org")
await bot.send_text(chat, "https://www.rust-lang.org", preview=False)
await bot.send_text(chat, "https://www.rust-lang.org", preview={"title": "Mi título", "description": "Escrito a mano"})

await bot.sendText(chat, 'Mira esto: https://www.rust-lang.org')
await bot.sendText(chat, 'https://www.rust-lang.org', { preview: false })
await bot.sendText(chat, 'https://www.rust-lang.org', { preview: { title: 'Mi título', description: 'Escrito a mano' } })

Para todo el cliente#

use std::time::Duration;
use soblendwa::LinkPreviewConfig;

let config = LinkPreviewConfig { timeout: Duration::from_secs(2), enabled: true, ..Default::default() };
let (client, events) = Client::builder().store(store).link_previews(config).build().await?;

const bot = await SoblendWA.create({ linkPreviews: { enabled: true, timeoutMs: 2000 } })

bot = await SoblendWA.create(link_previews={"enabled": True, "timeout_ms": 2000})

soblendwa-server --no-link-previews

Cómo funciona#

• La consulta sale de tu servidor. Para generar la vista previa, el bot abre la página, como hace el teléfono en la app oficial. Si repite enlaces de desconocidos y no quieres eso, usa enabled: false.
• Protegido contra enlaces maliciosos. Nunca consulta hosts privados: 127.0.0.1, la red interna, el servicio de metadatos de la nube (169.254.169.254), localhost, *.local ni *.internal. También revisa cada redirección y a qué IP resuelve el dominio, así un dominio público que apunte a tu red interna tampoco pasa.
• Dos miniaturas. Una pequeña dentro del mensaje y otra nítida de hasta 1200 px, subida cifrada. Si la subida falla, el mensaje sale igual con la pequeña. La nítida aún es Experimental
• Reutiliza lo que ya hizo. Un enlace repetido no vuelve a consultar la página, por 1 hora, ni a subir la miniatura.
• Nunca frena un envío. Si la página falla o no responde, sale una tarjeta mínima con el dominio.
• Imágenes hostiles. La imagen se decodifica con límites de tamaño y memoria.

Tu propia fuente de datos#

Implementa LinkPreviewFetcher para traer los datos de otro servicio. Si devuelves None, el enlace se envía sin tus datos.

use std::sync::Arc;
use async_trait::async_trait;
use soblendwa::{LinkPreview, LinkPreviewConfig, LinkPreviewFetcher};

struct MiFuente;

#[async_trait]
impl LinkPreviewFetcher for MiFuente {
    async fn fetch(&self, url: &str) -> soblendwa::Result<Option<LinkPreview>> {
        Ok(Some(LinkPreview { url: url.to_owned(), title: Some("Desde mi API".into()), ..Default::default() }))
    }
}

let config = LinkPreviewConfig { fetcher: Some(Arc::new(MiFuente)), ..Default::default() };

Otras funciones#

Los mensajes recibidos traen en JSON linkPreview con url, title, description, video, hasThumbnail, hasHighQualityThumbnail, thumbnailWidth y thumbnailHeight.

Crear una encuesta#

El último número es cuántas opciones se pueden elegir. Con 1 se usa el formato de opción única; con 0 o más de una, el de varias opciones, igual que la app oficial.

let encuesta = client.send_message(&chat, Message::poll("¿Pizza o tacos?", ["Pizza", "Tacos"], 1)).await?;
client.send_message(&chat, Message::poll("¿Qué te gusta?", ["Rust", "Go", "Zig"], 0)).await?;

const encuesta = await bot.sendPoll(chat, '¿Pizza o tacos?', ['Pizza', 'Tacos'], 1)
await bot.sendPoll(chat, '¿Qué te gusta?', ['Rust', 'Go', 'Zig'], 0)

encuesta = await bot.send_poll(chat, "¿Pizza o tacos?", ["Pizza", "Tacos"], 1)
await bot.send_poll(chat, "¿Qué te gusta?", ["Rust", "Go", "Zig"], 0)

const encuesta = await bot.sendPoll(chat, '¿Pizza o tacos?', ['Pizza', 'Tacos'], 1)
await bot.sendPoll(chat, '¿Qué te gusta?', ['Rust', 'Go', 'Zig'], 0)

Message::announcement_poll es para grupos de anuncios de comunidades.

Votar#

client.vote_poll(&chat, &encuesta, &["Tacos"]).await?;

await bot.votePoll(chat, encuesta, ['Tacos'])

await bot.vote_poll(chat, encuesta, ["Tacos"])

await bot.votePoll(chat, encuesta, ['Tacos'])

Leer los votos#

if let Event::PollVote(voto) = event {
    println!("{} votó {:?} en {}", voto.voter, voto.selected, voto.poll_id);
}

bot.on('pollVote', ({ voter, selected, pollId }) => console.log(voter, selected, pollId))

@bot.on("pollVote")
def voted(event):
    print(event["voter"], event["selected"], event["pollId"])

bot.on('pollVote', ({ voter, selected, pollId }) => console.log(voter, selected, pollId))

Las opciones llegan por nombre. Si activas el store de chats, los votos también se guardan en poll_votes.

Eventos de calendario#

use soblendwa::events::EventResponseKind;

let evento = Message::event("Lanzamiento SoblendWA", 1_800_000_000)
    .event_details(Some("En vivo"), Some(1_800_003_600), Some((19.4326, -99.1332, "CDMX")), None, true);
let id = client.send_message(&chat, evento).await?;
client.respond_event(&chat, &id, EventResponseKind::Going, 0).await?;

Los parámetros de event_details son: descripción, hora de fin en segundos Unix, lugar como (latitud, longitud, nombre), enlace para unirse y si se permiten invitados extra. .cancel_event() marca el evento como cancelado.

Leer las respuestas#

Event::EventResponse trae chat, event_id, responder, kind, extra_guests y timestamp.

Menú interactivo#

use soblendwa::interactive::{Interactive, Section};

let menu = Interactive::new("¿Qué quieres hacer?")
    .title("Soblend")
    .footer("SoblendWA")
    .quick_reply("ping", "Medir latencia")
    .url("Documentación", "https://github.com/Soblend-Development-Studio/SoblendWA")
    .copy("Copiar cupón", "SOBLEND-2026")
    .call("Llamar", "+5215512345678")
    .select("Ver comandos", vec![Section::new("Comandos").described_row("menu", "Menú", "Todos los comandos")]);
client.send_message(&chat, menu.build()).await?;

await bot.sendInteractive(chat, {
  body: '¿Qué quieres hacer?',
  title: 'Soblend',
  footer: 'SoblendWA',
  buttons: [
    { type: 'reply', id: 'ping', text: 'Medir latencia' },
    { type: 'url', text: 'Documentación', url: 'https://github.com/Soblend-Development-Studio/SoblendWA' },
    { type: 'copy', text: 'Copiar cupón', code: 'SOBLEND-2026' },
    { type: 'call', text: 'Llamar', phone: '+5215512345678' },
    { type: 'select', title: 'Ver comandos', sections: [{ title: 'Comandos', rows: [{ id: 'menu', title: 'Menú', description: 'Todos los comandos' }] }] },
  ],
})

await bot.send_interactive(
    chat,
    "¿Qué quieres hacer?",
    [
        {"type": "reply", "id": "ping", "text": "Medir latencia"},
        {"type": "url", "text": "Documentación", "url": "https://github.com/Soblend-Development-Studio/SoblendWA"},
        {"type": "copy", "text": "Copiar cupón", "code": "SOBLEND-2026"},
    ],
    title="Soblend",
    footer="SoblendWA",
)

await bot.sendInteractive(chat, {
  body: '¿Qué quieres hacer?',
  footer: 'SoblendWA',
  buttons: [
    { type: 'reply', id: 'ping', text: 'Medir latencia' },
    { type: 'url', text: 'Documentación', url: 'https://github.com/Soblend-Development-Studio/SoblendWA' },
  ],
})

La cabecera puede llevar texto (.title, .subtitle) o multimedia ya preparada (.image, .video, .document).

Botones simples#

client.send_message(&chat, Message::buttons("Elige", Some("pie"), [("si", "Sí"), ("no", "No")])).await?;

await bot.sendButtons(chat, 'Elige', [{ id: 'si', text: 'Sí' }, { id: 'no', text: 'No' }], 'pie')

await bot.send_buttons(chat, "Elige", [("si", "Sí"), ("no", "No")], "pie")

await bot.sendButtons(chat, 'Elige', [{ id: 'si', text: 'Sí' }, { id: 'no', text: 'No' }], 'pie')

Listas#

use soblendwa::interactive::Section;

client.send_message(&chat, Message::list("Menú", "Elige un plato", "Ver menú", None, &[
    Section::new("Tacos").row("pastor", "Al pastor").row("suadero", "Suadero"),
])).await?;

await bot.sendList(chat, {
  title: 'Menú',
  text: 'Elige un plato',
  buttonText: 'Ver menú',
  sections: [{ title: 'Tacos', rows: [{ id: 'pastor', title: 'Al pastor' }, { id: 'suadero', title: 'Suadero' }] }],
})

await bot.send_list(chat, "Menú", "Elige un plato", "Ver menú", [
    {"title": "Tacos", "rows": [{"id": "pastor", "title": "Al pastor"}, {"id": "suadero", "title": "Suadero"}]},
])

await bot.sendList(chat, {
  title: 'Menú',
  text: 'Elige un plato',
  buttonText: 'Ver menú',
  sections: [{ title: 'Tacos', rows: [{ id: 'pastor', title: 'Al pastor' }, { id: 'suadero', title: 'Suadero' }] }],
})

Leer la opción elegida#

if let Some(reply) = msg.message.interactive_reply() {
    println!("eligió {} ({:?})", reply.id, reply.source);
}

bot.on('message', (message) => {
  if (message.reply?.id === 'ping') bot.reply(message, 'Pong')
})

@bot.on("message")
async def chosen(message):
    if message["reply"] and message["reply"]["id"] == "ping":
        await bot.reply(message, "Pong")

bot.on('message', (message) => {
  if (message.reply?.id === 'ping') bot.reply(message, 'Pong')
})

reply trae id, text, source (buttons, list, template o nativeFlow), flow y params.

Plantillas y respuestas#

Consultar#

let info = client.group_info(&grupo).await?;
let actualizado = client.group_metadata(&grupo).await?;
let todos = client.joined_groups().await?;

const info = await bot.groupInfo(grupo)
const todos = await bot.joinedGroups()

info = await bot.group_info(grupo)
todos = await bot.joined_groups()

const info = await bot.groupInfo(grupo)
const todos = await bot.joinedGroups()

group_info responde desde la caché al instante, y group_metadata siempre consulta al servidor. La caché se actualiza sola cuando WhatsApp avisa de un cambio.

Revisar si alguien es admin#

is_admin acepta el número o el LID de la persona, así que funciona en grupos con LID.

let grupo_info = client.group_info(msg.chat()).await?;
if grupo_info.is_admin(msg.sender()) {
    client.reply(&msg, "Eres administrador").await?;
}

Crear y gestionar#

use soblendwa::ParticipantAction;

let nuevo = client.create_group("Equipo Soblend", &[Jid::phone("5215511111111")]).await?;
let resultados = client
    .update_participants(&nuevo.jid, &[Jid::phone("5215522222222")], ParticipantAction::Promote)
    .await?;
client.set_group_subject(&nuevo.jid, "Equipo").await?;
client.set_group_description(&nuevo.jid, Some("Hecho con SoblendWA")).await?;
client.set_group_picture(&nuevo.jid, std::fs::read("grupo.jpg")?).await?;
client.leave_group(&nuevo.jid).await?;

ParticipantAction puede ser Add, Remove, Promote o Demote. Cada resultado trae el jid y un status, parecido a un código HTTP: 200 significa que funcionó.

Ajustes#

Invitaciones#

let codigo = client.group_invite_code(&grupo).await?;
println!("https://chat.whatsapp.com/{codigo}");

let nuevo_codigo = client.revoke_group_invite(&grupo).await?;
let detalles = client.group_invite_info(&nuevo_codigo).await?;
let unido = client.join_group(&nuevo_codigo).await?;

accept_group_invite(remitente, invitación) acepta una tarjeta de invitación recibida por mensaje. Para enviar una, usa send_group_invite.

Solicitudes para entrar#

let solicitudes = client.group_join_requests(&grupo).await?;
let personas: Vec<Jid> = solicitudes.iter().map(|s| s.jid.clone()).collect();
client.respond_join_requests(&grupo, &personas, true).await?;

Cambios en vivo#

Event::GroupUpdate avisa de lo que cambia: group, author, action, participants y timestamp.

Cuando alguien sale de un grupo, SoblendWA rota la sender key para que esa persona no pueda leer lo que venga después.

Datos de GroupInfo#

let comunidad = client.create_community("Soblend", "Comunidad oficial").await?;
let subgrupo = client.create_community_group(&comunidad.jid, "Anuncios técnicos", &[]).await?;
let subgrupos = client.community_groups(&comunidad.jid).await?;

client.link_group(&comunidad.jid, &grupo).await?;
client.unlink_group(&comunidad.jid, &grupo).await?;
client.set_community_join_approval(&comunidad.jid, true).await?;
client.leave_community(&comunidad.jid).await?;

Una comunidad es un tipo de grupo, así que también funcionan las funciones de grupo, como group_info y update_participants. En GroupInfo, is_community indica si lo es, is_community_announce si es su grupo de anuncios y linked_parent a qué comunidad pertenece.

community_groups devuelve una lista de LinkedGroup con jid, subject, owner, created y size.

Para encuestas en grupos de anuncios, usa Message::announcement_poll.

Consultar y seguir#

let otro = client.newsletter_info_by_invite("https://whatsapp.com/channel/0029Va...").await?;
let mismo = client.newsletter_info(&otro.jid).await?;
client.newsletter_follow(&otro.jid).await?;
client.newsletter_mute(&otro.jid, true).await?;
client.newsletter_unfollow(&otro.jid).await?;

Leer y reaccionar#

for publicacion in client.newsletter_messages(&otro.jid, 20, None).await? {
    client.newsletter_react(&otro.jid, &publicacion.server_id, Some("🔥")).await?;
}

Los mensajes de canal que recibes traen msg.info.server_id, que es lo que usa newsletter_react. None quita tu reacción. newsletter_live_updates pide recibir en vivo los cambios del canal, y devuelve por cuántos segundos si WhatsApp lo indica.

Crear y administrar Experimental#

let canal = client.newsletter_create("Soblend News", Some("Novedades del estudio")).await?;
client.newsletter_update(&canal.jid, Some("Soblend"), None, None).await?;
let suscriptores = client.newsletter_subscribers(&canal.jid).await?;
let admins = client.newsletter_admin_count(&canal.jid).await?;
client.newsletter_demote(&canal.jid, &Jid::phone("5215511111111")).await?;
client.newsletter_change_owner(&canal.jid, &Jid::phone("5215522222222")).await?;
client.newsletter_delete(&canal.jid).await?;

Para publicar, envía un mensaje normal a su JID con send_message.

Datos#

Estas funciones usan el app state de WhatsApp, la lista de cambios que se sincroniza entre tus dispositivos. Cada parche se verifica con LTHash y MACs antes de aplicarse. Si falta una clave, se le pide al teléfono y la sincronización continúa sola cuando llega.

Organizar chats#

use std::time::Duration;

client.archive_chat(&chat, true).await?;
client.pin_chat(&chat, true).await?;
client.mute_chat(&chat, Some(Duration::from_secs(8 * 60 * 60))).await?;
client.mark_chat_read(&chat, true).await?;
client.clear_chat(&chat).await?;
client.delete_chat(&chat).await?;

await bot.modifyChat(chat, 'archive')
await bot.modifyChat(chat, 'pin')
await bot.modifyChat(chat, 'mute', 8 * 60 * 60)
await bot.modifyChat(chat, 'read')
await bot.modifyChat(chat, 'clear')
await bot.modifyChat(chat, 'delete')

await bot.modify_chat(chat, "archive")
await bot.modify_chat(chat, "pin")
await bot.modify_chat(chat, "mute", 8 * 60 * 60)
await bot.modify_chat(chat, "read")
await bot.modify_chat(chat, "clear")
await bot.modify_chat(chat, "delete")

await bot.modifyChat(chat, 'archive')
await bot.modifyChat(chat, 'pin')
await bot.modifyChat(chat, 'mute', 8 * 60 * 60)
await bot.modifyChat(chat, 'read')
await bot.modifyChat(chat, 'clear')
await bot.modifyChat(chat, 'delete')

Las acciones de modifyChat son archive, unarchive, pin, unpin, mute, unmute, read, unread, delete y clear. Si no indicas segundos, mute dura 8 horas.

Mensajes destacados y contactos#

client.star_message(&chat, &msg.info.id, false, true).await?;
client.save_contact(&Jid::phone("5215511111111"), "Ana Soblend").await?;
client.set_push_name("Mi Bot").await?;

Etiquetas Experimental#

client.edit_label("1", "Clientes VIP", 3).await?;
client.label_chat(&chat, "1", true).await?;
client.label_message(&chat, &msg.info.id, "1", true).await?;
client.delete_label("1").await?;

await bot.editLabel('1', 'Clientes VIP', 3)
await bot.labelChat(chat, '1')
await bot.labelMessage(chat, message, '1')
await bot.deleteLabel('1')

await bot.edit_label("1", "Clientes VIP", 3)
await bot.label_chat(chat, "1")
await bot.label_message(chat, message, "1")
await bot.delete_label("1")

await bot.editLabel('1', 'Clientes VIP', 3)
await bot.labelChat(chat, '1')
await bot.labelMessage(chat, message, '1')
await bot.deleteLabel('1')

Respuestas rápidas Experimental#

let id = client.save_quick_reply(None, "hola", "¡Hola! ¿En qué te ayudo?").await?;
client.delete_quick_reply(&id).await?;

const id = await bot.saveQuickReply('hola', '¡Hola! ¿En qué te ayudo?')

id = await bot.save_quick_reply("hola", "¡Hola! ¿En qué te ayudo?")

const id = await bot.saveQuickReply('hola', '¡Hola! ¿En qué te ayudo?')

Cualquier otro cambio#

chat_modify acepta todas las modificaciones, incluidas las que no tienen atajo.

use soblendwa::ChatModification;

client.chat_modify(&chat, ChatModification::RemoveContact).await?;
client.chat_modify(&chat, ChatModification::DeleteForMe {
    message_id: msg.info.id.clone(),
    from_me: msg.info.from_me,
    timestamp: msg.info.timestamp,
}).await?;

ChatModification puede ser Archive, Pin, Mute, MarkRead, Delete, Clear, Star, DeleteForMe, SaveContact, RemoveContact, Label o MessageLabel.

Cambios desde el teléfono#

Lo que cambies en el teléfono llega como Event::ChatUpdate { update, timestamp, initial_sync }. initial_sync indica si viene de la sincronización inicial.

use soblendwa::events::ChatUpdate;

if let Event::ChatUpdate { update: ChatUpdate::Archived { chat, archived }, .. } = event {
    println!("{chat} archivado: {archived}");
}

En JSON, los campos usan camelCase, como messageId o fullName.

Sincronizar a mano#

Normalmente no hace falta. client.sync_app_state(&COLLECTIONS, false) fuerza una sincronización, y COLLECTIONS contiene las colecciones que usa WhatsApp.

Activarlo#

use soblendwa::ChatStore;

let chats = ChatStore::open("session/chats.json").await?;
let (client, events) = Client::builder().store(store).chat_store(chats.clone()).build().await?;

const bot = await SoblendWA.create({ chatStore: { path: 'session/chats.json', limit: 500 } })

bot = await SoblendWA.create(chat_store={"path": "session/chats.json", "limit": 500})

soblendwa-server --session bot

El servidor lo activa por defecto, en una carpeta por cuenta. Se desactiva con --no-chat-store.

Consultar#

for chat in chats.chats() {
    println!("{} · {} sin leer", chats.name_of(&chat.jid).unwrap_or(chat.jid.to_string()), chat.unread);
}
let ultimos = chats.messages(&chat, 20);
let encontrados = chats.search("factura", 10);
let viejo = chats.message(&chat, "3EB0ABC...").unwrap();
client.reply(&viejo.to_event(), "respondiendo a un mensaje de ayer").await?;

const lista = bot.chats()
const contactos = bot.contacts()
const ultimos = bot.messages(chat, { limit: 20 })
const encontrados = bot.search('factura', 10)

lista = bot.chats()
contactos = bot.contacts()
ultimos = bot.messages(chat, 20)
encontrados = bot.search("factura", 10)

const lista = await bot.chats()
const contactos = await bot.contacts()
const ultimos = await bot.messages(chat, { limit: 20 })
const encontrados = await bot.search('factura', 10)

Qué guarda#

Se alimenta solo con mensajes entrantes y enviados, historial, recibos (enviado, entregado, leído, reproducido), reacciones, votos de encuestas, ediciones, borrados, cambios de app state, nombres de contactos y asuntos de grupos.

Guarda hasta 500 mensajes por chat, ajustable con ChatStore::open_with_limit. Se escribe a disco cada 10 segundos si hubo cambios, y al llamar client.disconnect(). La escritura es atómica, así que un corte de luz no deja el archivo a medias.

status puede ser Error, Pending, Sent, Delivered, Read o Played. Los métodos completos están en la referencia de ChatStore.

Historial#

Al vincular, el teléfono envía el historial en bloques, y cada uno llega como Event::HistorySync. También puedes pedir más.

let oldest = msg.key();
client.request_history(&chat, &oldest, msg.info.timestamp * 1000, 50).await?;

Pide entre 1 y 50 mensajes anteriores al indicado. El resultado llega como otro Event::HistorySync. request_placeholder_resend le pide al teléfono una copia de mensajes concretos que no se pudieron descifrar, y download_history descarga un bloque a partir de su notificación.

En JSON, historySync trae syncType, progress, chunkOrder, conversations, pushNames y lidMappings.

Foto de perfil#

let foto = client.profile_picture_url(&chat, true).await?;
client.set_profile_picture(None, std::fs::read("yo.jpg")?).await?;
client.remove_profile_picture(None).await?;

Con None cambias la tuya; con Some(&grupo) la de un grupo. La imagen puede ser JPEG, PNG, WebP o GIF de cualquier tamaño: se recorta al centro y se deja en 640×640. En Node.js y Python: bot.profilePicture(jid, fullSize) y bot.profile_picture(jid, full_size).

Información y nombre#

client.set_about("Hecho con SoblendWA").await?;
let infos = client.fetch_about(&[chat.clone()]).await?;
client.set_push_name("Mi Bot").await?;

Bloquear#

client.block(&chat).await?;
client.unblock(&chat).await?;
let bloqueados = client.blocklist().await?;

await bot.block(jid)
await bot.unblock(jid)

await bot.block(jid)
await bot.unblock(jid)

await bot.block(jid)
await bot.unblock(jid)

Privacidad#

use soblendwa::{PrivacySetting, PrivacyValue};

client.set_privacy(PrivacySetting::LastSeen, PrivacyValue::Contacts).await?;
let ajustes = client.privacy_settings().await?;

PrivacyValue puede ser Everyone, Contacts, ContactsExcept, Nobody, MatchLastSeen o Known. No todos los valores valen para todos los ajustes: WhatsApp rechaza las combinaciones que no admite.

Los cambios llegan como Event::PrivacyChanged y Event::BlocklistChanged, y los de otras personas como Event::PictureChanged y Event::AboutChanged. Experimental

Mensajes temporales#

client.set_disappearing(&chat, 7 * 24 * 60 * 60).await?;
client.set_default_disappearing(0).await?;
let modos = client.disappearing_modes(&[chat.clone()]).await?;

const modos = await bot.disappearingModes(chat)

modos = await bot.disappearing_modes(chat)

const modos = await bot.disappearingModes(chat)

Comprobar números#

let encontrados = client.on_whatsapp(&["5215511111111"]).await?;
let lid = client.lid_for_phone(&Jid::phone("5215511111111")).await?;
let telefono = client.phone_for_lid(&Jid::lid("100000000000001")).await?;

const encontrados = await bot.onWhatsApp('5215511111111')

encontrados = await bot.on_whatsapp("5215511111111")

const encontrados = await bot.onWhatsApp('5215511111111')

Cada resultado trae query, jid, exists y lid. phone_for_lid solo conoce los pares que WhatsApp ya compartió contigo.

Límites de la cuenta#

let limite = client.reachout_timelock().await?;
let cupo = client.new_chat_message_cap().await?;
let bots = client.bot_list().await?;

En línea#

client.set_presence(true).await?;
client.subscribe_presence(&chat).await?;

await bot.setOnline(true)

await bot.set_online(True)

await bot.setOnline(true)

Para saber si alguien está en línea, suscríbete y atiende Event::Presence { from, available, last_seen }. Con .online_on_connect(false) el bot no aparece en línea al conectar.

Escribiendo y grabando#

use soblendwa::ChatPresence;

client.send_chat_presence(&chat, ChatPresence::Composing).await?;
client.send_chat_presence(&chat, ChatPresence::Recording).await?;
client.send_chat_presence(&chat, ChatPresence::Paused).await?;

await bot.typing(chat, 'composing')
await bot.typing(chat, 'recording')
await bot.typing(chat, 'paused')

await bot.typing(chat, "composing")
await bot.typing(chat, "recording")
await bot.typing(chat, "paused")

await bot.typing(chat, 'composing')
await bot.typing(chat, 'recording')
await bot.typing(chat, 'paused')

Lo que hacen los demás llega como Event::ChatState { chat, sender, state }.

Llamadas#

use soblendwa::events::CallKind;

if let Event::Call(llamada) = event {
    if llamada.kind == CallKind::Offer {
        client.reject_call(&llamada.id, &llamada.from).await?;
    }
}
let enlace = client.create_call_link(true, None).await?;

Event::Call trae id, from, kind (Offer, Accept, Reject o Terminate), video, is_group y timestamp. En create_call_link, true significa video, y el segundo parámetro es una hora de inicio opcional en segundos Unix.

Catálogo y productos#

use soblendwa::business::{CatalogImage, ProductDraft};

let pagina = client.catalog(None, 10, None).await?;
let producto = client.product_create(&ProductDraft {
    name: Some("Taza Soblend".into()),
    price: Some(149_000),
    currency: Some("MXN".into()),
    images: vec![CatalogImage::Data(std::fs::read("taza.jpg")?)],
    ..Default::default()
}).await?;
client.product_update(&producto.id, &ProductDraft { hidden: Some(true), ..Default::default() }).await?;
client.product_delete(&[&producto.id]).await?;

Los precios van en milésimas, como en la app: 149_000 son 149,00. Las imágenes pueden ser bytes (CatalogImage::Data) o una URL (CatalogImage::Url). Para seguir paginando, pasa next_cursor como tercer parámetro de catalog.

Enviar un producto#

client.send_product(&chat, &mi_numero, &producto, &std::fs::read("taza.jpg")?, Some("¡Nuevo!")).await?;

Colecciones y pedidos#

let colecciones = client.catalog_collections(None, 10).await?;
let pedido = client.order_details("id-del-pedido", "token-del-pedido").await?;

Perfil de empresa#

use soblendwa::business::{BusinessHours, BusinessProfileUpdate, OpeningHours, Weekday};

client.update_business_profile(&BusinessProfileUpdate {
    email: Some("ventas@soblend.dev".into()),
    hours: Some(BusinessHours {
        timezone: "America/Mexico_City".into(),
        days: vec![(Weekday::Mon, OpeningHours::Between { open_minute: 9 * 60, close_minute: 18 * 60 })],
    }),
    ..Default::default()
}).await?;

let portada = client.set_business_cover_photo(std::fs::read("portada.jpg")?).await?;
client.remove_business_cover_photo(&portada).await?;
let perfil = client.business_profile(&chat).await?;

OpeningHours puede ser AllDay, ByAppointment o Between { open_minute, close_minute }, con los minutos contados desde la medianoche.

Datos#

Si WhatsApp bloquea la cuenta#

Se detiene y te dice por qué, sin borrar la sesión. Si desbloqueas la cuenta en el teléfono, vuelves a conectar sin escanear otro QR.

if let Event::AccountBlocked { code, reason, expires } = event {
    eprintln!("Bloqueada ({code}): {reason}. Hasta: {expires:?}");
}

Reconexión#

La espera crece y tiene un margen aleatorio, para que cien sesiones no se reconecten en el mismo milisegundo.

Se apaga con .auto_reconnect(false). El keepalive envía un ping cada 15 segundos y, si no hay respuesta en 8, reconecta. El servidor además escalona el arranque de las sesiones.

Límite de envíos#

Un bug que manda mensajes en bucle no se convierte en spam. Lo que pase el límite devuelve Error::RateLimited { chat, retry_after } y se cuenta en stats().rate_limited.

use soblendwa::SendLimit;

let limite = SendLimit { per_minute: 120, burst: 30, per_chat_per_minute: 20, per_chat_burst: 8 };
let (client, events) = Client::builder().store(store).send_limit(Some(limite)).build().await?;

.send_limit(None) lo desactiva. Bajar los límites reduce el riesgo, pero no hay ningún ritmo que garantice que WhatsApp no bloquee una cuenta.

Reinicios sin pérdidas#

Cada mensaje se guarda en un outbox hasta que WhatsApp confirma que lo recibió. Si se cae la conexión o reinicias el proceso, se reenvía al reconectar con el mismo id, y un mensaje que sigue en vuelo no se reenvía.

• client.pending_sends() muestra lo que está esperando: id, chat, queued_at y attempts.
• stats().outbox_resent cuenta los reenvíos.
• .outbox(false) lo desactiva.

Reintentos después de reiniciar#

Lo enviado se conserva hasta dos días, así un contacto que no pudo descifrar un mensaje puede pedirlo de nuevo aunque el bot se haya reiniciado.

Un fallo no tumba todo#

Si un handler entra en pánico, se registra, se cuenta en stats().panics y la sesión sigue. Cada sesión del servidor es independiente: si una se cuelga abriendo su almacenamiento, las demás siguen.

Recuperación de mensajes#

Si un mensaje no se puede descifrar, SoblendWA pide un reintento al remitente y una copia a tu teléfono a la vez. Cuando llega bien, emite Event::MessageRecovered. Esto está probado de punta a punta contra el WhatsApp falso, y aún falta confirmarlo con una cuenta real. Experimental

Tiempos por fase#

Cada Event::ServerAck trae timings, para saber dónde se fue el tiempo de un envío.

Un ServerAck con error trae el código de rechazo de WhatsApp. Uno sin timings suele ser una petición interna al teléfono.

Métricas#

let stats = client.stats();
println!("{} recibidos, {} enviados", stats.received, stats.sent);

const stats = bot.stats()

stats = bot.stats()

const stats = await bot.stats()

curl -X POST http://127.0.0.1:8787/api/bot/stats -H "Authorization: Bearer mi-clave"

Latencia#

let bot = msg.info.elapsed();
let red = client.latency();
let medido_ahora = client.ping().await?;

• msg.info.elapsed() mide cuánto lleva el mensaje dentro del bot, desde que llegó del socket. Incluye descifrarlo.
• client.latency() devuelve al instante la latencia de red medida en segundo plano.
• client.ping() hace una medición nueva y tarda un viaje de ida y vuelta.

La primera vez que el bot le escribe a un chat nuevo, tiene que pedir los dispositivos del destinatario y sus claves: uno o dos viajes de ida y vuelta, igual que WhatsApp Web. Después todo queda guardado y los envíos solo cuestan el cifrado local.

El tiempo que ves en el teléfono es la suma del viaje de tu teléfono a WhatsApp, unos 0,05 ms del bot, y el viaje de WhatsApp al bot y de vuelta. Esos viajes dependen de la distancia física y de tu conexión, y ningún código puede bajarlos de lo que permita la red.

Un bot completo contra zapo#

Un bot de eco de punta a punta. Los dos se conectan al mismo @zapo-js/fake-server con el protocolo real (Noise, vinculación por QR, Signal), cada uno en su propio proceso y con almacenamiento en memoria. zapo corre con su acelerador @zapo-js/native.

Las piezas, una por una#

Se midió en la misma máquina contra el código real de cada librería: whatsmeow del 2 de noviembre de 2026 con su libsignal v0.2.2 (Go 1.27.2) y Baileys 7.0.0-rc14 con su libsignal y su GroupCipher. Mismo stanza, mismo mensaje de 120 bytes y mismas operaciones; las tres librerías producen exactamente los mismos 3.375 bytes al codificar. SoblendWA serializa la sesión en cada mensaje; a whatsmeow y Baileys se les midió con los registros como objetos en memoria, que es su caso más rápido. whatsmeow serializando como su almacén SQL baja a 6.773 msg/s.

Puedes repetir lo nuestro:

cargo test --release -- --ignored throughput

Por qué es rápido#

Desde que llega un mensaje hasta que sale la respuesta, el bot tarda unos 0,05 ms en un chat conocido.

• Sin esperas de red en chats conocidos. Las sesiones, los dispositivos y los datos de los grupos se guardan en disco y se usan al instante, aunque reinicies el bot. Se actualizan en segundo plano y cuando WhatsApp avisa de un cambio. Al conectar se precargan tus grupos y los dispositivos de sus miembros.
• Grupos grandes rápidos desde el primer mensaje. Las consultas de claves y dispositivos salen en paralelo, en un solo viaje de red, y las sesiones Signal se crean usando todos los núcleos: 1000 dispositivos en unos 0,1 s en lugar de 0,4 s.
• Socket sin demoras. TCP_NODELAY evita que el sistema retenga mensajes pequeños. El lector y el escritor tienen cada uno su propio cifrador AES-GCM y no comparten locks.
• Arranque rápido. La versión de WhatsApp Web se recuerda y se actualiza en segundo plano.
• Almacenamiento sin bloqueos. FileStore escribe en un log de solo-escritura únicamente lo que cambió y compacta de vez en cuando. Los backends SQL y Redis agrupan las escrituras en segundo plano.
• Colas por chat. Los chats distintos van en paralelo y cada chat conserva su orden.
• Multimedia reutilizada. El mismo archivo no se vuelve a cifrar ni a subir.
• Sin código inseguro. #![forbid(unsafe_code)], y el decodificador binario está probado contra cientos de miles de entradas hostiles.

Elegir un store#

Los marcados como experimentales pasan sus pruebas locales, pero todavía no se han probado contra un servidor real.

Abrirlos#

use std::sync::Arc;
use soblendwa::store::{MongoStore, PostgresStore, RedisStore, SqliteStore};
use soblendwa::{FileStore, MemoryStore};

let archivos = FileStore::open("session").await?;
let memoria = Arc::new(MemoryStore::new());
let sqlite = Arc::new(SqliteStore::open_account("datos/bots.db", "ventas").await?);
let postgres = Arc::new(PostgresStore::connect_account("postgres://bot:clave@localhost/wa", "ventas").await?);
let redis = Arc::new(RedisStore::connect_account("redis://127.0.0.1/", "ventas").await?);
let mongo = Arc::new(MongoStore::connect_account("mongodb://localhost:27017", "wa", "ventas").await?);

let (client, events) = Client::builder().store(sqlite).build().await?;

const opciones = [
  { type: 'file', path: 'session' },
  { type: 'memory' },
  { type: 'sqlite', path: 'datos/bots.db', account: 'ventas' },
  { type: 'postgres', url: 'postgres://bot:clave@localhost/wa', account: 'ventas' },
  { type: 'redis', url: 'redis://127.0.0.1/', account: 'ventas' },
  { type: 'mongo', url: 'mongodb://localhost:27017', database: 'wa', account: 'ventas' },
]
const bot = await SoblendWA.create({ store: opciones[0] })

bot = await SoblendWA.create(store={"type": "sqlite", "path": "datos/bots.db", "account": "ventas"})

soblendwa-server --dir sessions
soblendwa-server --sqlite bots.db
soblendwa-server --memory
soblendwa-server --mongo mongodb://localhost:27017 --mongo-db wa

account permite guardar varias cuentas en la misma base. Con FileStore, usa una carpeta por cuenta. Si no indicas un store, Rust usa memoria, y Node.js y Python usan la carpeta session.

Las credenciales y las claves de la cuenta son secretos. Protege el acceso a tu base de datos y a tu carpeta de sesión como protegerías una contraseña.

Cómo funciona por dentro#

Todos los backends de Rust comparten el mismo núcleo, BatchedStore: las lecturas salen de memoria después de la primera vez, y las escrituras se agrupan en una sola transacción, o un solo pipeline en Redis, en segundo plano. Si una clave cambia mil veces antes de escribirse, solo se escribe el último valor. Enviar un mensaje nunca espera a la base de datos. client.disconnect() vacía lo pendiente antes de salir.

Store escrito en JavaScript#

Con el módulo de Node.js pasas un objeto con tus funciones y usas la base de datos que quieras. Las lecturas ya pasan por caché y las escrituras llegan agrupadas, así que no hace falta optimizar nada.

const store = {
  loadCreds: () => db.creds.findOne(),
  saveCreds: (json) => db.creds.save(json),
  get: (kind, key) => db.keys.get(`${kind}:${key}`),
  keys: (kind) => db.keys.list(kind),
  apply: (writes) => db.keys.bulk(writes),
}
const bot = await SoblendWA.create({ store })

En lugar de apply puedes dar set(kind, key, value), remove(kind, key) y clear(). Probado de punta a punta: vinculación, mensajes y reinicio con el mismo store.

Store escrito en Rust#

Implementa Backend, con cuatro métodos más list si quieres exportar a zapo, y envuélvelo en BatchedStore::new(tu_backend): la caché y el agrupado vienen gratis.

use async_trait::async_trait;
use soblendwa::store::{Creds, KeyKind, KeyWrite};
use soblendwa::{Backend, Result};

struct MiBaseDeDatos;

#[async_trait]
impl Backend for MiBaseDeDatos {
    async fn load_creds(&self) -> Result<Option<Creds>> {
        Ok(None)
    }

    async fn save_creds(&self, _creds: &Creds) -> Result<()> {
        Ok(())
    }

    async fn fetch(&self, _kind: KeyKind, _key: &str) -> Result<Option<Vec<u8>>> {
        Ok(None)
    }

    async fn apply(&self, _writes: &[KeyWrite]) -> Result<()> {
        Ok(())
    }
}

Si prefieres controlarlo todo, implementa directamente el trait Store, con load_creds, save_creds, get, set, remove, clear, y opcionalmente flush y keys.

Qué se guarda#

KeyKind indica el tipo de cada dato.

use std::time::Duration;
use soblendwa::{Client, Platform, SendLimit};

let (client, events) = Client::builder()
    .store(store)
    .device_name("SoblendWA")
    .platform(Platform::Desktop)
    .push_name("Mi Bot")
    .online_on_connect(false)
    .auto_reconnect(true)
    .query_timeout(Duration::from_secs(30))
    .send_limit(Some(SendLimit { per_minute: 120, burst: 30, per_chat_per_minute: 20, per_chat_burst: 8 }))
    .outbox(true)
    .media_cache(Some(Duration::from_secs(7 * 24 * 60 * 60)))
    .workers(16)
    .build()
    .await?;

Config tiene además connect_timeout (20 s) y keepalive_interval (15 s), que se cambian a través de .config(...).

En Node.js y Python#

Las opciones se pasan a SoblendWA.create. En Python usan snake_case, y se convierten solas.

send_limit, outbox, media_cache, workers y query_timeout solo se pueden cambiar desde Rust por ahora. En los demás lenguajes se usan los valores por defecto.

Registros#

SoblendWA escribe sus registros con tracing. En Rust, instala un suscriptor como tracing-subscriber. El servidor los muestra por defecto, y se ajustan con la variable RUST_LOG.

RUST_LOG=soblendwa=debug,soblendwa_server=info soblendwa-server

use soblendwa::Proxy;

let proxy = Proxy::parse("socks5://usuario:clave@127.0.0.1:1080")?;
let (client, events) = Client::builder().store(store).proxy(proxy).build().await?;

const bot = await SoblendWA.create({ proxy: 'socks5://usuario:clave@127.0.0.1:1080' })

bot = await SoblendWA.create(proxy="socks5://usuario:clave@127.0.0.1:1080")

soblendwa-server --proxy socks5://usuario:clave@127.0.0.1:1080

El usuario y la contraseña son opcionales. Pasan por el proxy el WebSocket, las subidas y descargas de multimedia, las vistas previas de enlaces y la consulta de la versión de WhatsApp Web. Se probó contra los servidores reales de WhatsApp a través de un SOCKS5 con usuario y contraseña.

Desde zapo con SQLite#

cargo run --release --example import_zapo --features sqlite -- ./auth/state.sqlite bot ./session

Convierte las credenciales, las sesiones Signal, incluidas las claves de mensajes que llegaron fuera de orden, las pre-keys, las sender keys de grupos, las claves y versiones de app state y los pares número ↔ LID de los contactos. La base de zapo se abre solo para leer: no se modifica.

Volver a zapo#

Si algo no te convence, escribe el estado actual de SoblendWA de vuelta en la base de zapo y sigue con tu bot de antes, con los ratchets al día.

cargo run --release --example import_zapo --features sqlite -- --rollback ./session ./auth/state.sqlite bot

Probado contra zapo-js 1.11 real, en los dos sentidos: zapo crea la base, SoblendWA la importa, descifra los mensajes pendientes y responde; los contactos de zapo descifran esas respuestas; tras el rollback, zapo sigue mandando y recibiendo mensajes privados y de grupo.

Desde tu código#

use soblendwa::store::{export_zapo_sqlite, import_zapo_sqlite, zapo_sessions};

let sesiones = zapo_sessions("auth/state.sqlite")?;
let destino = FileStore::open("session").await?;
let reporte = import_zapo_sqlite("auth/state.sqlite", "bot", destino.as_ref()).await?;
println!("{} sesiones, {} pre-keys", reporte.sessions, reporte.pre_keys);
export_zapo_sqlite(destino.as_ref(), "auth/state.sqlite", "bot").await?;

Desde zapo con MongoDB Experimental#

cargo run --release --example import_zapo --features "sqlite mongo" -- --mongo mongodb://localhost:27017 mi_base bot ./session
cargo run --release --example import_zapo --features "sqlite mongo" -- --rollback-mongo ./session mongodb://localhost:27017 mi_base bot

La conversión se probó con documentos que siguen el esquema exacto de @zapo-js/store-mongo, y descifra mensajes pendientes reales de zapo, pero todavía no contra un servidor MongoDB. Haz una copia de la base antes del rollback. Desde código: ZapoMongo::connect, import_zapo_mongo y export_zapo_mongo. Si usas un prefijo de colecciones, indícalo con .collection_prefix(...).

Desde Baileys#

cargo run --release --example import_baileys -- ./auth_info ./session

let store = FileStore::open("session").await?;
let reporte = soblendwa::store::import_baileys("auth_info", store.as_ref()).await?;
println!("{} sesiones, {} claves de grupo", reporte.sessions, reporte.sender_keys);

const { importBaileys } = require('soblendwa-node')
const report = await importBaileys('./auth_info', { type: 'sqlite', path: 'session/auth.db' })

from soblendwa import import_baileys

report = await import_baileys("./auth_info", type="sqlite", path="session/auth.db")

Convierte las credenciales, las sesiones Signal de libsignal-node, las pre-keys, las sender keys de grupos, las claves y versiones de app state y los mapeos número ↔ LID. Las listas de dispositivos y los tokens se vuelven a pedir solos. El bot sigue vinculado, y los chats en curso siguen cifrándose con las mismas sesiones.

El reporte trae me, sessions, pre_keys, sender_keys, app_state_keys, app_state_versions, lid_mappings, skipped y failed. Revisa failed por si algo no se pudo convertir.

Equivalencias con Baileys#

Cada función pública de Baileys 7 tiene su equivalente.

WhatsApp falso#

FakeWhatsApp (feature testing) es un servidor de WhatsApp en memoria que habla el protocolo real: handshake Noise con su propia cadena de certificados, nodos binarios, reparto de pre-keys, USync, grupos con sender keys, acks, recibos y mensajes guardados para cuentas desconectadas. Las cuentas son clientes SoblendWA normales, así que prueba tu bot completo, cifrado incluido.

use soblendwa::testing::FakeWhatsApp;
use soblendwa::Event;

let fake = FakeWhatsApp::start().await?;
let (bot, mut eventos) = fake.connect("5215511111111").await?;
let (ana, _) = fake.connect("5215522222222").await?;

ana.send_text(&FakeWhatsApp::jid("5215511111111"), "!ping").await?;
while let Some(evento) = eventos.recv().await {
    if let Event::Message(msg) = evento {
        assert_eq!(msg.text(), Some("!ping"));
        break;
    }
}

Simula también la subida y descarga de multimedia, y permite provocar fallos.

Desde otros lenguajes#

Levanta el servidor contra el WhatsApp falso. Cada sesión recibe un número de prueba, y tu bot se conecta igual que siempre.

soblendwa-server --fake --session bot --session ana

import { connect } from 'soblendwa-client'

const bot = await connect('ws://127.0.0.1:8787', { session: 'bot' })
const ana = await connect('ws://127.0.0.1:8787', { session: 'ana' })

bot.on('message', (message) => console.log(message.text))

Nada sale de tu máquina y las sesiones viven en memoria.

Contra un servidor falso de otros#

SoblendWA también pasa contra @zapo-js/fake-server: handshake Noise y certificado, vinculación por QR con firma ADV, mensajes privados y de grupo. Desde Node.js:

const bot = await SoblendWA.create({ server: { wsUrl: servidor.url, noiseRootHex: raiz } })

Las pruebas del proyecto#

cargo test --features "sqlite mongo testing" --lib
cargo test -p soblendwa-server
cargo test --release -- --ignored throughput
cargo test -p soblendwa-server -- --ignored

Incluye pruebas de robustez del decodificador binario: cientos de miles de entradas aleatorias y mutadas, anidamiento hostil y bombas de compresión. Ninguna entrada puede provocar un pánico, un desbordamiento de pila ni agotar la memoria.

El CI de GitHub corre formato, clippy y todas las pruebas en Linux, Windows y macOS, compila con Rust 1.89, y levanta el servidor con --fake para pasarle el harness desde JavaScript.

Bot de pruebas en vivo#

cargo run --release --example bot dibuja el QR en la terminal y responde unos 30 comandos, uno por función. Escribe !ayuda desde otro número. Si un comando falla, el error te llega como respuesta en el mismo chat.

La sesión se guarda en ./session, o en la carpeta que le pases: --example bot -- mi-carpeta.

Pruebas de días#

node clients/js/soak.mjs --sessions bot,ana --hours 72 --pid 12345

Manda texto y multimedia entre cuentas vinculadas durante días, y escribe cada minuto en soak.jsonl la memoria por proceso, los mensajes perdidos, los que no se pudieron descifrar, las reconexiones y las métricas de cada cuenta. Con --webhook avisa en cuanto aparece un mensaje sin descifrar o un bloqueo. Para medir la memoria por cuenta, corre un servidor por cuenta y pasa --pid cuenta=pid.

Canario diario#

cargo run --release --example canary -- ./sesion-prueba-a ./sesion-prueba-b

Conecta dos cuentas de prueba, manda un texto y una imagen de una a otra, comprueba que se descifran y que la imagen descargada es idéntica, y revisa ping, mensajes sin descifrar y pánicos. Con SOBLENDWA_ALERT_WEBHOOK (Discord, Slack o cualquier webhook JSON) avisa si algo falla. Prográmalo una vez al día con cron, un timer de systemd o el Programador de tareas, para enterarte el mismo día si WhatsApp cambió algo.

El cifrado Signal, el códec binario, el socket y el almacenamiento corren en Rust. JavaScript solo recibe eventos y llama métodos, así que el bot no se frena por el recolector de basura ni por el hilo de eventos de Node.js.

Crear el cliente#

const { SoblendWA } = require('soblendwa-node')

async function main() {
  const bot = await SoblendWA.create({
    store: { type: 'sqlite', path: 'session/auth.db' },
    pushName: 'Mi Bot',
  })

  bot.on('qr', ({ code }) => console.log('Escanea:', code))
  bot.on('connected', () => console.log('Conectado como', bot.me))
  bot.on('message', async (message) => {
    if (message.info.fromMe) return
    if (message.text === '!ping') await bot.reply(message, `Pong\n${bot.elapsed(message).toFixed(2)} ms`)
  })

  await bot.connect()
}

main()

Con TypeScript es igual, y los tipos vienen en index.d.ts. Las opciones de create están en Configuración.

Eventos#

SoblendWA es un EventEmitter. Cada evento se emite por su type, y también como event, y los errores de los handlers como error.

bot.on('event', (event) => console.log(event.type))
bot.on('error', (error) => console.error(error))

async function recorrer() {
  for await (const event of bot.events()) {
    console.log(event.type)
  }
}

Métodos#

chat acepta un JID completo o solo el número. message acepta el objeto recibido o su id.

Funciones del paquete#

Stores#

Además de los stores incluidos, puedes escribir el tuyo en JavaScript.

Los métodos son corrutinas normales de Python: se usan con await, sin hilos ni callbacks.

Crear el cliente#

import asyncio
from soblendwa import SoblendWA


async def main():
    bot = await SoblendWA.create(store={"type": "sqlite", "path": "session/auth.db"}, push_name="Mi Bot")

    @bot.on("qr")
    def qr(event):
        print("Escanea:", event["code"])

    @bot.on("message")
    async def answer(message):
        if message["info"]["fromMe"]:
            return
        if message["text"] == "!ping":
            await bot.reply(message, f"Pong\n{bot.elapsed(message):.2f} ms")

    await bot.run()


asyncio.run(main())

Las opciones de create usan snake_case y se convierten solas. Están en Configuración. Las opciones anidadas también, como link_previews={"timeout_ms": 2000}.

Eventos#

@bot.on("tipo") registra un handler, que puede ser normal o async. "event" recibe todos. bot.run() conecta y atiende los eventos hasta que la sesión termine.

Si prefieres manejar el bucle tú mismo:

await bot.connect()
async for event in bot.events():
    print(event["type"])

Los eventos son diccionarios con los mismos campos que en JSON, en camelCase, como message["info"]["fromMe"].

Métodos#

chat acepta un JID completo o solo el número. message acepta el diccionario recibido o su id.

Funciones del paquete#

Funciona en Node.js 18+, Bun, Deno y el navegador. En Node.js 22+, Bun y Deno usa el WebSocket incluido; en Node.js 18 a 21 instala ws.

Conectar#

import { connect } from 'soblendwa-client'

const bot = await connect('ws://127.0.0.1:8787', { session: 'ventas', token: 'mi-clave' })

bot.on('message', async (message) => {
  if (message.info.fromMe) return
  if (message.text === '!ping') {
    const ms = await bot.elapsed(message)
    await bot.reply(message, `Pong\n${ms.toFixed(2)} ms`)
  }
})

Si te desconectas del servidor, el cliente se reconecta solo, con una espera creciente de hasta 30 segundos. WhatsApp sigue conectado en el servidor mientras tanto, así que no se pierde la sesión.

Eventos#

bot.on('qr', ({ code }) => console.log(code))
bot.on('connected', () => console.log('En línea'))
bot.on('lagged', (missed) => console.warn('Perdí', missed, 'eventos'))
bot.on('error', (error) => console.error(error))

async function recorrer() {
  for await (const event of bot.events()) {
    console.log(event.type)
  }
}

Además de los eventos de WhatsApp, el cliente emite open, close, lagged y error. lagged avisa de que tu bot iba tan lento que el servidor descartó eventos.

Varias cuentas#

Cada sesión es una cuenta distinta, y el servidor las maneja todas a la vez.

const ventas = await connect(url, { session: 'ventas', token })
const soporte = await connect(url, { session: 'soporte', token })

Métodos#

Los mismos que el módulo de Node.js, con todo asíncrono, porque cada llamada viaja al servidor. También tiene status(), read(message), close() y call(método, parámetros) para cualquier otro.

const estado = await bot.status()
await bot.read(message)
const resultado = await bot.call('sendText', { chat: '5215512345678', text: 'hola' })
bot.close()

sendMedia y compañía mandan los bytes por el WebSocket, en base64. sendFile y downloadToFile usan rutas del servidor y son la opción para archivos grandes. bytes puede ser un Uint8Array, un ArrayBuffer o un texto en base64.

Un solo servidor maneja varias cuentas a la vez, y usó unos 14 MB de RAM con dos cuentas contra el WhatsApp falso.

Arrancarlo#

soblendwa-server --token mi-clave --session ventas --session soporte

La primera vez muestra el QR de cada cuenta en la terminal. Para reutilizar una sesión que ya vinculaste con el bot de ejemplo, usa --dir . --session session.

Opciones#

El nombre de una sesión tiene de 1 a 64 caracteres: letras, números, - y _. Los registros se ajustan con RUST_LOG.

Autenticación#

Con --token, cada petición debe llevar la clave de una de estas formas:

• La cabecera Authorization: Bearer mi-clave.
• El parámetro ?token=mi-clave.

Sin clave o con una incorrecta, responde 401 con {"error":{"message":"missing or wrong token"}}.

Rutas HTTP#

curl -X POST http://127.0.0.1:8787/api/ventas/sendText \
  -H "Authorization: Bearer mi-clave" \
  -d '{"chat":"5215512345678","text":"Hola desde curl"}'

Protocolo WebSocket#

Al conectar a ws://host:8787/ws/<cuenta>?token=… llega primero el saludo y, si hay un QR pendiente, el evento qr.

{ "type": "hello", "session": "ventas", "me": "5215512345678:3@s.whatsapp.net", "connected": true, "methods": ["status", "sendText"] }

Después llegan los eventos:

{ "session": "ventas", "event": { "type": "message", "text": "hola" } }

Para llamar un método, envía un id tuyo, y la respuesta trae el mismo. Las llamadas se atienden en paralelo, así que las respuestas pueden llegar en otro orden.

{ "id": 1, "method": "sendText", "params": { "chat": "5215512345678", "text": "hola" } }

{ "id": 1, "result": "3EB0ABC123" }

{ "id": 1, "error": { "message": "missing parameter \"text\"" } }

Si un cliente va tan lento que el servidor descarta eventos, recibe {"type":"lagged","missed":N}. El búfer guarda hasta 4.096 eventos por cuenta.

Webhooks#

Con --webhook, cada evento se envía por POST a tu URL, con el mismo JSON que en el WebSocket y un límite de 10 segundos. Si hay --token, va en la cabecera Authorization, y conviene que lo revises para saber que el aviso viene de tu servidor. Si la entrega falla, se registra en los logs y no se reintenta.

const http = require('node:http')

http.createServer((request, response) => {
  if (request.headers.authorization !== 'Bearer mi-clave') {
    response.writeHead(401).end()
    return
  }
  let body = ''
  request.on('data', (chunk) => (body += chunk))
  request.on('end', () => {
    const { session, event } = JSON.parse(body)
    console.log(session, event.type)
    response.writeHead(200).end()
  })
}).listen(3000)

Métodos disponibles#

Son los mismos por WebSocket y por HTTP. chat acepta un JID o solo el número. messageId es el id de un mensaje reciente o guardado en el store de chats. Los bytes viajan en base64.

Ejemplos en otros lenguajes#

import requests

requests.post(
    "http://127.0.0.1:8787/api/ventas/sendText",
    headers={"Authorization": "Bearer mi-clave"},
    json={"chat": "5215512345678", "text": "Hola"},
)

<?php
$context = stream_context_create(["http" => [
    "method" => "POST",
    "header" => "Authorization: Bearer mi-clave\r\nContent-Type: application/json",
    "content" => json_encode(["chat" => "5215512345678", "text" => "Hola"]),
]]);
echo file_get_contents("http://127.0.0.1:8787/api/ventas/sendText", false, $context);

body := strings.NewReader(`{"chat":"5215512345678","text":"Hola"}`)
request, _ := http.NewRequest("POST", "http://127.0.0.1:8787/api/ventas/sendText", body)
request.Header.Set("Authorization", "Bearer mi-clave")
response, err := http.DefaultClient.Do(request)

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer mi-clave");
var body = new StringContent("{\"chat\":\"5215512345678\",\"text\":\"Hola\"}");
var response = await http.PostAsync("http://127.0.0.1:8787/api/ventas/sendText", body);

La página también está en el buscador: pulsa Ctrl K y escribe el nombre de un método.

Crear y conectar#

Estado#

Enviar#

Vista previa de enlaces#

Multimedia#

Archivos grandes#

Recibos#

Encuestas y eventos#

Grupos#

Comunidades Experimental#

Canales#

Chats y app state#

Historial#

Perfil y privacidad#

Cuentas#

Presencia y llamadas#

Empresa Experimental#

Bajo nivel#

Para lo que la librería aún no cubre. Un error aquí puede hacer que WhatsApp cierre la conexión.

Message admite From<&str> y From<String>, por eso client.reply(&msg, "hola") funciona.

Crear#

Interactivos#

Modificar#

Leer#

Mensajes recibidos#

Botones#

Jid tiene tres campos públicos: user, device y server. También implementa Display y FromStr, así que puedes usar to_string() y parse().

Grupos#

Proxy#