HTTP API: Batch Events

This endpoint allows your backend server to publish multiple events to different channels in a single HTTP request. This can be more efficient than sending many individual requests if you need to trigger several events simultaneously.

Endpoint

POST /apps/{app_id}/batch_events

Path Parameters

• {app_id} (string, required): The ID of your application.

Authentication

Required. See HTTP API Overview.

Request Body

The request body must be JSON and should contain a single field:

• batch (array of event objects, required): An array where each object represents an event to be published. The maximum number of events in a batch is limited by event_limits.max_batch_size.

Each event object within the batch array has the following structure (similar to the single event publish endpoint):

• name (string, required): The name of the event.
• channel (string, required): The channel name to publish this specific event to. (Note: Unlike single event publishing, channels array is not typically used here; each event in the batch specifies its own single channel).
• data (string or object, required): The payload for the event.
• socket_id (string, optional): If provided, this event will not be sent to the client with this socket_id on the specified channel.

Example Request Body

{
  "batch": [
    {
      "channel": "user-123-notifications",
      "name": "new_message_alert",
      "data": "{\"sender\":\"Alice\",\"preview\":\"Hey there!\"}",
      "socket_id": "optional_socket_id_to_exclude_for_this_event"
    },
    {
      "channel": "live-updates",
      "name": "score_changed",
      "data": "{\"teamA\": 1, \"teamB\": 0}"
    },
    {
      "channel": "private-admin",
      "name": "system_alert",
      "data": "{\"message\":\"Maintenance window approaching.\"}"
    }
  ]
}


Query Parameters (for Authentication)
auth_key
auth_timestamp
auth_version
auth_signature
body_md5 (MD5 hash of the entire JSON request body, i.e., {"batch": [...]})
(Any other parameters included in the signature calculation by your Pusher server library)
Responses
200 OK: The batch of events was successfully accepted for publishing. The response body is typically an empty JSON object {}.
{}


400 Bad Request: The request was malformed (e.g., invalid JSON, batch array missing or malformed, individual events missing required fields, payload too large, too many events in batch).
{
  "error": "Invalid request: 'batch' array must contain valid event objects."
}


401 Unauthorized: Authentication failed.
{
  "error": "Authentication failed: Invalid signature."
}


403 Forbidden: Authenticated, but not authorized.
{
  "error": "Forbidden: Application is disabled."
}


413 Payload Too Large: The overall request body or individual event data payloads exceed configured limits.
Important Notes
Atomicity: The batch operation is generally not atomic in the sense that if one event in the batch is invalid, others might still be processed,