Skip to main content

​
What is the Z-API Compatibility version?

The Z-API Compatibility version was created to make it easy for customers currently using Z-API to migrate to as their official API solution for WhatsApp and other messaging channels. We know that switching API providers can be a complex process — especially when you already have integrations running in production. That’s why we developed this compatibility layer that maintains the same structure you already know.

​
What changes in practice?

The only changes required in your application are the base URL and the authentication header. Additionally, since it uses the official WhatsApp API, some Z-API features are not available. See the Official API Limitations page for details.
Before (Z-API)After (Hub Message)
Base URLhttps://api.z-api.iohttps://zapi.hubmessage.io
AuthenticationClient-Token headerAuthorization: Bearer {secret} header
Naminginstance / instance_idchannel / channel_id
URL Path/instances/{id}/token/{token}/instances/ or /channels/ (both work)
API Payloads—Same structure
Webhook Body—Same structure

​
About naming

In , what was previously called instance (instance_id) is now referred to as channel (channel_id). The concept is the same — it represents a connection to a WhatsApp number — but we adopted the term “channel” because it’s more comprehensive, since supports multiple messaging channels beyond WhatsApp.
For compatibility, the API accepts both /instances/ and /channels/ in the path. If you’re migrating from Z-API, you can keep /instances/ without any issues — your integrations will continue working. For new integrations, we recommend using /channels/.
If today your application makes a call like: 
curl -X POST https://api.z-api.io/instances/YOUR_INSTANCE/token/YOUR_TOKEN/send-text \
  -H "Content-Type: application/json" \
  -H "Client-Token: YOUR_CLIENT_TOKEN" \
  -d '{"phone": "5511999999999", "message": "Hello!"}'
Just change it to: 
curl -X POST https://zapi.hubmessage.io/channels/YOUR_CHANNEL/token/YOUR_TOKEN/send-text \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET" \
  -d '{"phone": "5511999999999", "message": "Hello!"}'
Note that only the base URL and authentication header changed — the path and body are identical. The secret for the Authorization header is generated in the Hub Message dashboard when you create your channel. The request payloads and webhook bodies maintain exactly the same structure, ensuring your integrations continue working without breaking.

​
Why migrate?

Official WhatsApp API

Use the official WhatsApp Business API with all the security and stability it provides.

Lower risk of blocking

By using the official WhatsApp API, the risk of banning is significantly lower compared to unofficial solutions.

Simple migration

Just change the base URL and you’re done — your integrations keep working.

Dedicated support

Count on the team’s support throughout the migration process.

​
How to migrate

1

Create your Hub Message account

Go to the Dashboard and create your account.
2

Set up your channel

Create a new channel and connect your WhatsApp number.
3

Update the base URL and authentication

Replace https://api.z-api.io with https://zapi.hubmessage.io and change the Client-Token header to Authorization: Bearer YOUR_SECRET.
4

Configure webhooks

Update the webhook callback URL in the Dashboard to point to your server. Incoming events will have the same structure as before.
5

Test and validate

Run send and receive tests to make sure everything is working correctly.
Need help with the migration? Contact us at .