> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ararahq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrar do Z-API

> Sair do Z-API (conexão via WhatsApp Web) para a WhatsApp Business Platform via Arara: o que muda no número, templates, janela de 24h e no código.

O Z-API conecta um número pelo WhatsApp Web. A Arara envia pela WhatsApp Business Platform da Meta. Não é só trocar de fornecedor: mudam as regras de envio (templates e janela de 24h), o jeito de conectar o número e o formato do código. Esta página cobre esses pontos.

## O que muda

| | Z-API | Arara |
| - | - | - |
| Conexão do número | Sessão do WhatsApp Web (QR Code) | Número cadastrado na WhatsApp Business Platform pelo fluxo da Meta |
| Mensagem iniciada pela empresa | Mensagem sem template | Template aprovado pela Meta |
| Mensagem dentro da janela de 24h | A qualquer momento | Só dentro da janela de 24h aberta pelo cliente |
| Recebimento | Webhook do Z-API | Webhook da organização, assinado com HMAC |
| Cobrança | Mensalidade do Z-API | Plano + uso por mensagem, em BRL. Veja [Preços](/concepts/pricing) |

## O número

Antes de começar, decida o que fazer com o número atual:

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

A conexão é feita no dashboard ([https://app.ararahq.com](https://app.ararahq.com)), em Números. A verificação da empresa e o nome de exibição passam pela Meta.

## O caminho técnico

### 1. Preparação

1. Crie a organização em [https://app.ararahq.com](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

Cada mensagem iniciada pela empresa vira um template:

* 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`

```bash theme={null}
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" }
  }'
```

Revise cada texto contra as [regras de template](/templates/policy) antes de submeter. A aprovação é da Meta.

### 3. Código

<CodeGroup>
  ```typescript Z-API (antes) theme={null}
  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!',
    }
  );
  ```

  ```typescript Arara (depois) theme={null}
  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' },
  );
  ```
</CodeGroup>

Principais mudanças:

* **Mensagem sem template só na janela de 24h.** Veja [Janela de 24h](/concepts/24h-window).
* **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](/webhooks).

### 4. Recebimento

```typescript theme={null}
// 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;
}
```

Configure a URL e o secret do webhook no dashboard.

### 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 maior mudança é de operação:

* **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](/concepts/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

<CardGroup cols={2}>
  <Card title="Conceitos WhatsApp" icon="lightbulb" href="/concepts/whatsapp">
    Janela de 24h e templates antes de migrar.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Primeiro envio depois que o número estiver pronto.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.