Migrar do Z-API

​

O que muda

​

O número

• Número no app WhatsApp Business: a Meta permite conectar o número à plataforma em coexistência, mantendo o app no celular. Na Arara, mensagens enviadas pelo celular chegam como evento message.echo, e o inbox mostra as duas pontas.
• Número em outro app ou sem app: o número precisa ser registrado só na plataforma e deixa de funcionar no WhatsApp Web. Planeje a janela de troca e avise clientes.
• Número novo: você conecta um número novo na Arara e mantém o Z-API em paralelo até migrar a base.

​

O caminho técnico

​

1. Preparação

1. Crie a organização em https://app.ararahq.com e gere uma chave de API (ara_live_...).
2. Liste tudo que o seu sistema envia pelo Z-API e classifique: resposta a cliente (cabe na janela de 24h) ou mensagem iniciada pela empresa (vira template).
3. Tenha a conta da empresa na Meta pronta para a verificação.

​

2. Templates

• Confirmação de pedido → pedido_confirmado, categoria UTILITY
• Carrinho abandonado → carrinho_abandonado, categoria MARKETING ou UTILITY, conforme o conteúdo
• Oferta → oferta_semana, categoria MARKETING

curl -X POST https://api.ararahq.com/v1/templates \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pedido_confirmado",
    "category": "UTILITY",
    "language": "pt_BR",
    "body": "Oi {{1}}, seu pedido {{2}} foi confirmado.",
    "samples": { "1": "João", "2": "ARA-123" }
  }'

​

3. Código

import axios from 'axios';

await axios.post(
  `https://api.z-api.io/instances/${INSTANCE}/token/${TOKEN}/send-text`,
  {
    phone: '5511999999999',
    message: 'Olá João, seu pedido foi confirmado!',
  }
);

import { NodeSDK } from '@ararahq/sdk';

const sdk = new NodeSDK({ apiKey: process.env.ARARA_API_KEY! });

// Janela de 24h aberta (cliente falou com você nas últimas 24h): mensagem sem template
await sdk.messages.send({
  receiver: '+5511999999999',
  body: 'Olá João, seu pedido foi confirmado!',
});

// Fora da janela: template aprovado
await sdk.messages.send(
  {
    receiver: '+5511999999999',
    templateName: 'pedido_confirmado',
    templateVariables: ['João', 'ARA-123'],
  },
  { idempotencyKey: 'pedido-ARA-123-confirmado' },
);

• Mensagem sem template só na janela de 24h. Veja Janela de 24h.
• Mensagem iniciada pela empresa usa template aprovado.
• Destinatário em formato internacional: +5511999999999 (o prefixo whatsapp: também é aceito).
• Webhook assinado: valide X-Arara-Signature e X-Arara-Timestamp. Veja Webhooks.

​

4. Recebimento

// Mesma URL recebe todos os eventos da organização
if (event === 'message.received') {
  const phone = data.from; // só dígitos, ex.: 5511999999999
  const text = data.body;
}

​

5. Cutover

1. Com número conectado e templates aprovados, atualize as variáveis de ambiente (ARARA_API_KEY, ARARA_WEBHOOK_SECRET).
2. Faça deploy.
3. Acompanhe entregas e falhas no dashboard nos primeiros dias.
4. Desligue o Z-API quando o fluxo estiver validado.

​

Rotina do time

• A janela de 24h é regra da Meta, não da Arara.
• Template tem texto fixo aprovado; o que muda por envio são as variáveis.
• O cliente precisa ter consentido em receber mensagens da empresa. Veja Compliance.

​

O que não migra

• Histórico de mensagens do Z-API: a Arara não importa.
• Contatos do celular: ficam no aparelho. Suba sua base pela API de contatos ou pelo dashboard.
• Grupos: a Arara não envia para grupos. Se a sua operação depende de grupos, avalie antes.

​

Próximos passos