Prazo típico: depende da verificação da sua empresa na Meta e da aprovação dos templates, que não são controladas pela Arara. Reserve alguns dias úteis para número e templates, e rode Twilio e Arara em paralelo até validar.
O que muda
Recursos da Arara sem equivalente direto no Twilio: Brain, Smart Links, recuperação de receita, CLI e MCP server. Preços em Preços.
Número e templates
- Número: você conecta o número à Arara pelo dashboard (https://app.ararahq.com), em Números, pelo fluxo de cadastro da Meta. Se o número está hoje em uma conta WhatsApp Business do Twilio, a liberação e a transferência seguem as regras da Meta para troca de provedor.
- Templates: templates pertencem à conta WhatsApp Business (WABA). Recrie cada template na Arara (dashboard ou
POST /v1/templates) e aguarde a aprovação da Meta antes do cutover. - Histórico: a Arara não importa mensagens antigas do Twilio. Exporte antes de encerrar a conta.
201) traz o id (UUID) do template. Consultas de status (GET /v1/templates/{id}/status) usam esse id; o envio usa o nome.
Diff de código
Envio de template
contentSid→templateName: o nome do template, não um SID.contentVariables→templateVariables: array posicional. Se o template tem header de mídia, a URL da mídia vai na primeira posição.- Sem
from:senderé opcional. - Idempotência: o header
Idempotency-Keyevita envio duplicado em retry.
Webhook de status
- Assinatura:
X-Arara-Signature=sha256=+ HMAC-SHA256 de{X-Arara-Timestamp}.{corpo cru}com o secret da organização (whsec_...). Valide com o corpo cru, não com o JSON já parseado. - Envelope único:
{ event, apiVersion, data, timestamp, organizationId }. - Um webhook para todos os eventos, configurado no dashboard (URL e secret).
Mensagem recebida (cliente respondeu)
- Sem TwiML: a resposta é uma chamada à API.
- Mensagem sem template só dentro da janela de 24h aberta pela mensagem do cliente. Fora dela, use template. Veja Janela de 24h.
data.fromvem só com dígitos, semwhatsapp:e sem+.
Mapeamento de campos
Plano de migração
Preparação
- Liste templates e números em uso no Twilio.
- Crie a organização na Arara em https://app.ararahq.com e gere uma chave de API.
- Recrie os templates (
POST /v1/templates) e acompanhe a aprovação. - Conecte o número em Números, no dashboard.
Cutover
- Configure o webhook da organização (URL + secret) no dashboard.
- Atualize as variáveis de ambiente:
ARARA_API_KEYeARARA_WEBHOOK_SECRET. - Faça deploy do código adaptado.
- Mantenha a conta Twilio ativa até validar entrega, inbound e webhooks na Arara.
Depois do cutover
- Acompanhe no dashboard: entregas, falhas e qualidade do número.
- Encerre o Twilio quando a operação estiver estável.
Pegadinhas
Nome do template
Use nomes que façam sentido para o time (pedido_confirmado). O envio sempre usa esse nome; o id (UUID) serve para consultar ou apagar o template.
Botões
POST /v1/templates aceita botões QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE e SMART_LINK (link rastreável da Arara).
Mídia com URL temporária
Se as mídias estão em URLs que expiram, hospede em um endereço estável ou suba pela Arara (POST /v1/media/upload, multipart com o campo file), que devolve url.
Twilio Conversations e Studio
A Arara é focada em WhatsApp: outros canais do Conversations não migram. Fluxos do Studio precisam ser recriados no seu backend, em automações ou no Brain.Próximos passos
Quickstart
Primeiro envio.
SDK Node
Métodos disponíveis na versão publicada.