# WhatsApp Business API

Enviar e receber WhatsApp a partir dos números da empresa, com sandbox de testes e transcrição de áudios.

Fonte: https://ardumaker.com/pt/docs/whatsapp-business-api/

- Categoria: Comunicação
- Estado: Disponível
- Requisitos: Uma empresa na ArduMaker onde você é membro ou admin; Um número de WhatsApp já habilitado, que um admin adiciona à conta
- Ferramentas MCP (Só leem): `listar_numeros_whatsapp`, `listar_numeros_sandbox_whatsapp`, `ver_numero_sandbox_whatsapp`, `listar_chat_sandbox_whatsapp`
- Ferramentas MCP (Escrevem ou modificam): `configurar_transcripcion_whatsapp`, `crear_numero_sandbox_whatsapp`, `editar_numero_sandbox_whatsapp`, `simular_mensaje_sandbox_whatsapp`, `simular_estado_sandbox_whatsapp`
- Ferramentas MCP (Destrutivas): `eliminar_numero_sandbox_whatsapp`

## O que permite fazer?

- Uma conta de WhatsApp por empresa, com a sua subconta do fornecedor (Twilio).
- Enviar texto, arquivos e modelos a partir de um número, com o mesmo formato de pedido que a Twilio.
- Receber mensagens e reencaminhá-las para um sistema próprio com [webhooks](https://ardumaker.com/pt/docs/webhooks-whatsapp).
- Testar um bot com contatos de sandbox, sem telefone e sem que nada saia para o fornecedor.
- Transcrever para texto os áudios e notas de voz que chegam.

## Quando convém usar?

Para atender ou vender por WhatsApp com um bot próprio, ou para integrar as mensagens da empresa com outro sistema.

## Como funciona na ArduMaker?

1. **Conta.** Na primeira vez que a empresa abre o WhatsApp, a ArduMaker pede ao fornecedor uma subconta e só então guarda a conta. Se o fornecedor falhar, nada fica a meio.
2. **Números.** Um admin da empresa adiciona cada número com o telefone e, se tiver, as credenciais de API. Uma empresa nova ou sem pagamento validado pode ter até 5 números ativos.
3. **Envio.** Envia-se com a sessão da pessoa ou com o cabeçalho `Twilio-Api-Sid` do número. A ArduMaker guarda a mensagem e os arquivos e reencaminha o pedido ao fornecedor; a resposta é a do fornecedor.
4. **Receção.** O fornecedor avisa a ArduMaker de cada mensagem recebida e de cada mudança de estado; a ArduMaker guarda-os no [histórico](https://ardumaker.com/pt/docs/historial-de-chats).

### Sandbox de testes

Um contato de sandbox é uma linha da base de dados, não uma linha telefónica: não tem limite nem custo. Sem número explícito gera-se um no intervalo `+999`, reservado pela ITU. Um envio a um contato de sandbox faz tudo o normal mas salta o pedido ao fornecedor, responde `sandbox: true` e o chat fica marcado como teste.

### Transcrição de áudios

Ativa-se por número. Só áudio e notas de voz: o texto fica na mensagem com o prefixo `[transcripcion]: `. Há até 10 tentativas seguidas com espera crescente; se se esgotarem, a mensagem fica `failed` e pode ser repetida manualmente.

## O que muda realmente?

- No fornecedor: uma subconta por empresa.
- Na ArduMaker: a conta, os números, as conversas, as mensagens e os arquivos recebidos ou enviados.
- Na faturamento: o uso do fornecedor é sincronizado e cobrado como consumo da empresa.

## Esquema

**Mensagem de saída**

```text
Painel, bot ou agente (sessão ou Twilio-Api-Sid)
  ↓
API de WhatsApp da ArduMaker (guarda mensagem e arquivos)
  ↓
Contato de sandbox? (sim: não sai)
  ↓
Twilio (entrega no WhatsApp)
```

## Resultado esperado

As mensagens saem e entram pelo número da empresa e ficam no seu histórico. Com o sandbox, um bot testa-se de ponta a ponta sem telefone.

## Erros e resolução

- **424 `dependencia_caida` ou `proveedor_no_configurado` ao abrir a conta**: o fornecedor não criou a subconta. É seguro repetir: volta a ser pedida.
- **`numero_repetido`**: esse telefone já está na conta.
- **Limite de 5 números**: é libertado quando a empresa tem mais de 7 dias e pelo menos um pagamento autorizado.
- **Erro do fornecedor ao enviar**: é devolvido o mesmo código e corpo que a Twilio respondeu.
- **Transcrição `failed`**: o motivo fica na mensagem; repete-se manualmente a partir do chat.

> **PRECAUCION:** As credenciais de API de um número só são mostradas a um admin da empresa, a pedido, e fica registrado quem as viu.

## Relação com MCP

Via MCP não se enviam mensagens reais: as ferramentas listam os números e trabalham sobre o sandbox. `configurar_transcripcion_whatsapp` é só para admins da empresa. Ver [/mcp/docs](https://ardumaker.com/pt/mcp/docs).

| Tipo | Ferramentas |
| --- | --- |
| Leitura | `listar_numeros_whatsapp`, `listar_numeros_sandbox_whatsapp`, `ver_numero_sandbox_whatsapp`, `listar_chat_sandbox_whatsapp` |
| Modificam | `crear_numero_sandbox_whatsapp`, `editar_numero_sandbox_whatsapp`, `simular_mensaje_sandbox_whatsapp`, `simular_estado_sandbox_whatsapp`, `configurar_transcripcion_whatsapp` |
| Destrutiva | `eliminar_numero_sandbox_whatsapp` |

> **PRECAUCION:** `simular_mensaje_sandbox_whatsapp` entrega a mensagem aos webhooks reais da conta. O que o bot do cliente responde chega marcado como conteúdo não confiável.

## Funcionalidades relacionadas

- [Webhooks de WhatsApp](https://ardumaker.com/pt/docs/webhooks-whatsapp/)
- [Histórico de chats](https://ardumaker.com/pt/docs/historial-de-chats/)
- [Consumo de serviços](https://ardumaker.com/pt/docs/consumo-de-servicios/)
- [Router IA](https://ardumaker.com/pt/docs/router-ia/)
- [Empresas](https://ardumaker.com/pt/docs/empresas/)