# Technical Details

## 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 <mark style="color:blue;">**with\_leaderboard**</mark> to <mark style="color:blue;">**true**</mark>
* event feed: set flag <mark style="color:blue;">**with\_feed**</mark> to <mark style="color:blue;">**true**</mark>
* live locations: set flag <mark style="color:blue;">**with\_locations**</mark> to <mark style="color:blue;">**true**</mark>
* points of interest: set flag <mark style="color:blue;">**with\_poi**</mark> to <mark style="color:blue;">**true**</mark>

### Create Group Mutation

**Description:** Creates a new social group with specified attributes.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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.

<pre class="language-graphql"><code class="lang-graphql"><strong>mutation Delete_group_poi(
</strong>  $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"
}
</code></pre>

### &#x20;Subscribe Group POI Mutation

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

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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"
}
```

### &#x20;**Group Feed Query**

**Description:** Retrieves the feed messages of a specific group.

```graphql
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.

```graphql
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:

* [GQL](https://graphqldocs.sentiance.com/#introduction) definition