list_people
Retrieve and organize user data within Webex by listing people based on email, name, ID, roles, or location. Facilitates targeted access and management of user details via the Webex Messaging API.
Instructions
List people in an organization using the Webex Messaging API.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| callingData | No | Include Webex Calling user details in the response. | |
| displayName | No | List people whose name starts with this string. For non-admin requests, either this or email are required. | |
| No | List people with this email address. For non-admin requests, either this or displayName are required. | ||
| id | No | List people by ID. Accepts up to 85 person IDs separated by commas. | |
| locationId | No | List people present in this location. | |
| max | No | Limit the maximum number of people in the response. | |
| orgId | No | List people in this organization. Only admin users of another organization may use this parameter. | |
| roles | No | List of roleIds separated by commas. |
Implementation Reference
- The main handler function `executeFunction` that builds the Webex `/people` API URL with query parameters, performs a GET request using fetch, handles errors, and returns the list of people or an error object.const executeFunction = async ({ email, displayName, id, orgId, roles, callingData = true, locationId, max = 100 }) => { try { // Construct the URL with query parameters const url = new URL(getWebexUrl('/people')); if (email) url.searchParams.append('email', email); if (displayName) url.searchParams.append('displayName', displayName); if (id) url.searchParams.append('id', id); if (orgId) url.searchParams.append('orgId', orgId); if (roles) url.searchParams.append('roles', roles); if (locationId) url.searchParams.append('locationId', locationId); url.searchParams.append('callingData', callingData.toString()); url.searchParams.append('max', max.toString()); // Set up headers for the request const headers = getWebexHeaders(); // Perform the fetch request const response = await fetch(url.toString(), { method: 'GET', headers }); // Check if the response was successful if (!response.ok) { const errorData = await response.json(); throw new Error(errorData); } // Parse and return the response data const data = await response.json(); return data; } catch (error) { console.error('Error listing people:', error); return { error: 'An error occurred while listing people.' }; } };
- The input schema definition for the `list_people` tool, specifying parameters like email, displayName, id, etc., with types, descriptions, and required fields.parameters: { type: 'object', properties: { email: { type: 'string', description: 'List people with this email address. For non-admin requests, either this or displayName are required.' }, displayName: { type: 'string', description: 'List people whose name starts with this string. For non-admin requests, either this or email are required.' }, id: { type: 'string', description: 'List people by ID. Accepts up to 85 person IDs separated by commas.' }, orgId: { type: 'string', description: 'List people in this organization. Only admin users of another organization may use this parameter.' }, roles: { type: 'string', description: 'List of roleIds separated by commas.' }, callingData: { type: 'boolean', description: 'Include Webex Calling user details in the response.' }, locationId: { type: 'string', description: 'List people present in this location.' }, max: { type: 'integer', description: 'Limit the maximum number of people in the response.' } }, required: ['email'] }
- The `apiTool` object that bundles the handler function and tool definition (including name 'list_people' and schema), which is exported and dynamically loaded by the tools discovery system.const apiTool = { function: executeFunction, definition: { type: 'function', function: { name: 'list_people', description: 'List people in an organization using the Webex Messaging API.', parameters: { type: 'object', properties: { email: { type: 'string', description: 'List people with this email address. For non-admin requests, either this or displayName are required.' }, displayName: { type: 'string', description: 'List people whose name starts with this string. For non-admin requests, either this or email are required.' }, id: { type: 'string', description: 'List people by ID. Accepts up to 85 person IDs separated by commas.' }, orgId: { type: 'string', description: 'List people in this organization. Only admin users of another organization may use this parameter.' }, roles: { type: 'string', description: 'List of roleIds separated by commas.' }, callingData: { type: 'boolean', description: 'Include Webex Calling user details in the response.' }, locationId: { type: 'string', description: 'List people present in this location.' }, max: { type: 'integer', description: 'Limit the maximum number of people in the response.' } }, required: ['email'] } } } }; export { apiTool };
- tools/paths.js:52-52 (registration)The path to the list_people tool file listed in toolPaths array, used by lib/tools.js to dynamically import and register the tool.'webex-public-workspace/webex-messaging/list-people.js',
- lib/tools.js:7-16 (registration)The `discoverTools` function that dynamically imports all tools from paths listed in toolPaths, spreads their apiTool, and adds the path for bulk registration.export async function discoverTools() { const toolPromises = toolPaths.map(async (file) => { const module = await import(`../tools/${file}`); return { ...module.apiTool, path: file, }; }); return Promise.all(toolPromises); }