WhatsApp Business API

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

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

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.

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.

Funcionalidades relacionadas

• Webhooks de WhatsApp
• Histórico de chats
• Consumo de serviços
• Router IA
• Empresas