Migrate
Migrate from Z-API
How to replace Z-API with Messajo and keep your number.
This page shows what changes when you leave Z-API and how each of its operations becomes a Messajo call. The general tables for any provider (Cloud API, 360dialog, Twilio and unofficial APIs) live in Migrate from another provider; only the Z-API specifics are here.
What changes in the model
Section titled “What changes in the model”Z-API pairs a phone, like WhatsApp Web. Messajo uses Meta’s official API. In practice:
| In Z-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”Z-API identifies the instance by its ID and token, which you find in the Z-API panel. 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 token per instance”.
See Key types.
Operations side by side
Section titled “Operations side by side”Z-API paths are not listed here: check them in the Z-API documentation. The left column names the operation.
| Operation in Z-API | In Messajo |
|---|---|
| Send text | POST /v1/messages with type: "text". See Send text |
| Send image | type: "image". See Send image |
| Send video | type: "video". See Send video |
| Send audio | type: "audio". See Send audio |
| Send document | type: "document". See Send document |
| Send sticker | type: "sticker". See Send sticker |
| Send location | type: "location". See Send and request location |
| Send contact | type: "contacts". See Send a contact |
| Send buttons | type: "interactive", reply buttons. See Send buttons |
| Send an option list | type: "interactive", list. See Send list |
| React to a message | type: "reaction". See Send reaction |
| Reply quoting a message | reply_to in the send body |
| Mark as read | POST /v1/messages/{id}/read. See Mark as read |
| Send a file by URL | link (public URL) or media_id, obtained with POST /v1/media (multipart) |
Z-API’s text send uses the phone and message fields (Send simple text). In Messajo they become to and text.body.
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 @c.us do not exist; any non-digit character is dropped.
Webhooks
Section titled “Webhooks”| In Z-API | In Messajo |
|---|---|
| Received-message callback | message.received event |
| Message status callback (sent, delivered, read) | message.status event |
| Instance state callback | connection.* events |
| QR code callback | 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 to the new
Authorizationand body format, with recipients without suffixes. - Z-API instance turned off only after the official connection is active and tested, and the device paired by QR code unpaired from it.