# WhatsApp Business API

Send and receive WhatsApp from the company's numbers, with a test sandbox and audio transcription.

Source: https://ardumaker.com/en/docs/whatsapp-business-api/

- Category: Communication
- Status: Available
- Requirements: A company in ArduMaker where you are a member or admin; An already enabled WhatsApp number, added to the account by an admin
- MCP tools (Read only): `listar_numeros_whatsapp`, `listar_numeros_sandbox_whatsapp`, `ver_numero_sandbox_whatsapp`, `listar_chat_sandbox_whatsapp`
- MCP tools (Write or modify): `configurar_transcripcion_whatsapp`, `crear_numero_sandbox_whatsapp`, `editar_numero_sandbox_whatsapp`, `simular_mensaje_sandbox_whatsapp`, `simular_estado_sandbox_whatsapp`
- MCP tools (Destructive): `eliminar_numero_sandbox_whatsapp`

## What can you do with it?

- One WhatsApp account per company, with its own provider (Twilio) subaccount.
- Send text, files and templates from a number, with the same request shape as Twilio.
- Receive messages and forward them to your own system with [webhooks](https://ardumaker.com/en/docs/webhooks-whatsapp).
- Test a bot with sandbox contacts, without a phone and without anything reaching the provider.
- Transcribe incoming audio and voice notes to text.

## When should you use it?

To serve or sell over WhatsApp with your own bot, or to integrate the company's messages with another system.

## How does it work in ArduMaker?

1. **Account.** The first time the company opens WhatsApp, ArduMaker requests a subaccount from the provider and only then saves the account. If the provider fails, nothing is left half-done.
2. **Numbers.** A company admin adds each number with its phone and, if available, its API credentials. A new company, or one without a validated payment, can have up to 5 active numbers.
3. **Sending.** You send with the person's session or with the number's `Twilio-Api-Sid` header. ArduMaker stores the message and its files and forwards the request to the provider; the response is the provider's.
4. **Receiving.** The provider notifies ArduMaker of each incoming message and status change; ArduMaker stores them in the [history](https://ardumaker.com/en/docs/historial-de-chats).

### Test sandbox

A sandbox contact is a row, not a line: it has no cap and no cost. Without an explicit number, one is generated in the `+999` range, reserved by the ITU. Sending to a sandbox contact does everything as usual but skips the provider call, answers `sandbox: true` and the chat is flagged as a test.

### Audio transcription

It is enabled per number. Audio and voice notes only: the text is stored in the message with the `[transcripcion]: ` prefix. There are up to 10 consecutive attempts with growing waits; if they run out, the message is `failed` and can be retried manually.

## What actually changes?

- At the provider: one subaccount per company.
- In ArduMaker: the account, its numbers, conversations, messages and received or sent files.
- In billing: provider usage is synced and charged as company consumption.

## Diagram

**Outgoing message**

```text
Panel, bot or agent (session or Twilio-Api-Sid)
  ↓
ArduMaker WhatsApp API (stores message and files)
  ↓
Sandbox contact? (yes: it does not go out)
  ↓
Twilio (delivers on WhatsApp)
```

## Expected result

Messages go out and come in through the company number and stay in its history. With the sandbox, a bot is tested end to end without a phone.

## Errors and troubleshooting

- **424 `dependencia_caida` or `proveedor_no_configurado` when opening the account**: the provider did not create the subaccount. Safe to retry: it is requested again.
- **`numero_repetido`**: that phone is already in the account.
- **5-number limit**: it lifts once the company is over 7 days old and has at least one authorised payment.
- **Provider error when sending**: the same status and body Twilio answered are returned.
- **Transcription `failed`**: the reason is stored in the message; retry it manually from the chat.

> **PRECAUCION:** A number's API credentials are only shown to a company admin on request, and who viewed them is logged.

## MCP access

Real messages are not sent through MCP: the tools list numbers and work on the sandbox. `configurar_transcripcion_whatsapp` is for company admins only. See [/mcp/docs](https://ardumaker.com/en/mcp/docs).

| Type | Tools |
| --- | --- |
| Read | `listar_numeros_whatsapp`, `listar_numeros_sandbox_whatsapp`, `ver_numero_sandbox_whatsapp`, `listar_chat_sandbox_whatsapp` |
| Modify | `crear_numero_sandbox_whatsapp`, `editar_numero_sandbox_whatsapp`, `simular_mensaje_sandbox_whatsapp`, `simular_estado_sandbox_whatsapp`, `configurar_transcripcion_whatsapp` |
| Destructive | `eliminar_numero_sandbox_whatsapp` |

> **PRECAUCION:** `simular_mensaje_sandbox_whatsapp` delivers the message to the account's real webhooks. What the customer's bot answers arrives marked as untrusted content.

## Related features

- [WhatsApp webhooks](https://ardumaker.com/en/docs/webhooks-whatsapp/)
- [Chat history](https://ardumaker.com/en/docs/historial-de-chats/)
- [Service usage](https://ardumaker.com/en/docs/consumo-de-servicios/)
- [Router IA](https://ardumaker.com/en/docs/router-ia/)
- [Companies](https://ardumaker.com/en/docs/empresas/)