Pusher integration enables you to stream WhatsApp events to Pusher channels for easy real-time integration with web and mobile applications without managing WebSocket infrastructure.
Configuration Configure Pusher through environment variables.
Basic Setup # Enable Pusher integration PUSHER_ENABLED = true
Global Pusher Configuration Configure a global Pusher app to receive events from all instances:
# Enable global Pusher PUSHER_GLOBAL_ENABLED = true # Pusher app credentials PUSHER_GLOBAL_APP_ID = your_app_id PUSHER_GLOBAL_KEY = your_app_key PUSHER_GLOBAL_SECRET = your_app_secret PUSHER_GLOBAL_CLUSTER = us2 # Use TLS/SSL encryption PUSHER_GLOBAL_USE_TLS = true
Setting Up Pusher
Create Pusher Account
Sign up at pusher.com and create a new Channels app.
Get Credentials
Copy your app credentials from the Pusher dashboard:
App ID
Key
Secret
Cluster
Configure Evolution API
Add credentials to your .env file: PUSHER_GLOBAL_APP_ID = 123456 PUSHER_GLOBAL_KEY = abcdef123456 PUSHER_GLOBAL_SECRET = secret123456 PUSHER_GLOBAL_CLUSTER = us2
Restart Evolution API
Restart the API to apply changes.
Available Events Configure which events are sent to Pusher:
Instance Events
Message Events
Contact Events
Chat & Group Events
Other Events
# Application lifecycle PUSHER_EVENTS_APPLICATION_STARTUP = true # Connection events PUSHER_EVENTS_QRCODE_UPDATED = true PUSHER_EVENTS_CONNECTION_UPDATE = true
# Message events PUSHER_EVENTS_MESSAGES_SET = true PUSHER_EVENTS_MESSAGES_UPSERT = true PUSHER_EVENTS_MESSAGES_EDITED = true PUSHER_EVENTS_MESSAGES_UPDATE = true PUSHER_EVENTS_MESSAGES_DELETE = true PUSHER_EVENTS_SEND_MESSAGE = true PUSHER_EVENTS_SEND_MESSAGE_UPDATE = true
# Contact events PUSHER_EVENTS_CONTACTS_SET = true PUSHER_EVENTS_CONTACTS_UPSERT = true PUSHER_EVENTS_CONTACTS_UPDATE = true PUSHER_EVENTS_PRESENCE_UPDATE = true
# Chat events PUSHER_EVENTS_CHATS_SET = true PUSHER_EVENTS_CHATS_UPSERT = true PUSHER_EVENTS_CHATS_UPDATE = true PUSHER_EVENTS_CHATS_DELETE = true # Group events PUSHER_EVENTS_GROUPS_UPSERT = true PUSHER_EVENTS_GROUPS_UPDATE = true PUSHER_EVENTS_GROUP_PARTICIPANTS_UPDATE = true
# Label events PUSHER_EVENTS_LABELS_EDIT = true PUSHER_EVENTS_LABELS_ASSOCIATION = true # Call events PUSHER_EVENTS_CALL = true # Typebot integration PUSHER_EVENTS_TYPEBOT_START = false PUSHER_EVENTS_TYPEBOT_CHANGE_STATUS = false
Per-Instance Configuration Configure Pusher with separate credentials for each instance:
curl -X POST https://your-api.com/pusher/set/instance_name \ -H "apikey: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "pusher": { "enabled": true, "appId": "123456", "key": "your_app_key", "secret": "your_app_secret", "cluster": "us2", "useTLS": true, "events": [ "MESSAGES_UPSERT", "MESSAGES_UPDATE", "QRCODE_UPDATED", "CONNECTION_UPDATE" ] } }'
Channel Structure Events are published to channels named after your instances:
Channel : Instance name (e.g., my_instance)Event : Event name in lowercase with dots (e.g., messages.upsert)
Each WhatsApp instance publishes to its own dedicated Pusher channel.
Subscribing to Events Connect to Pusher channels and listen for events:
JavaScript
HTML
Python
Swift (iOS)
Kotlin (Android)
import Pusher from 'pusher-js' ; // Initialize Pusher const pusher = new Pusher ( 'YOUR_APP_KEY' , { cluster: 'us2' , encrypted: true }); // Subscribe to instance channel const channel = pusher . subscribe ( 'my_instance' ); // Listen for events channel . bind ( 'messages.upsert' , ( data ) => { console . log ( 'New message:' , data ); console . log ( 'From:' , data . sender ); console . log ( 'Instance:' , data . instance ); console . log ( 'Message data:' , data . data ); }); channel . bind ( 'qrcode.updated' , ( data ) => { console . log ( 'QR Code updated' ); // Note: QR code base64 is removed for Pusher to reduce size console . log ( 'QR Code data:' , data . data . qrcode ); }); channel . bind ( 'connection.update' , ( data ) => { console . log ( 'Connection status:' , data . data . state ); if ( data . data . state === 'open' ) { console . log ( 'WhatsApp connected!' ); } }); // Connection state pusher . connection . bind ( 'connected' , () => { console . log ( 'Connected to Pusher' ); }); pusher . connection . bind ( 'error' , ( err ) => { console . error ( 'Pusher error:' , err ); });
Event Payload Structure All events have a consistent structure:
{ "event" : "messages.upsert" , "instance" : "my_instance" , "data" : { "key" : { "remoteJid" : "[email protected] " , "fromMe" : false , "id" : "3EB0XXXXX" }, "message" : { "conversation" : "Hello from WhatsApp!" }, "messageTimestamp" : 1709550600 , "pushName" : "John Doe" }, "destination" : "123456" , "date_time" : "2024-03-04T10:30:00.000Z" , "sender" : "5511999999999" , "server_url" : "https://your-evolution-api.com" , "apikey" : "instance_api_key" }
For qrcode.updated events, the base64 field is removed to reduce payload size. Only the QR code string is sent.
Payload Size Limit Pusher has a 10 KB message size limit. Evolution API:
Checks payload size before sendingRemoves base64 from QR codes automaticallyLogs errors if payload exceeds 10 KBDrops oversized messages with error log
If you receive payload size errors, reduce the events enabled or filter data before sending.
Best Practices
Use Presence Channels for Authentication
For production apps, use Pusher’s presence channels with server-side authentication: const channel = pusher . subscribe ( 'presence-my_instance' );
Enable Only Required Events
Reduce bandwidth and costs by enabling only necessary events: PUSHER_EVENTS_MESSAGES_UPSERT = true PUSHER_EVENTS_MESSAGES_UPDATE = true # Disable others PUSHER_EVENTS_CONTACTS_SET = false
Monitor Pusher Metrics
Use Pusher Dashboard to monitor:
Connection count
Message volume
API usage
Handle Connection States
Always handle connection state changes: pusher . connection . bind ( 'state_change' , ( states ) => { console . log ( 'State changed:' , states . previous , '->' , states . current ); });
Use TLS in Production
Always enable TLS for production: PUSHER_GLOBAL_USE_TLS = true
Pusher Clusters Choose a cluster close to your users for lower latency:
mt1 - US East (N. Virginia)us2 - US East (Ohio)us3 - US West (Oregon)eu - EU (Ireland)ap1 - Asia Pacific (Singapore)ap2 - Asia Pacific (Mumbai)ap3 - Asia Pacific (Tokyo)ap4 - Asia Pacific (Sydney)
Troubleshooting
Verify Pusher app key is correct
Check cluster matches your Pusher app
Ensure Pusher app is not suspended
Check browser console for specific errors
Verify PUSHER_ENABLED=true
Verify instance is connected to WhatsApp
Check that specific events are enabled in configuration
Verify you’re subscribed to correct channel (instance name)
Check Evolution API logs for Pusher errors
Use Pusher Debug Console to see live events
Check Evolution API logs for specific events
Disable events with large payloads (e.g., MESSAGES_SET)
Contact Pusher support for higher limits (paid plans)
Consider switching to Webhook or WebSocket for large payloads
Reduce number of enabled events
Use per-instance Pusher apps instead of global
Implement client-side filtering
Consider switching to WebSocket for high-volume scenarios
Authentication errors (per-instance)
Verify all Pusher credentials are correct
Check appId, key, and secret match your Pusher app
Ensure cluster is correctly set
Test credentials in Pusher Debug Console