SentianceInsights-Control-TowerLegacy DocsImportant Security Notice

Technical Details

This section provides technical details to help you integrate the Social Groups feature into your application, including examples of GraphQL queries and mutations.

Group Management

Manage social groups effectively within your application using intuitive group management features.

Invitation-Based Groups

  • Registration Codes: Groups are invitation-based, utilising unique registration codes that can be shared.

  • Sharing Invitations: Users share the registration code with family and friends to invite them to join a group.

  • Secure Access: Only those with the registration code can request to join, keeping groups secure.

Membership Requests and Roles

  • Membership Approval: Existing group members can accept or decline membership requests from new users.

  • User Roles: Each member within a group is assigned a specific role:

    • ADMIN: Has full control over group settings, including managing members and approving requests.

    • MEMBER: Standard participant with access to all group features.

    • PENDING: Users who have requested to join the group and are awaiting approval.

  • Role Management: ADMINs can change the roles of members as needed to maintain group integrity.

Managing Groups

  • Approving Requests: Members receive notifications of pending requests and can approve or deny them.

  • Maintaining Privacy: The role system ensures that only approved members have access to the group's information and features.

Technical Implementation

Group Features

Groups have specific features selected during creation, which determine their behavior in subsequent mutations and queries. These features, such as live location tracking, leaderboard rankings, or Points of Interest (POIs), influence how the group’s data is managed and retrieved.

Available features:

  • leaderboard: set flag with_leaderboard to true

  • event feed: set flag with_feed to true

  • live locations: set flag with_locations to true

  • points of interest: set flag with_poi to true

Create Group Mutation

Description: Creates a new social group with specified attributes.

mutation Create_group(
  $features: CreateUserEngagementGroupRequest_UserEngagementGroupFeaturesInput, # Group features
  $name: String, # Name of the group
  $group_type: UserEngagementGroupTypeEnum, # Type of the group (e.g., SOCIAL)
  $origin: String, # Origin of the group (e.g., 'client_app')
  $ranking_attributes: [UserEngagementGroupRankingAttributeEnum] # Attributes for group ranking
) {
  create_group(
    features: $features,
    name: $name,
    group_type: $group_type,
    origin: $origin,
    ranking_attributes: $ranking_attributes
  ) {
    group {
      group_id # ID of the created group
      name # Name of the created group
      created_at # Timestamp of creation
      reg_code # Registration code to be used by other users to request memebership
    }
    status # Success or failure status
  }
}

# VARIABLES
{
  "features": { "with_locations": true },
  "name": "My Social Group",
  "group_type": "SOCIAL",
  "origin": "client_app",
  "ranking_attributes": ["DRIVER_COACHING_SCORE"]
}

Remove Group Membership Mutation

Description: Removes a user from a specified group.

