osky

Voz real en WhatsApp: integra notas de voz bidireccionales con OpenClaw paso a paso

Voz real en WhatsApp: integra notas de voz bidireccionales con OpenClaw paso a paso
Tema OpenClaw WhatsApp Voice Notes

Voz real en WhatsApp con OpenClaw: de cero a produccion

Si llevas tiempo construyendo bots para WhatsApp sabes el dolor: la API oficial de Meta te da acceso limitado, Baileys te funciona hasta que no, y el soporte de audio siempre fue el primo feo de la fiesta. OpenClaw cambio eso. Segun la comparativa publicada en zenvanriel.com, el canal de WhatsApp de OpenClaw no solo soporta notas de voz entrantes y salientes, sino que lo hace a la par de Telegram, que históricamente era el rey indiscutible de la experiencia de bots con audio. Este tutorial te explica exactamente como montarlo, sin rodeos.

Diagrama de flujo de audio entre usuario y bot OpenClaw

Que es OpenClaw y por que importa en 2026

OpenClaw es un framework de canales unificados para bots conversacionales. La idea es simple: defines tu logica de bot una vez y la conectas a multiples canales (Telegram, WhatsApp, Signal, Discord) con adaptadores estandarizados. Lo relevante aqui es que su adaptador de WhatsApp no usa el enfoque de bot API oficial de Telegram — en cambio, trabaja sobre la WhatsApp Cloud API de Meta con extensiones propias para manejar objetos de audio de forma nativa.

Esto significa que puedes:

  • Recibir una nota de voz del usuario como objeto de audio procesable
  • Transcribirla, analizarla o rutearla en tu pipeline
  • Responder con otra nota de voz generada (TTS o archivo pre-grabado)
  • Todo dentro del mismo hilo de conversacion, sin hacks raros

Requisitos previos

Antes de tocar codigo, asegurate de tener esto en orden:

  1. Cuenta de Meta for Developers con una app configurada y el producto WhatsApp habilitado
  2. Numero de telefono verificado en WhatsApp Business Platform (no el numero personal, uno dedicado)
  3. OpenClaw >= 0.9.4 — las versiones anteriores tienen el adaptador de WhatsApp sin soporte de voz completo
  4. Node.js >= 20 o Python >= 3.11 segun el SDK que uses
  5. Webhook publico — puedes usar ngrok en desarrollo, pero en produccion necesitas HTTPS real
  6. Credenciales de un proveedor TTS si vas a generar respuestas de voz (ElevenLabs, Azure Speech, Google TTS — lo que prefieras)

Paso 1: Instala OpenClaw y el adaptador de WhatsApp

# Con npm
npm install @openclaw/core @openclaw/channel-whatsapp

# O con pip si prefieres Python
pip install openclaw openclaw-channel-whatsapp

Verifica la version del adaptador:

npm list @openclaw/channel-whatsapp
# Debe mostrar >= 0.9.4

Paso 2: Configura el canal de WhatsApp

Crea tu archivo de configuracion principal. En JavaScript:

// bot.config.js
import { OpenClaw } from '@openclaw/core';
import { WhatsAppChannel } from '@openclaw/channel-whatsapp';

const bot = new OpenClaw({
  channels: [
    new WhatsAppChannel({
      phoneNumberId: process.env.WA_PHONE_NUMBER_ID,
      accessToken: process.env.WA_ACCESS_TOKEN,
      verifyToken: process.env.WA_VERIFY_TOKEN,
      voiceSupport: {
        enabled: true,
        inbound: true,   // recibir notas de voz
        outbound: true,  // enviar notas de voz
        format: 'ogg',   // WhatsApp usa ogg/opus internamente
      },
    }),
  ],
});

export default bot;

Advertencia de produccion: el accessToken de Meta expira. Usa tokens de sistema (System User Token) con permisos whatsapp_business_messaging y whatsapp_business_management. Los tokens de usuario personal te van a quemar en produccion cuando menos lo esperes.

Paso 3: Registra tu webhook en Meta

En el panel de Meta for Developers:

  1. Ve a tu app > WhatsApp > Configuracion
  2. En "Webhook", ingresa tu URL publica: https://tudominio.com/webhook/whatsapp
  3. El verify token debe coincidir con WA_VERIFY_TOKEN en tu .env
  4. Suscribete a los campos: messages, message_reactions (opcional)

