Migrate
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; only the Evolution API specifics are here.
What changes in the model
Section titled “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 |
| 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 |
| Paired number | Official number, with quality and limits measured by Meta |
Keeping your number
Section titled “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: they need API-only mode.
- For higher volume or a new number, use API-only mode.
The step-by-step is in Connect WhatsApp; if something gets stuck, see Coexistence issues.
Authentication
Section titled “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 withconnection_idin the body; - connection key (
mjc_…): valid for one connection only and needs noconnection_id. It is the closest thing to “one key per instance”.
See Key types.
Routes side by side
Section titled “Routes side by side”The Evolution API paths come from the Evolution Foundation documentation; 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 |
POST /message/sendMedia/{instanceName} (image, video, document and audio) |
type: "image", "video", "document" or "audio". See Send image, video, document and audio |
| Send sticker (no route in the documentation consulted) | type: "sticker". See Send sticker |
POST /message/sendLocation/{instanceName} |
type: "location". See Send and request location |
POST /message/sendContact/{instanceName} |
type: "contacts". See Send a contact |
POST /message/sendButtons/{instanceName} |
type: "interactive", reply buttons. See Send buttons |
POST /message/sendList/{instanceName} |
type: "interactive", list. See Send list |
POST /message/sendReaction/{instanceName} |
type: "reaction". See Send reaction |
Quote option (quoted) |
reply_to in the send body |
POST /chat/markMessageAsRead/{instanceName} |
POST /v1/messages/{id}/read. See Mark as read |
| Media by URL | link (public URL) or media_id, obtained with POST /v1/media (multipart) |
Example: send a text
Section titled “Example: send a text”The text body differs between Evolution API versions (text directly or inside textMessage); check the one in your installation.
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." }'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." } }'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
Section titled “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
Section titled “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 and Messajo signs every delivery with Messajo-Signature (HMAC-SHA256). Verify the signature on your server, as in Verify the signature. In coexistence, messages sent from the phone app arrive as message.echo.
What has no equivalent or works differently
Section titled “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.
- Groups. They do not sync in coexistence; to use groups, the mode is API-only. See Groups.
Cutover checklist
Section titled “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
apikeytoAuthorizationand 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.