Move a Pusher Channels application to Bird Realtime
Pusher is a Bird brand. This guide explains a move between product interfaces within the Bird family. Keep an existing Pusher application running until its Bird publisher, client and authorization path work together.
The interfaces share channel concepts, but credentials, authorization fields and protocol event names must match the product receiving them. Changing a hostname in an existing Pusher client does not establish compatibility.
Map the integration
| Pusher Channels integration | Bird Realtime implementation |
|---|---|
| Pusher app ID, app key, secret and cluster | Bird Realtime app ID, public key, secret and region from the same Bird app |
| Pusher browser client and channelAuthorization.endpoint | BirdRealtime from @messagebird/realtime, with appKey, region and authEndpoint |
| Authorization input socket_id, channel_name | JSON input connection_id, channel_name |
| Presence response channel_data | member_data, containing signed member_id and optional member_info |
| Server trigger publication | Server SDK realtime.publish(appId, { event, channels, data }) |
| Server exclusion socket_id | Bird publish exclusion exclude_connection_id |
| Pusher lifecycle bindings | Bird lifecycle bindings listed below; preserve application event names where appropriate |
| Cache channel with a last event | Bird cache channel with a repopulation path when the value is absent |
Pusher's authorization guide defines the source fields. Reuse your application's permission checks, then return a fresh Bird signature through Bird channel authorization. Renaming a presence field after signing changes the signed data: construct member_data first and sign that exact string with the Bird app secret.
The default Bird authorizer sends JSON. Update an endpoint that previously expected form data, and preserve your session and cross-origin policy. Keep the authorization decision on your server. A caller-supplied member ID or channel name does not establish access to another customer's order.
| Existing binding | Bird binding | Application action |
|---|---|---|
| pusher:subscription_succeeded | bird:subscription_succeeded | Render the initial view and refresh it after re-subscription. |
| pusher:subscription_error | bird:subscription_error | Show the refused subscription and inspect the authorization response. |
| pusher:member_added | bird:member_added | Read member.member_id. |
| pusher:member_removed | bird:member_removed | Remove that member's roster entry. |
| pusher:subscription_count | bird:connection_count | Read connection_count after enabling the app's counting settings. |
| pusher:cache_miss | bird:cache_miss | Load or republish current application state. |
The Pusher event reference describes its bindings. Bird's presence guide distinguishes members from open connections. One member can hold multiple tabs; do not change the displayed count from people to connections during the transition.
Pusher cache channels and Bird cache channels retain a latest event. Test both a hit and an empty or expired cache. Repopulate from the application record; a warm cache is not durable history. Preserve private-cache- or presence-cache- access semantics when mapping names.
Pusher encrypted channels need a server encryption key. Configure Bird encryption through its own encryptionMasterKey option and authorization helper, then test decryption with the Bird client. Do not infer ciphertext portability from a matching channel prefix. Retain the old keys and data needed to read historical records.
Build and test the receiving path
Create a separate Bird Realtime app. Record its app ID, public key, secret and region together. The browser uses the public key and region; your publisher uses an API key and the app credentials. Keep the API key and app secret on your server.
Run the complete Express and browser order application before changing customer traffic. It includes an authorized private subscription, two-tab presence, a stored order, and recovery after a lost connection. Its local demo session must be replaced by your application's authentication when integrating it.
Start with a private order channel and a presence room. Map the Pusher user_id you derived from your application session to Bird member_id; map only the profile fields you intend other subscribers to see into member_info.
The complete example includes runnable publisher, browser and authorization files. The relevant values line up as follows:
| Purpose | Example value | Keep consistent across |
|---|---|---|
| Customer identity | customer_ada | Application session and signed presence identity |
| Private order channel | private-order-42 | Server publish, browser subscription and permission check |
| Presence room | presence-order-42 | Browser subscription and allowed order membership |
| Application event | order-updated | Publisher and browser binding |
| Record version | Order version | Stored state, notifications and stale-read handling |
Recreate Realtime webhook subscriptions for the Bird app in the dashboard. A Pusher webhook handler using X-Pusher-* headers and a batch of events is not a Bird verifier: verify Bird's raw body and Standard Webhooks headers, then process its event envelope. Keep the two endpoint configurations separate during overlap. The Pusher webhook reference documents the original format.
| Test | Expected result |
|---|---|
| Publisher targets the Bird app | An authorized Bird client receives the intended application event. |
| Signed-out or different customer subscribes | Authorization refuses the request. |
| Same customer opens two tabs | One member, two connections; closing one tab does not remove the member. |
| Browser reconnects with a new connection ID | Authorization runs again and the latest application state is loaded. |
| Cache expires | The miss path restores state without inventing an event history. |
| Encrypted channel is used | An authorized Bird client decrypts; a refused caller receives no channel key. |
| A webhook is repeated | The application does not repeat a durable business action. |
Switch traffic and reconcile
Select an initial customer cohort and record which app its publisher, browser and authorization endpoint use. Roll those settings together. Two integrations can observe the same application event while the business action retains one owner.
Preserve event IDs or record versions through any period of dual publication. A retried notification should refresh a view, not create another order or charge. Confirm the customer result in the application database, then compare subscription errors, reconnect recovery, presence behavior and current usage.
Retain the Pusher app and its relevant data during the transition. To reverse a cohort, restore its publisher and client routing together and reload current application state. Keep historical application data, webhook records and encryption material accessible under your retention policy; creating a Bird app does not import them.
References and next steps
- Pusher Channels documentation.
- Complete Express/browser application and first-event setup.
- Publish an event, authorize channels, and connection lifecycle.
- Presence, cache channels, encryption, and webhooks.
- Realtime resources, migration directory, Realtime API, and pricing.
- Start now or talk to sales.
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.