# group_list_2

Returns the bot’s groups list in JSON format.

```csharp
// See "LSL Helper Functions" page for this function

smartbotsAPI("group_list_2", []);
```

# Variables

The following table shows input values (you send them with the API call) and returned output values.

## Input basic parameters

| Variable | Required | Description |
|----------|----------|-------------|
| action   | yes      | = **group_list_2** |
| apikey   | yes      | Your personal [developer's API key](/doc/developers-api-key-tw8bQj4LSJ) |
| botname  | yes      | Your bot's SL login |
| secret   | yes      | [Bot access code](https://www.mysmartbots.com/docs/Bot_access_code) of your bot |
| dataType | optional | Set to "json" to get JSON reply instead of URL-encoded string |
| custom   | optional | The custom data (string) to be passed back to caller script. This value will be returned back to the caller in HTTP response |

## Input

| Variable | Required | Description |
|----------|----------|-------------|
| limit_name | optional | List only the groups whose name contains this text (case-insensitive) |
| limit_uuid | optional | List only the groups whose UUID exactly matches this value |
| with_roles | optional | Set to `1`to include roles of each group.<br>⚠️ Makes the command slower (up to **15 seconds**) |
| with_titles | optional | If `with_roles`is set, this parameter adds current active title information.<br>⚠️ Makes the command even slower (up to **30 seconds**) |

## Output

*(To be received in* `*http_response*` *LSL event, see* [*docs for details*](/doc/doing-http-api-calls-c6FSEMF7bP)*)*

| Variable | Description |
|----------|-------------|
| result   | OK - command completed successfully<br>FAIL - command failed |
| resulttext | Detailed reason for the failure |
| custom   | The value from input "custom" parameter. See above |
| groups   | JSON array containing the bot’s groups (see below) |

# Return value

This command returns complex data and is **only available** when requesting JSON output (`dataType=json`).  
The response can be quite large for LSL HTTP queries (limited to 1024 characters).  
To reduce data size, use the `limit_name` or `limit_uuid` parameters.

`groups` array contains groups:

```typescript
interface group_list_2.Group {
	// Group UUID
	uuid: UUID;
 	// Group name
	name: string;
 	// Is this an active (current) group of the bot
	active: boolean;
	
 	// Group roles available for bot
	roles: {
 		// Role UUID
		uuid: UUID;
  		// Role name
		name: string;
  		// Role title (tag)
		title: string;
  		// Role description
		description: string;
		titleSelected: string;
	}[];
	
 	// Is group open to join
	open: boolean;
 	// Group join fee
	fee: number;
 	// The list of group permissions, comma separated
	permissions: string;
	
 	// Wherever bot configured to receive notices from this group
	acceptNotices: boolean;
 	// Is group is published to bot's web profile
	allowPublish: boolean;
 	// Is group is shown in bot's profile
	listInProfile: boolean;
}
```

# Example

The following is an example of the groups list returned:

```json
{
  "action": "group_list_2",
  "result": "OK",
  "groups": [
    {
      "name": "SmartBots: group invitation bots",
      "uuid": "0b65a122-8f77-64fe-5b2a-225d4c490d9c",
      "fee": 0,
      "open": 0,
      "permissions": "Invite,JoinChat,ReceiveNotices",
      "roles": [
        {
          "name": "Owners",
          "uuid": "044ad014-7298-eb70-0945-85d6df01f154",
          "title": "SmartBots CEO",
          "description": "These are the owners of the group. They always have FULL POWER over the group.",
          "titleSelected": false
        },
        {
          "name": "SmartBots",
          "uuid": "10d7e54f-7c52-8f0e-7ad8-7e0059664cd0",
          "title": "SmartBots",
          "description": "",
          "titleSelected": false
        }
      ],
      "acceptNotices": true,
      "listInProfile": true,
      "allowPublish": false
    }
  ]
}
```