WhatsApp Business API

Enviar y recibir WhatsApp desde los números de la empresa, con sandbox de pruebas y transcripción de audios.

Categoría: Comunicación
Estado: Disponible
Requisitos: Una empresa en ArduMaker con acceso de miembro o admin; Un número de WhatsApp ya habilitado, que un admin suma a la cuenta
Herramientas MCP (Solo leen): listar_numeros_whatsapp, listar_numeros_sandbox_whatsapp, ver_numero_sandbox_whatsapp, listar_chat_sandbox_whatsapp
Herramientas MCP (Escriben o modifican): configurar_transcripcion_whatsapp, crear_numero_sandbox_whatsapp, editar_numero_sandbox_whatsapp, simular_mensaje_sandbox_whatsapp, simular_estado_sandbox_whatsapp
Herramientas MCP (Destructivas): eliminar_numero_sandbox_whatsapp

Markdown

¿Qué permite hacer?

Una cuenta de WhatsApp por empresa, con su subcuenta del proveedor (Twilio).
Enviar texto, archivos y plantillas desde un número, con la misma forma de pedido que Twilio.
Recibir mensajes y reenviarlos a un sistema propio con webhooks.
Probar un bot con contactos de sandbox, sin teléfono y sin que nada salga al proveedor.
Transcribir a texto los audios y notas de voz que llegan.

¿Cuándo conviene usarlo?

Para atender o vender por WhatsApp con un bot propio, o para integrar los mensajes de la empresa con otro sistema.

¿Cómo funciona en ArduMaker?

Cuenta. La primera vez que la empresa abre WhatsApp, ArduMaker pide al proveedor una subcuenta y recién entonces guarda la cuenta. Si el proveedor falla, no queda nada a medias.
Números. Un admin de la empresa suma cada número con su teléfono y, si tiene, sus credenciales de API. Una empresa nueva o sin un pago validado tiene hasta 5 números activos.
Envío. Se envía con la sesión de la persona o con la cabecera Twilio-Api-Sid del número. ArduMaker guarda el mensaje y sus archivos y reenvía el pedido al proveedor; la respuesta es la del proveedor.
Recepción. El proveedor avisa a ArduMaker de cada mensaje entrante y de cada cambio de estado; ArduMaker los guarda en el historial.

Sandbox de pruebas

Un contacto de sandbox es una fila, no una línea: no tiene tope ni costo. Sin número explícito se genera uno en el rango +999, reservado por la ITU. Un envío a un contacto de sandbox hace todo lo normal pero se saltea el pedido al proveedor, responde sandbox: true y el chat queda marcado como prueba.

Transcripción de audios

Se activa por número. Solo audio y notas de voz: el texto queda en el mensaje con el prefijo [transcripcion]: . Hay hasta 10 intentos seguidos con espera creciente; si se agotan, el mensaje queda failed y se puede reintentar a mano.

¿Qué cambia realmente?

En el proveedor: una subcuenta por empresa.
En ArduMaker: la cuenta, sus números, las conversaciones, los mensajes y los archivos recibidos o enviados.
En la facturación: el uso del proveedor se sincroniza y se cobra como consumo de la empresa.

Esquema

Panel, bot o agente: sesión o Twilio-Api-Sid
API de WhatsApp de ArduMaker: guarda mensaje y archivos
¿Contacto de sandbox?: sí: no sale
Twilio: entrega en WhatsApp

Mensaje saliente

Resultado esperado

Los mensajes salen y entran por el número de la empresa y quedan en su historial. Con sandbox, un bot se prueba de punta a punta sin un teléfono.

Errores y resolución

424 `dependencia_caida` o `proveedor_no_configurado` al abrir la cuenta: el proveedor no creó la subcuenta. Es seguro reintentar: se vuelve a pedir.
`numero_repetido`: ese teléfono ya está en la cuenta.
Límite de 5 números: se libera cuando la empresa tiene más de 7 días y al menos un pago autorizado.
Error del proveedor al enviar: se devuelve el mismo código y cuerpo que respondió Twilio.
Transcripción `failed`: el motivo queda en el mensaje; se reintenta a mano desde el chat.

Relación con MCP

Por MCP no se envían mensajes reales: las herramientas listan los números y trabajan sobre el sandbox. configurar_transcripcion_whatsapp es solo para admins de la empresa. Ver /mcp/docs.

Tipo	Herramientas
Lectura	`listar_numeros_whatsapp`, `listar_numeros_sandbox_whatsapp`, `ver_numero_sandbox_whatsapp`, `listar_chat_sandbox_whatsapp`
Modifican	`crear_numero_sandbox_whatsapp`, `editar_numero_sandbox_whatsapp`, `simular_mensaje_sandbox_whatsapp`, `simular_estado_sandbox_whatsapp`, `configurar_transcripcion_whatsapp`
Destructiva	`eliminar_numero_sandbox_whatsapp`