# Migrate from another provider

> What changes when you bring your integration from another provider to Messajo.

## How much changes

The effort depends on where you come from. If you already use the official API, little changes; if you come from an unofficial API, the model changes.

| Coming from | Sending | Webhooks | Effort |
|---|---|---|---|
| Cloud API directly | Same body on the mirror layer; change the base URL and the token | `meta` format: the same `value` you already handle | Small |
| 360dialog | Same body on the mirror layer; change the URL, drop `D360-API-KEY` and put the `phone_number_id` in the path | `meta` format | Small |
| Twilio | Rewrite: simple or mirror layer | Statuses become `message.status` | Medium |
| Evolution, WAHA, Z-API, uazapi | Rewrite and adopt Meta's rules (window, templates, opt-in) | `normalized` or `meta` format | Large |

Both API layers (Meta mirror and simple) use the same key. See [Concepts](/en/start/concepts/).

## Coming from the Cloud API or 360dialog

The mirror layer takes **the same body as Meta**, field by field. The code that builds the message stays the same; only the URL and authentication change.

| | Before | On Messajo |
|---|---|---|
| Cloud API | `POST https://graph.facebook.com/<version>/{phone_number_id}/messages` | `POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages` |
| 360dialog | `POST https://waba-v2.360dialog.io/messages` | `POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages` |
| Authentication | `Authorization: Bearer <Meta token>` or `D360-API-KEY: <key>` | `Authorization: Bearer mj_...` |

```bash
curl -X POST "https://api.messajo.com/v1/whatsapp/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Hello from Messajo" }
  }'
```

- On 360dialog the key already identifies the number. On Messajo the key belongs to the organization, so the `phone_number_id` goes in the path. It is shown on the connection page.
- The `D360-API-KEY` header goes away; `Authorization: Bearer` comes in, with an [API key](/en/api/authentication/) that has the `send` permission.
- The Meta token no longer lives in your code: Messajo stores the connection token, encrypted.
- Meta's response and errors come back as they were, with the same `{ "error": { "code", … } }` body your code already handles. Only Messajo's own errors (key, permission, limit) use the [single format](/en/errors/).
- For webhooks, choose the `meta` format on the destination to receive the same `value` Meta sends, inside the Messajo envelope. See [Events](/en/webhooks/events/).

### What the mirror accepts

The path is `/v1/whatsapp/{id}/<rest of Meta's path>`, with Meta's method, query and body. The Graph API version is the server's.

| `{id}` | Goes to | Example |
|---|---|---|
| `phone_number_id` of one of your connections | the number | `POST /v1/whatsapp/{phone_number_id}/messages`, `GET …/whatsapp_business_profile`, `POST …/media` |
| `waba_id` (messaging account) of one of your connections | the account | `GET /v1/whatsapp/{waba_id}/message_templates` |
| `phone_number_id` + `nodes/{node_id}` | a standalone Meta node | `GET /v1/whatsapp/{phone_number_id}/nodes/{media_id}`, `DELETE …/nodes/{template_id}` |

The `waba_id` is shown on the connection page, under **Messaging account (WABA)**. Standalone nodes (media, template by id) go through the number, so Messajo knows which connection the request belongs to.

- **Key permission:** `POST …/messages` needs `send`; `message_templates` and template nodes need `templates`; other `GET`s, `read`; other changes, `admin`. A key bound to some connections only reaches those.
- **Blocked** with `403` [`mirror_path_blocked`](/en/errors#mirror_path_blocked), because they break the connection: `register`, `deregister`, `request_code`, `verify_code`, `smb_app_data`, `DELETE …/subscribed_apps` and `POST …/subscribed_apps` with `override_callback_uri`.
- **Sending:** `POST …/messages` goes through the same per-number limit as the simple layer ([Sending per number](/en/api/limits#sending-per-number)), records the message in the logs, emits `message.sent` and returns the Messajo id in the `X-Messajo-Message-Id` header. Messajo does not retry the send when Meta fails.
- **Response:** Meta's status, body and `content-type`, plus `X-Request-Id`. The `Authorization` you send never goes on to Meta.

## Coming from Twilio

Twilio has its own format (`From`, `To` and `Body` with the `whatsapp:` prefix, form-encoded), so the send call is rewritten:

- **simple layer** (`POST /v1/messages`), for text, media, templates and buttons in the same format across the 3 channels;
- **mirror layer**, to use any Meta feature with Meta's own body.

Twilio statuses (`queued`, `sent`, `delivered`, `read`, `failed`) arrive as the `message.status` event, and incoming messages as `message.received`. Replace the `StatusCallback` and the inbound webhook with an [event destination](/en/webhooks/events/) and [verify the signature](/en/webhooks/verify-signature/) from Messajo instead of `X-Twilio-Signature`. Approved templates live in your Meta account: sync or recreate them on Messajo.

## Coming from an unofficial API

Evolution, WAHA, Z-API and uazapi emulate a phone. Messajo uses Meta's official API, and that changes the model:

| On the unofficial API | On Messajo |
|---|---|
| Scan the QR code | Meta's official signup (Embedded Signup), from the panel |
| Instance | Connection |
| Send any message at any time | Outside the 24 h window, only an **approved template** |
| Bought lists or contacts who never talked to you | **Opt-in**: the person must have agreed to receive messages |
| No per-message cost | Meta charges per template message, directly to you |
| Risk of the number being banned | Official number, with quality and limits measured by Meta |

To keep support on the phone, connect in **coexistence**: the WhatsApp Business app keeps working and Messajo brings in the contacts and up to 6 months of history, once, at connection time. Groups do not sync in coexistence. See [Connect WhatsApp](/en/connect/whatsapp/).

Turn off the old API only after the official connection is active and tested, and unlink the device paired through the QR code from it.

## The number is already with another partner

It depends on the mode:

- **API only**: under Meta's new account model, the number can have several partners at once. Connect through Messajo without removing it from the current partner, migrate gradually and turn off the old one when you are done. See [Meta's guide to the new account model](https://developers.facebook.com/documentation/business-messaging/whatsapp/account-model-evolution/onboarding/).
- **Coexistence**: one partner at a time. Disconnect in the phone app and connect again through Messajo, as in [Switch partners in coexistence](/en/connect/whatsapp/#switch-partners-in-coexistence).

## Cutover checklist

- [ ] Templates synced or recreated on Messajo, and approved.
- [ ] Event destinations created, with the signature verified on your server.
- [ ] One API key per integration, with only the permissions and connections it needs.
- [ ] An end-to-end test with your own number: send, receive, status and template.
- [ ] Old integration turned off only after the test, and the number disconnected from the old provider, if needed.
