# Migrate from Evolution API

> How to replace Evolution API with Messajo and keep your number.

This page shows what changes when you leave Evolution API and how each of its routes becomes a Messajo call. The general tables for any provider are in [Migrate from another provider](/en/operate/migrate/); only the Evolution API specifics are here.

## What changes in the model

Evolution API pairs a phone, like WhatsApp Web. Messajo uses Meta's official API. In practice:

| In Evolution API | In Messajo |
|---|---|
| Scan the QR code | Meta's official signup (Embedded Signup), from the panel |
| Instance | Connection (`conn_…`) |
| Free-form message at any time | Free-form only within 24 h of the person's last message; otherwise an [approved template](/en/guides/templates/) |
| Contact who never wrote to you | Opt-in required: the person must have agreed to receive messages |
| No per-message charge from Meta | Meta charges for template messages, billed to you directly. See [Meta costs](/en/guides/costs/) |
| Paired number | Official number, with quality and limits measured by Meta |

## Keeping your number

To keep handling chats on your phone, connect in **coexistence**: the WhatsApp Business app keeps working and Messajo imports your contacts and up to 6 months of history, once, when you connect.

- It requires the WhatsApp Business app 2.24.17 or newer, with QR code confirmation in the app.
- Throughput is fixed at 20 messages per second.
- Groups do not sync in coexistence. If you rely on groups, see [Groups](/en/guides/groups/): they need API-only mode.
- For higher volume or a new number, use **API-only** mode.

The step-by-step is in [Connect WhatsApp](/en/connect/whatsapp/); if something gets stuck, see [Coexistence issues](/en/troubleshooting/coexistence/).

## Authentication

Evolution API authenticates with the `apikey` header (global or per instance) and identifies the instance by its name in the path. In Messajo every call carries `Authorization: Bearer <key>`:

- **organization key** (`mj_…`): sent together with `connection_id` in the body;
- **connection key** (`mjc_…`): valid for one connection only and needs no `connection_id`. It is the closest thing to "one key per instance".

See [Key types](/en/api/authentication/#key-types).

## Routes side by side

The Evolution API paths come from the [Evolution Foundation documentation](https://docs.evolutionfoundation.com.br/llms.txt); all of them take the instance name at the end.

| Route in Evolution API | In Messajo |
|---|---|
| `POST /message/sendText/{instanceName}` | `POST /v1/messages` with `type: "text"`. See [Send text](/en/send/text/) |
| `POST /message/sendMedia/{instanceName}` (image, video, document and audio) | `type: "image"`, `"video"`, `"document"` or `"audio"`. See [Send image](/en/send/image/), [video](/en/send/video/), [document](/en/send/document/) and [audio](/en/send/audio/) |
| Send sticker (no route in the documentation consulted) | `type: "sticker"`. See [Send sticker](/en/send/sticker/) |
| `POST /message/sendLocation/{instanceName}` | `type: "location"`. See [Send and request location](/en/send/location/) |
| `POST /message/sendContact/{instanceName}` | `type: "contacts"`. See [Send a contact](/en/send/contacts/) |
| `POST /message/sendButtons/{instanceName}` | `type: "interactive"`, reply buttons. See [Send buttons](/en/send/buttons/) |
| `POST /message/sendList/{instanceName}` | `type: "interactive"`, list. See [Send list](/en/send/list/) |
| `POST /message/sendReaction/{instanceName}` | `type: "reaction"`. See [Send reaction](/en/send/reaction/) |
| Quote option (`quoted`) | `reply_to` in the send body |
| `POST /chat/markMessageAsRead/{instanceName}` | `POST /v1/messages/{id}/read`. See [Mark as read](/en/send/mark-as-read/) |
| Media by URL | `link` (public URL) or `media_id`, obtained with `POST /v1/media` (multipart) |

### Example: send a text

The text body differs between Evolution API versions (`text` directly or inside `textMessage`); check the one in your installation.

**Evolution API**

```bash
curl https://YOUR-SERVER/message/sendText/my-instance \
  -H "apikey: $EVOLUTION_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Hi! Your order is out for delivery."
  }'
```

**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": "Hi! Your order is out for delivery." }
  }'
```

**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: "Hi! Your order is out for delivery." },
});
```

### Recipient format

Messajo takes the phone with country code, digits only (for example `5511999999999`), or a `ctc_…` contact. Suffixes such as `@s.whatsapp.net` do not exist; any non-digit character is dropped.

## Webhooks

| In Evolution API | In Messajo |
|---|---|
| Message received event | `message.received` event |
| Message status update event | `message.status` event |
| Instance connection state event | `connection.*` events |
| QR code event | No equivalent: the connection is made from the panel |

You register an [event destination](/en/webhooks/events/) and Messajo signs every delivery with `Messajo-Signature` (HMAC-SHA256). Verify the signature on your server, as in [Verify the signature](/en/webhooks/verify-signature/). In coexistence, messages sent from the phone app arrive as `message.echo`.

## What has no equivalent or works differently

- **Sending to anyone at any time.** In Messajo the 24 h window applies and, outside it, only an approved template. See [Limits](/en/api/limits/#windows).
- **Groups.** They do not sync in coexistence; to use groups, the mode is API-only. See [Groups](/en/guides/groups/).

## Cutover checklist

- [ ] Connection created (coexistence or API-only) and **Active** in the panel.
- [ ] Templates created and approved for the messages you send outside the window.
- [ ] Event destinations created, with the signature verified on your server.
- [ ] One API key per integration, with only the permissions and connections it needs.
- [ ] End-to-end test with a number of your own: send, receive, status and template.
- [ ] Integration switched from `apikey` to `Authorization` and to the new body format, with recipients without suffixes.
- [ ] Evolution API instance turned off **only after** the official connection is active and tested, and the device paired by QR code unpaired from it.
