Skip to main content
Esta página é o roteiro técnico para trocar o Twilio WhatsApp pela Arara: o que muda no número, nos templates e no código.
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.
Criar um template pela API:
A resposta (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

Diferenças:
  • 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-Key evita envio duplicado em retry.

Webhook de status

Diferenças:
  • 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)

Diferenças:
  • 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.from vem só com dígitos, sem whatsapp: e sem +.

Mapeamento de campos

Plano de migração

Preparação

  1. Liste templates e números em uso no Twilio.
  2. Crie a organização na Arara em https://app.ararahq.com e gere uma chave de API.
  3. Recrie os templates (POST /v1/templates) e acompanhe a aprovação.
  4. Conecte o número em Números, no dashboard.

Cutover

  1. Configure o webhook da organização (URL + secret) no dashboard.
  2. Atualize as variáveis de ambiente: ARARA_API_KEY e ARARA_WEBHOOK_SECRET.
  3. Faça deploy do código adaptado.
  4. Mantenha a conta Twilio ativa até validar entrega, inbound e webhooks na Arara.

Depois do cutover

  1. Acompanhe no dashboard: entregas, falhas e qualidade do número.
  2. 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.