# WhatsApp Business API

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

Fuente: https://ardumaker.com/docs/whatsapp-business-api/

- 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`

## ¿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](https://ardumaker.com/docs/webhooks-whatsapp).
- 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?

1. **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.
2. **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.
3. **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.
4. **Recepción.** El proveedor avisa a ArduMaker de cada mensaje entrante y de cada cambio de estado; ArduMaker los guarda en el [historial](https://ardumaker.com/docs/historial-de-chats).

### 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

**Mensaje saliente**

```text
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)
```

## 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.

> **PRECAUCION:** Las credenciales de API de un número solo las ve un admin de la empresa, a pedido, y queda registrado quién las miró.

## 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](https://ardumaker.com/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` |

> **PRECAUCION:** `simular_mensaje_sandbox_whatsapp` entrega el mensaje a los webhooks reales de la cuenta. Lo que contesta el bot del cliente llega marcado como contenido no confiable.

## Funciones relacionadas

- [Webhooks de WhatsApp](https://ardumaker.com/docs/webhooks-whatsapp/)
- [Historial de chats](https://ardumaker.com/docs/historial-de-chats/)
- [Consumo de servicios](https://ardumaker.com/docs/consumo-de-servicios/)
- [Router IA](https://ardumaker.com/docs/router-ia/)
- [Empresas](https://ardumaker.com/docs/empresas/)