# 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](/en/operate/migrate/); only the Z-API specifics are here.

## 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](/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

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](/en/api/authentication/#key-types).

## Operations side by side

Z-API paths are not listed here: check them in the [Z-API documentation](https://developer.z-api.io/). The left column names the operation.

| Operation in Z-API | In Messajo |
|---|---|
| Send text | `POST /v1/messages` with `type: "text"`. See [Send text](/en/send/text/) |
| Send image | `type: "image"`. See [Send image](/en/send/image/) |
| Send video | `type: "video"`. See [Send video](/en/send/video/) |
| Send audio | `type: "audio"`. See [Send audio](/en/send/audio/) |
| Send document | `type: "document"`. See [Send document](/en/send/document/) |
| Send sticker | `type: "sticker"`. See [Send sticker](/en/send/sticker/) |
| Send location | `type: "location"`. See [Send and request location](/en/send/location/) |
| Send contact | `type: "contacts"`. See [Send a contact](/en/send/contacts/) |
| Send buttons | `type: "interactive"`, reply buttons. See [Send buttons](/en/send/buttons/) |
| Send an option list | `type: "interactive"`, list. See [Send list](/en/send/list/) |
| React to a message | `type: "reaction"`. See [Send reaction](/en/send/reaction/) |
| Reply quoting a message | `reply_to` in the send body |
| Mark as read | `POST /v1/messages/{id}/read`. See [Mark as read](/en/send/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](https://developer.z-api.io/message/send-text)). In Messajo they become `to` and `text.body`.

### 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

| 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](/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 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.
