Difference between revisions of "HTTP API/Bot Commands/avatar groups"
From SmartBots Developers Docs
(Created page with "{{DISPLAYTITLE: avatar_groups (HTTP Bot Command)}} <onlyinclude>Returns a list of a resident's groups.</onlyinclude> {{API Variables Table}} {{API HTTP Required Vars|avatar_...") |
|||
| (2 intermediate revisions by the same user not shown) | |||
| Line 7: | Line 7: | ||
{{API Variable Group|Input}} | {{API Variable Group|Input}} | ||
| − | {{API Variable|avatar}} Avatar UUID to fetch groups for | + | {{API Variable|avatar|yes}} Avatar UUID to fetch groups for |
| − | {{API Variable|skipnames}} Skip group (do not return) if its name contains this substring (case insensitive) | + | {{API Variable|skipnames|no}} Skip group (do not return) if its name contains this substring (case insensitive) |
| − | {{API Variable|matchnames}} Return only groups those which names contain this substring (case insensitive) | + | {{API Variable|matchnames|no}} Return only groups those which names contain this substring (case insensitive) |
| − | {{API Variable|matchuuid}} Return groups with this UUID only | + | {{API Variable|matchuuid|no}} Return groups with this UUID only |
{{API Variable Group|Output}} | {{API Variable Group|Output}} | ||
| Line 22: | Line 22: | ||
{{API Variables Table End}} | {{API Variables Table End}} | ||
| − | == Working with large lists == | + | == Usage comments == |
| + | |||
| + | === Working with large lists === | ||
LSL llHttpRequest() function has a limitation on reply size (it is being cut to 2048 bytes, or 1024 Unicode characters). If the resident has a lot of groups, they may not fit into the http reply. | LSL llHttpRequest() function has a limitation on reply size (it is being cut to 2048 bytes, or 1024 Unicode characters). If the resident has a lot of groups, they may not fit into the http reply. | ||
| Line 31: | Line 33: | ||
* ''matchnames'' - list only groups which names contain a specific substring | * ''matchnames'' - list only groups which names contain a specific substring | ||
* ''matchuuid'' - return specific group by UUID | * ''matchuuid'' - return specific group by UUID | ||
| + | |||
| + | === Limits === | ||
| + | |||
| + | Due to the high SL asset server load the bot's rate of this API command is limited to 5 requests per 30 seconds. | ||
== Return value == | == Return value == | ||
| Line 47: | Line 53: | ||
<syntaxhighlight lang="http"> | <syntaxhighlight lang="http"> | ||
| − | + | https://www.mysmartbots.com/api/bot.html?action=avatar_groups&botname=BarKeeeper%20Resident&avatar=cd93067e-7c4e-41c0-ba91-be01f4bafe35 | |
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 67: | Line 73: | ||
<syntaxhighlight lang="http"> | <syntaxhighlight lang="http"> | ||
| − | + | https://www.mysmartbots.com/api/bot.html?action=avatar_groups&botname=BarKeeeper%20Resident&avatar=cd93067e-7c4e-41c0-ba91-be01f4bafe35&matchnames=earn2life | |
</syntaxhighlight> | </syntaxhighlight> | ||
Latest revision as of 19:53, 10 May 2019
Returns a list of a resident's groups.
Variables
The following table shows input values (you send them with the API call) and returned output values.
| Variable | Required | Description | ||
|---|---|---|---|---|
| This API command applies only for Standard bot | ||||
| Input basic parameters: | ||||
| action | yes | = avatar_groups | ||
| apikey | yes | Your personal developer's API key. | ||
| botname | yes | Your bot's SL login. | ||
| secret | yes | 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: | ||||
| avatar | yes | Avatar UUID to fetch groups for | ||
| skipnames | optional | Skip group (do not return) if its name contains this substring (case insensitive) | ||
| matchnames | optional | Return only groups those which names contain this substring (case insensitive) | ||
| matchuuid | optional | Return groups with this UUID only | ||
| Output: | ||||
| (to be received in http_response LSL event, see docs for details) | ||||
| result | OK - command completed successfully FAIL - command failed | |||
| resulttext | Detailed reason for the failure. | |||
| custom | The value from input "custom" parameter. See above. | |||
| total | The total number of groups (regardless of any filters, see below). | |||
| groups | The list of resident's groups: UUIDs and names.
This list may be affected by skip* and match* parameters. See the "Return value" section below. | |||
Usage comments
Working with large lists
LSL llHttpRequest() function has a limitation on reply size (it is being cut to 2048 bytes, or 1024 Unicode characters). If the resident has a lot of groups, they may not fit into the http reply.
There are several solutions for this problem. Use the following parameters:
- skipnames - ignore groups which names contain this substring
- matchnames - list only groups which names contain a specific substring
- matchuuid - return specific group by UUID
Limits
Due to the high SL asset server load the bot's rate of this API command is limited to 5 requests per 30 seconds.
Return value
total - variable contains the total number of resident's groups. It is not affected by skip* or match* parameters.
groups - the list of groups (probably filtered by skip* and match*): a string which contains both object UUIDs and names separated by newline ("\n"):
UUID1 name of the group 1 UUID2 name of the group 2 ...
Examples
Example request to get the resident's groups:
https://www.mysmartbots.com/api/bot.html?action=avatar_groups&botname=BarKeeeper%20Resident&avatar=cd93067e-7c4e-41c0-ba91-be01f4bafe35
A response from the bot:
0b4a7c17-4e2b-bc96-34c1-4cb6e67a9fd2 SLBiz2Life - Advertisers Support 0b65a122-8f77-64fe-5b2a-225d4c490d9c SmartBots: group invitation bots 0e6ce87d-d86e-9225-9e0f-cea9fb24313e Capital Exchange Stock Market 0ec6f039-1a39-339c-3c68-e31ed2dc703f Earn2Life.com Discount Shops 24dcd8e6-3406-1518-b9ba-8653c1be09eb Earn2Life.com partnership 41ff4c6b-e3c0-a2b9-f53b-797e78532374 Earn2Life - earn L$500-1000 a day 4fbbee90-b278-e1b9-0ec9-251da2390c6c Earn2Life.com Investors (EARN) 5c63bbff-7064-0849-e8a7-25dff3d1765f Earn2Life.com Training Group 9e325390-c5e0-de09-3921-1501d34f9b38 Earn2Life Pay4Observe Support c63983a8-f9b6-cb4b-6cdd-87da2f679a8e SmartBots Investors (BOTS) cee972ee-e1af-3da5-6846-36b89a041fa4 SmartBots Franchise
The same request, groups filtered by name (only those which contain "earn2life"):
https://www.mysmartbots.com/api/bot.html?action=avatar_groups&botname=BarKeeeper%20Resident&avatar=cd93067e-7c4e-41c0-ba91-be01f4bafe35&matchnames=earn2life
Response from the bot:
0ec6f039-1a39-339c-3c68-e31ed2dc703f Earn2Life.com Discount Shops 24dcd8e6-3406-1518-b9ba-8653c1be09eb Earn2Life.com partnership 41ff4c6b-e3c0-a2b9-f53b-797e78532374 Earn2Life - earn L$500-1000 a day 4fbbee90-b278-e1b9-0ec9-251da2390c6c Earn2Life.com Investors (EARN) 5c63bbff-7064-0849-e8a7-25dff3d1765f Earn2Life.com Training Group 9e325390-c5e0-de09-3921-1501d34f9b38 Earn2Life Pay4Observe Support
<< return back to Bot commands
(Miss an API call or parameter? Submit your request in forum)
