Skip to content

Migrate

Migrate from another provider

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

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.

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_...
Janela do terminal
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 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.
  • For webhooks, choose the meta format on the destination to receive the same value Meta sends, inside the Messajo envelope. See Events.

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 GETs, read; other changes, admin. A key bound to some connections only reaches those.
  • Blocked with 403 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), 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.

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.

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