Users API Reference

This document provides detailed information about the Users module endpoints in the Hooks API, which handle user-related operations through HTTP endpoints and Pub/Sub messaging.

Overview

The Users module exposes two main integration points:

1. HTTP endpoints for user-related tasks via the UsersTasksController
2. Pub/Sub messaging channels for asynchronous user operations via the UserPubSubHandlerService

HTTP Endpoints

Update User Location

Updates a user's location information based on their IP address.

GET /users/tasks/update-location/:userId/:sessionId/:ipAddress

Path Parameters:

• userId: The ID of the user to update
• sessionId: The ID of the user's session
• ipAddress: The IP address to geolocate

Headers:

• x-api-key: Required API key for authentication

Role Required: CLOUD_TASKS

Response:

{
  "success": true
}

Example Request:

GET /users/tasks/update-location/5f8a23b9c6d7e43a1f0c9876/6e21f7bc45d8a2c91b3e5432/203.0.113.1

Notes:

• This endpoint is primarily intended for internal use by Cloud Tasks
• The endpoint updates both user and session records with geolocation data
• For US users, the state is automatically set to Alaska (AK)

Pub/Sub Messaging

The Users module listens to the following Pub/Sub topics:

USER_CHAT_INFO_TOPIC

This topic handles messages related to user chat integration.

User Info Message

Message Name: UserChatMessageNames.USER_INFO

Payload Structure:

{
  id?: string;           // User ID
  badhombreId?: string;  // BadHombre platform ID
  username: string;      // Username
  avatarUrl: string;     // Profile image URL
}

Purpose: Updates a user's information in Stream Chat and adds them to all livestream channels.

Example:

// Publishing a USER_INFO message
await googlePubSubProvider.publishMessage(
  USER_CHAT_INFO_TOPIC,
  UserChatMessageNames.USER_INFO,
  {
    id: 'user123',
    username: 'player1',
    avatarUrl: 'https://example.com/avatars/player1.jpg',
  },
);

User Channel Member Message

Message Name: UserChatMessageNames.USER_CHANNEL_MEMBER

Payload Structure:

{
  channelId: string; // Channel ID to add users to
}

Purpose: Adds all active users to a specific chat channel.

Example:

// Publishing a USER_CHANNEL_MEMBER message
await googlePubSubProvider.publishMessage(
  USER_CHAT_INFO_TOPIC,
  UserChatMessageNames.USER_CHANNEL_MEMBER,
  {
    channelId: 'livestream-channel-123',
  },
);

Security

• All HTTP endpoints are protected by API key authentication
• Role-based access control restricts endpoints to authorized services
• Pub/Sub messaging is secured through Google Cloud Platform security mechanisms

Error Handling

• HTTP endpoints return a standard success response even in some error cases
• Pub/Sub message handlers log errors but continue processing
• Batch processing is used for large operations to prevent timeouts

Usage Considerations

Rate Limiting

No explicit rate limits are defined, but consider these practical limitations:

• MaxMind geolocation service may have query limits
• Stream Chat API has rate limits for user creation and channel operations
• Batch operations should be used for large-scale user updates

Processing Time

• User location updates are typically processed quickly (< 1 second)
• Chat membership operations for large user sets may take considerable time due to batch processing

Best Practices

1. Use Cloud Tasks for scheduling user location updates
2. Leverage Pub/Sub for asynchronous chat user management
3. Handle errors appropriately in services that publish messages
4. Avoid triggering large-scale operations during peak usage times