# Migrar da Z-API

> Como trocar a Z-API pelo Messajo e manter o número.

Esta página mostra o que muda ao sair da Z-API e como cada operação dela vira uma chamada do Messajo. As tabelas gerais de qualquer provedor (Cloud API, 360dialog, Twilio e APIs não oficiais) estão em [Migrar de outro provedor](/operate/migrate/); aqui ficam só os pontos da Z-API.

## O que muda no modelo

A Z-API pareia um telefone, como o WhatsApp Web. O Messajo usa a API oficial da Meta. Na prática:

| Na Z-API | No Messajo |
|---|---|
| Ler o QR code | Cadastro oficial da Meta (Embedded Signup), pelo painel |
| Instância | Conexão (`conn_…`) |
| Mensagem livre a qualquer hora | Mensagem livre só dentro de 24 h do último contato da pessoa; fora disso, um [template aprovado](/guides/templates/) |
| Contato que nunca falou com você | Exige opt-in: a pessoa precisa ter aceitado receber mensagens |
| Sem cobrança por mensagem da Meta | A Meta cobra por mensagem de template, direto de você. Veja [Custos da Meta](/guides/costs/) |
| Número pareado | Número oficial, com qualidade e limites medidos pela Meta |

## Manter o número

Para não perder o atendimento no celular, conecte em **coexistência**: o app do WhatsApp Business continua funcionando e o Messajo importa os contatos e até 6 meses de histórico, uma única vez, na hora de conectar.

- Exige o app WhatsApp Business 2.24.17 ou mais novo, com confirmação por QR code no app.
- A vazão fica fixa em 20 mensagens por segundo.
- Grupos não sincronizam na coexistência. Se você depende de grupos, veja [Grupos](/guides/groups/): eles pedem o modo só API.
- Para volume maior ou para um número novo, use o modo **só API**.

O passo a passo está em [Conectar o WhatsApp](/connect/whatsapp/); se algo travar, veja [Problemas na coexistência](/troubleshooting/coexistence/).

## Autenticação

A Z-API identifica a instância pelo ID e pelo token dela, que aparecem no painel da Z-API. No Messajo, toda chamada leva `Authorization: Bearer <chave>`:

- **chave de organização** (`mj_…`): enviada com `connection_id` no corpo;
- **chave de conexão** (`mjc_…`): vale só para uma conexão e dispensa o `connection_id`. É a mais próxima de "um token por instância".

Veja [Tipos de chave](/api/authentication/#tipos-de-chave).

## Operações lado a lado

Os caminhos da Z-API não estão aqui: confira-os na [documentação da Z-API](https://developer.z-api.io/). A coluna da esquerda nomeia a operação.

| Operação na Z-API | No Messajo |
|---|---|
| Enviar texto | `POST /v1/messages` com `type: "text"`. Veja [Enviar texto](/send/text/) |
| Enviar imagem | `type: "image"`. Veja [Enviar imagem](/send/image/) |
| Enviar vídeo | `type: "video"`. Veja [Enviar vídeo](/send/video/) |
| Enviar áudio | `type: "audio"`. Veja [Enviar áudio](/send/audio/) |
| Enviar documento | `type: "document"`. Veja [Enviar documento](/send/document/) |
| Enviar sticker | `type: "sticker"`. Veja [Enviar figurinha](/send/sticker/) |
| Enviar localização | `type: "location"`. Veja [Enviar e pedir localização](/send/location/) |
| Enviar contato | `type: "contacts"`. Veja [Enviar contato](/send/contacts/) |
| Enviar botões | `type: "interactive"`, botões de resposta. Veja [Enviar botões](/send/buttons/) |
| Enviar lista de opções | `type: "interactive"`, lista. Veja [Enviar lista](/send/list/) |
| Reagir a uma mensagem | `type: "reaction"`. Veja [Enviar reação](/send/reaction/) |
| Responder citando uma mensagem | `reply_to` no corpo do envio |
| Marcar como lida | `POST /v1/messages/{id}/read`. Veja [Marcar como lida](/send/mark-as-read/) |
| Enviar arquivo por URL | `link` (URL pública) ou `media_id`, obtido com `POST /v1/media` (multipart) |

O texto da Z-API usa os campos `phone` e `message` ([Enviar texto simples](https://developer.z-api.io/message/send-text)). No Messajo eles viram `to` e `text.body`.

### Formato do destinatário

O Messajo aceita o telefone com DDI, só dígitos (por exemplo `5511999999999`), ou um contato `ctc_…`. Sufixos como `@c.us` não existem; qualquer caractere que não seja dígito é descartado.

## Webhooks

| Na Z-API | No Messajo |
|---|---|
| Retorno de mensagem recebida | Evento `message.received` |
| Retorno de status da mensagem (enviada, entregue, lida) | Evento `message.status` |
| Retorno de estado da instância | Eventos `connection.*` |
| Retorno do QR code | Sem equivalente: a conexão é feita pelo painel |

Você cadastra um [destino de eventos](/webhooks/events/) e o Messajo assina cada entrega com `Messajo-Signature` (HMAC-SHA256). Verifique a assinatura no seu servidor, como em [Verificar a assinatura](/webhooks/verify-signature/). Na coexistência, as mensagens enviadas pelo app do celular chegam como `message.echo`.

## O que não tem equivalente ou funciona diferente

- **Enviar a qualquer pessoa, a qualquer hora.** No Messajo vale a janela de 24 h e, fora dela, só template aprovado. Veja [Limites](/api/limits/#janelas).
- **Grupos.** Na coexistência não sincronizam; para usar grupos, o modo é só API. Veja [Grupos](/guides/groups/).

## Checklist de virada

- [ ] Conexão criada (coexistência ou só API) e **Ativa** no painel.
- [ ] Templates criados e aprovados para as mensagens que você manda fora da janela.
- [ ] Destinos de eventos criados, com a assinatura verificada no seu servidor.
- [ ] Uma chave de API por integração, com só as permissões e conexões necessárias.
- [ ] Teste de ponta a ponta com um número seu: enviar, receber, status e template.
- [ ] Integração trocada de `Authorization` e de formato de corpo, e o destinatário sem sufixos.
- [ ] Instância da Z-API desligada **só depois** de a conexão oficial estar ativa e testada, e o aparelho pareado por QR code desconectado dela.