mutation Remove_group_membership(
  $removed_user_id: String, # ID of the user to remove
  $group_id: String # ID of the group
) {
  remove_group_membership(
    removed_user_id: $removed_user_id,
    group_id: $group_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "removed_user_id": "abc123",
  "group_id": "xyz789"
}

Update Group Mutation

Description: Updates details of an existing group.

mutation Update_group(
  $group_id: String, # ID of the group to update
  $name: String # New name of the group
) {
  update_group(
    group_id: $group_id,
    name: $name
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "abc123",
  "name": "Updated Group Name"
}

Delete Group Mutation

Description: Deletes a group using its ID.

mutation Delete_group($group_id: String) { # ID of the group to delete
  delete_group(group_id: $group_id) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "abc123"
}

Approve Group Join Mutation

Description: Approves a pending request for a user to join a group.

mutation Approve_group_join(
  $pending_user_id: String, # ID of the pending user
  $group_id: String # ID of the group
) {
  approve_group_join(
    pending_user_id: $pending_user_id,
    group_id: $group_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "pending_user_id": "user123",
  "group_id": "group456"
}

Decline Group Join Mutation

Description: Declines a pending request for a user to join a group.

mutation Decline_group_join(
  $group_id: String, # ID of the group
  $pending_user_id: String # ID of the pending user
) {
  decline_group_join(
    group_id: $group_id,
    pending_user_id: $pending_user_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "pending_user_id": "user456"
}

Make Group Admin Mutation

Description: Assigns a user as an admin of a group.

mutation Make_group_admin(
  $group_id: String, # ID of the group
  $new_admin_user_id: String # ID of the new admin user
) {
  make_group_admin(
    group_id: $group_id,
    new_admin_user_id: $new_admin_user_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "new_admin_user_id": "user456"
}

Unmake Group Admin Mutation

Description: Removes a user's admin privileges in a group.

mutation Unmake_group_admin(
  $group_id: String, # ID of the group
  $removed_admin_user_id: String # ID of the admin to remove
) {
  unmake_group_admin(
    group_id: $group_id,
    removed_admin_user_id: $removed_admin_user_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "removed_admin_user_id": "user456"
}

Join Group Mutation

Description: Allows a user to join a group using a registration code.

mutation Join_group($reg_code: String) { # Registration code of the group
  join_group(reg_code: $reg_code) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "reg_code": "reg789"
}

Leave Group Mutation

Description: Allows a user to leave a group.

mutation Leave_group($group_id: String) { # ID of the group
  leave_group(group_id: $group_id) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group456"
}

Set In-Group Status Mutation

Description: Sets a specific status for a user within a group.

mutation Set_in_group_status(
  $status: String, # Status of the user in the group
  $expire_in: Int, # Expiration time in seconds
  $group_id: String # ID of the group
) {
  set_in_group_status(
    status: $status,
    expire_in: $expire_in,
    group_id: $group_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "status": "Active",
  "expire_in": 31536000,  # 1 year
  "group_id": "group123"
}

Create Group POI Mutation

Description: Creates a new Point of Interest (POI) within a group.

mutation Create_group_poi(
  $group_id: String, # ID of the group
  $poi: EngagementPOIInput # POI details
) {
  create_group_poi(
    group_id: $group_id,
    poi: $poi
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "poi": {
    "name": "Central Park",
    "coordinates": {
      "latitude": 40.785091,
      "longitude": -73.968285
    },
    "radius": 100
  }
}

Delete Group POI Mutation

Description: Deletes a Point of Interest (POI) from a group.

mutation Delete_group_poi(
  $group_id: String, # ID of the group
  $poi_id: String # ID of the POI
) {
  delete_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "poi_id": "poi456"
}

Subscribe Group POI Mutation

Description: Subscribes to updates related to a POI in a group.

mutation Subscribe_group_poi(
  $group_id: String, # ID of the group
  $poi_id: String # ID of the POI
) {
  subscribe_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "poi_id": "poi789"
}

Unsubscribe Group POI Mutation

Description: Unsubscribes from updates related to a POI in a group.

mutation Unsubscribe_group_poi(
  $group_id: String, # ID of the group
  $poi_id: String # ID of the POI
) {
  unsubscribe_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "poi_id": "poi789"
}

Group Members Query

Description: Retrieves the members of a specific group, including their roles, status, and location details.

query getGroupMembers($user_id: String, $group_id: String) {
  user(user_id: $user_id) {
    engagement {
      groups(group_id: $group_id) {
        slice {
          members {
            slice {
              poi_subscriptions
              user_id
              role
              status
              status_expires_at
              joined_at
              last_known_location {
                latitude
                longitude
                timestamp
              }
              current_poi {
                poi_id
                poi_details {
                  name
                  coordinates {
                    latitude
                    longitude
                  }
                }
                entered_poi_at
              }
            }
          }
        }
      }
    }
  }
}

# VARIABLES
{
  "user_id": "xyz789",
  "group_id": "abc123"
}

Group Leaderboard Query

Description: Retrieves leaderboard details for a specific group, including user ranks and scores.

query getGroupLeaderboard($user_id: String, $group_id: String) {
  user(user_id: $user_id) {
    engagement {
      groups(group_id: $group_id) {
        slice {
          leaderboard {
            slice {
              user_id
              rank
              ranking_attr
              ranking_score
            }
          }
        }
      }
    }
  }
}

# VARIABLES
{
  "user_id": "xyz789",
  "group_id": "abc123"
}

Group Feed Query

Description: Retrieves the feed messages of a specific group.

query getGroupFeed($user_id: String, $group_id: String) {
  user(user_id: $user_id) {
    engagement {
      groups(group_id: $group_id) {
        slice {
          feed {
            slice {
              message
              params
            }
          }
        }
      }
    }
  }
}

# VARIABLES
{
  "user_id": "xyz789",
  "group_id": "abc123"
}

Group POIs Query

Description: Retrieves the points of interest (POIs) for a specific group.

query getGroupPOIs($user_id: String, $group_id: String) {
  user(user_id: $user_id) {
    engagement {
      groups(group_id: $group_id) {
        slice {
          points_of_interest {
            slice {
              poi_id
              poi_details {
                name
                coordinates {
                  latitude
                  longitude
                }
                address {
                  city
                }
              }
            }
          }
        }
      }
    }
  }
}

# VARIABLES
{
  "user_id": "xyz789",
  "group_id": "abc123"
}

Additional helpful links:

PreviousSocial GroupsNextAccessing Sentiance Insights

Last updated