OpenClaw expone el endpoint automaticamente cuando inicias el servidor:

// server.js
import bot from './bot.config.js';

bot.start({ port: 3000 });
// Webhook disponible en: http://localhost:3000/webhook/whatsapp

Paso 4: Maneja notas de voz entrantes

Aqui esta la parte buena. OpenClaw normaliza el objeto de audio para que no tengas que lidiar con el formato raw de Meta:

bot.on('voice', async (ctx) => {
  const { audioUrl, mimeType, duration } = ctx.message.voice;

  // audioUrl ya tiene el token de descarga resuelto
  const audioBuffer = await fetch(audioUrl).then(r => r.arrayBuffer());

  // Ejemplo: transcribir con Whisper
  const transcript = await transcribeWithWhisper(audioBuffer);

  // Responder con texto
  await ctx.reply(`Escuche esto: "${transcript}"`);

  // O responder con otra nota de voz
  const responseAudio = await generateVoiceResponse(transcript);
  await ctx.replyVoice(responseAudio, { mimeType: 'audio/ogg' });
});

Nota importante: WhatsApp solo acepta audio en formato OGG con codec Opus para notas de voz salientes. Si tu TTS genera MP3 o WAV, necesitas convertir antes de enviar. Usa ffmpeg en tu pipeline:

import { execSync } from 'child_process';

function convertToOggOpus(inputPath, outputPath) {
  execSync(
    `ffmpeg -i ${inputPath} -c:a libopus -b:a 32k ${outputPath}`,
    { stdio: 'ignore' }
  );
}

Paso 5: Respuestas de voz con TTS

Ejemplo completo con ElevenLabs:

import ElevenLabs from 'elevenlabs-node';

const eleven = new ElevenLabs({ apiKey: process.env.ELEVENLABS_KEY });

async function generateVoiceResponse(text) {
  const audioStream = await eleven.textToSpeechStream({
    voiceId: 'tu_voice_id',
    text,
    modelId: 'eleven_multilingual_v2',
  });

  // Convierte el stream a buffer
  const chunks = [];
  for await (const chunk of audioStream) chunks.push(chunk);
  const mp3Buffer = Buffer.concat(chunks);

  // Convierte a OGG Opus para WhatsApp
  // (aqui usarias tu funcion de ffmpeg o un wrapper)
  return convertBufferToOggOpus(mp3Buffer);
}

Paso 6: Prueba el flujo completo en desarrollo

# Terminal 1: levanta el bot
node server.js

# Terminal 2: expone el webhook con ngrok
ngrok http 3000

# Actualiza la URL del webhook en Meta con la URL de ngrok
# Manda una nota de voz desde tu WhatsApp al numero de prueba
# Verifica los logs

Advertencias criticas de produccion

  • Rate limits de Meta: WhatsApp Cloud API tiene limites por numero de telefono. Si mandas muchas notas de voz salientes en poco tiempo, te bloquean temporalmente. Implementa una cola con BullMQ o similar.
  • Tamano de audio: Meta rechaza archivos de audio mayores a 16 MB. Si tu TTS genera audios largos, cortalos.
  • Ventana de 24 horas: Solo puedes enviar mensajes (incluyendo voz) dentro de las 24 horas posteriores al ultimo mensaje del usuario, a menos que uses plantillas aprobadas.
  • No uses numeros personales en produccion: Usa numeros dedicados de Business. Los personales se pueden banear sin previo aviso.
  • Logs de audio: No loguees los buffers de audio completos. Solo metadata. Tu equipo de seguridad te lo va a agradecer.

Conclusion

OpenClaw le quito el pretexto a quien decia que WhatsApp no soportaba bots de voz como Telegram. Hoy en 2026, con el adaptador correcto y la configuracion adecuada, puedes tener un bot que recibe notas de voz, las procesa y responde con audio generado, todo en el mismo hilo de WhatsApp que tus usuarios ya usan a diario. El flujo es limpio, la documentacion de OpenClaw es decente y los gotchas estan bien documentados si sabes donde buscar. Ahora no hay excusa.