HTTP API: Channel Information

Sockudo provides HTTP API endpoints to retrieve information about channels, such as their status (occupied/vacant) and, for presence channels, the list of subscribed users.

1. Get Information for Multiple Channels

This endpoint retrieves information about one or more channels within your application.

Endpoint

GET /apps/{app_id}/channels

Path Parameters

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

Authentication

Required. See HTTP API Overview.

Query Parameters

• Authentication Parameters:
  • auth_key
  • auth_timestamp
  • auth_version
  • auth_signature
• Filtering Parameters:
  • filter_by_prefix (string, optional): Filters the list of channels to those whose names start with this prefix (e.g., private-, presence-).
  • info (string, optional): A comma-separated list of attributes to include for each channel.
    • occupied: (boolean) If the channel has at least one subscriber.
    • user_count: (integer, for presence channels only) The number of unique users subscribed to the channel.
    • subscription_count: (integer) The total number of connections subscribed to the channel.

Example Request

Get information about all channels prefixed with presence-, including their user_count:

GET /apps/my-app/channels?auth_key=...&auth_timestamp=...&auth_signature=...&filter_by_prefix=presence-&info=user_count,occupied

Responses

• 200 OK: Successfully retrieved channel information. The response body is a JSON object where keys are channel names.

  {
    "channels": {
      "presence-room-1": {
        "occupied": true,
        "user_count": 5
      },
      "presence-room-2": {
        "occupied": true,
        "user_count": 2
      },
      "private-user-updates-123": { // Example if not filtering by presence-
        "occupied": true
      }
    }
  }

  If no channels match or no attributes are requested/applicable, the inner objects might be empty or attributes omitted.

• 400 Bad Request: Invalid parameters.

• 401 Unauthorized: Authentication failed.

2. Get Information for a Single Channel

This endpoint retrieves information about a specific channel.

Endpoint

GET /apps/{app_id}/channels/{channel_name}

Path Parameters

• {app_id} (string, required): The ID of your application.
• {channel_name} (string, required): The name of the channel to query (e.g., presence-chat-room-42).

Authentication

Required.

Query Parameters

• Authentication Parameters:
  • auth_key
  • auth_timestamp
  • auth_version
  • auth_signature
• Filtering Parameters:
  • info (string, optional): A comma-separated list of attributes to include.
    • occupied: (boolean)
    • user_count: (integer, for presence channels)
    • subscription_count: (integer)

Example Request

GET /apps/my-app/channels/presence-chat-room-42?auth_key=...&auth_timestamp=...&auth_signature=...&info=occupied,user_count,subscription_count

Responses

• 200 OK: Successfully retrieved channel information.

  {
    "occupied": true,
    "user_count": 15, // Only if 'user_count' requested and it's a presence channel
    "subscription_count": 17 // Only if 'subscription_count' requested
  }

  If the channel does not exist or is not active, occupied might be false, and counts would be 0 or attributes omitted.

• 400 Bad Request: Invalid parameters.

• 401 Unauthorized: Authentication failed.

• 404 Not Found: The specified channel does not exist or has no information (behavior might vary; it could also return occupied: false).

3. Get Users in a Presence Channel

This endpoint retrieves the list of users currently subscribed to a specific presence channel.

Endpoint

GET /apps/{app_id}/channels/{channel_name}/users

Path Parameters

• {app_id} (string, required): The ID of your application.
• {channel_name} (string, required): The name of the presence channel (must start with presence-).

Authentication

Required.

Query Parameters

• Authentication Parameters:
  • auth_key
  • auth_timestamp
  • auth_version
  • auth_signature

Example Request

GET /apps/my-app/channels/presence-gameroom-abc/users?auth_key=...&auth_timestamp=...&auth_signature=...

Responses

• 200 OK: Successfully retrieved the list of users. The response body is a JSON object containing a users array. Each user object has an id (the user_id). Some implementations might also include the user_info if available and configured.

  {
    "users": [
      { "id": "user_1" },
      { "id": "user_5" },
      { "id": "user_alpha" }
    ]
  }

  If the channel is not a presence channel, is empty, or does not exist, the users array will be empty or an error might be returned.

• 400 Bad Request: Invalid parameters (e.g., channel name is not a presence channel).

• 401 Unauthorized: Authentication failed.

• 404 Not Found: The specified presence channel does not exist.