Skip to content

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.

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

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.

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 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 token per instance”.

See Key types.

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.

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.

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.
  • 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 Authorization and 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.