Migrate
Migrate from another provider
What changes when you bring your integration from another provider to Messajo.
How much changes
Section titled “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.
Coming from the Cloud API or 360dialog
Section titled “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_... |
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_idgoes in the path. It is shown on the connection page. - The
D360-API-KEYheader goes away;Authorization: Bearercomes in, with an API key that has thesendpermission. - 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. - For webhooks, choose the
metaformat on the destination to receive the samevalueMeta sends, inside the Messajo envelope. See Events.
What the mirror accepts
Section titled “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 …/messagesneedssend;message_templatesand template nodes needtemplates; otherGETs,read; other changes,admin. A key bound to some connections only reaches those. - Blocked with
403mirror_path_blocked, because they break the connection:register,deregister,request_code,verify_code,smb_app_data,DELETE …/subscribed_appsandPOST …/subscribed_appswithoverride_callback_uri. - Sending:
POST …/messagesgoes through the same per-number limit as the simple layer (Sending per number), records the message in the logs, emitsmessage.sentand returns the Messajo id in theX-Messajo-Message-Idheader. Messajo does not retry the send when Meta fails. - Response: Meta’s status, body and
content-type, plusX-Request-Id. TheAuthorizationyou send never goes on to Meta.
Coming from Twilio
Section titled “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 and verify the 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
Section titled “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.
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
Section titled “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.
- Coexistence: one partner at a time. Disconnect in the phone app and connect again through Messajo, as in Switch partners in coexistence.
Cutover checklist
Section titled “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.