# Migrar da Evolution API

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

Esta página mostra o que muda ao sair da Evolution API e como cada rota dela vira uma chamada do Messajo. As tabelas gerais de qualquer provedor estão em [Migrar de outro provedor](/operate/migrate/); aqui ficam só os pontos da Evolution API.

## O que muda no modelo

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

| Na Evolution 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 Evolution API autentica com o cabeçalho `apikey` (global ou da instância) e identifica a instância pelo nome no caminho. 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 "uma chave por instância".

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

## Rotas lado a lado

Os caminhos da Evolution API vêm da [documentação da Evolution Foundation](https://docs.evolutionfoundation.com.br/llms.txt); todos recebem o nome da instância no final.

| Rota na Evolution API | No Messajo |
|---|---|
| `POST /message/sendText/{instanceName}` | `POST /v1/messages` com `type: "text"`. Veja [Enviar texto](/send/text/) |
| `POST /message/sendMedia/{instanceName}` (imagem, vídeo, documento e áudio) | `type: "image"`, `"video"`, `"document"` ou `"audio"`. Veja [Enviar imagem](/send/image/), [vídeo](/send/video/), [documento](/send/document/) e [áudio](/send/audio/) |
| Enviar sticker (sem rota na documentação consultada) | `type: "sticker"`. Veja [Enviar figurinha](/send/sticker/) |
| `POST /message/sendLocation/{instanceName}` | `type: "location"`. Veja [Enviar e pedir localização](/send/location/) |
| `POST /message/sendContact/{instanceName}` | `type: "contacts"`. Veja [Enviar contato](/send/contacts/) |
| `POST /message/sendButtons/{instanceName}` | `type: "interactive"`, botões de resposta. Veja [Enviar botões](/send/buttons/) |
| `POST /message/sendList/{instanceName}` | `type: "interactive"`, lista. Veja [Enviar lista](/send/list/) |
| `POST /message/sendReaction/{instanceName}` | `type: "reaction"`. Veja [Enviar reação](/send/reaction/) |
| Opção de citar uma mensagem (`quoted`) | `reply_to` no corpo do envio |
| `POST /chat/markMessageAsRead/{instanceName}` | `POST /v1/messages/{id}/read`. Veja [Marcar como lida](/send/mark-as-read/) |
| Mídia por URL | `link` (URL pública) ou `media_id`, obtido com `POST /v1/media` (multipart) |

### Exemplo: enviar um texto

O corpo do texto varia entre versões da Evolution API (`text` direto ou dentro de `textMessage`); confira o da sua instalação.

**Evolution API**

```bash
curl https://SEU-SERVIDOR/message/sendText/minha-instancia \
  -H "apikey: $EVOLUTION_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Olá! Seu pedido saiu para entrega."
  }'
```

**Messajo cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_...",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Olá! Seu pedido saiu para entrega." }
  }'
```

**Messajo TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "text",
  text: { body: "Olá! Seu pedido saiu para entrega." },
});
```

### Formato do destinatário

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

## Webhooks

| Na Evolution API | No Messajo |
|---|---|
| Evento de mensagem recebida | Evento `message.received` |
| Evento de atualização de status da mensagem | Evento `message.status` |
| Evento de estado da conexão da instância | Eventos `connection.*` |
| Evento de 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 `apikey` para `Authorization` e de formato de corpo, e o destinatário sem sufixos.
- [ ] Instância da Evolution API desligada **só depois** de a conexão oficial estar ativa e testada, e o aparelho pareado por QR code desconectado dela.
