Microsoft Teams query tutorial

Learn how to query teams, channels, chats, and messages in Microsoft Teams.

After setting up a Microsoft Teams integration with Retool, your Microsoft Teams resource is available to use in the query editor. Microsoft Teams queries are backed by the Microsoft Graph API, so Retool exposes each available Graph operation for you to select and configure.

Create a query

Classic app

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

To create a Microsoft Teams query in a Retool app:

1. In the Retool app IDE, open the Code tab, then click + in the page or global scope.
2. Select Resource query.
3. Choose your Microsoft Teams resource.
4. Select an operation and configure its parameters.

Workflow or agent

Workflows and agent custom tools use the same Resource query block to query Microsoft Teams.

1. Add a Resource query block to your workflow or custom tool's function canvas.
2. Choose your Microsoft Teams resource.
3. Select an operation and configure its parameters.

Custom tools use the same block-based canvas as workflows, so the steps are identical in either context.

Query configuration fields

Microsoft Teams queries are operation-driven: Retool reads the available operations from the Microsoft Graph OpenAPI spec, and the fields shown depend on which operation you select. Refer to the Microsoft Graph API reference for the full list of available operations and their parameters.

Operation

Select the Microsoft Graph operation to run, such as listing a team's channels or sending a channel message. Retool groups operations by resource path, and shows the HTTP method (GET, POST, PATCH, DELETE) alongside each one.

Path

Path parameters required by the selected operation, such as a team ID or channel ID.

Example

{{ table1.selectedRow.data.teamId }}

Query

Optional query-string parameters for the selected operation, such as $filter, $top, or $select for OData query options.

Example

$top: 25
$filter: displayName eq {{ teamNameInput.value }}

Request body

For operations that create or update data, the JSON request body to send.

Example: send a channel message

{
  "body": {
    "content": {{ messageInput.value }}
  }
}

Auto-paginate

Enable to automatically fetch every page of results in a single query execution, rather than one page at a time. When enabled, set a Limit on the total number of records to fetch.

Common use cases

These examples demonstrate common Microsoft Teams operations in Retool apps. For the complete set of available operations, refer to the Microsoft Graph API reference.

list teams

First, create a query named listTeamsQuery and select the List joinedTeams operation (GET /me/joinedTeams).

Next, add a Table component to the app and set its Data property to {{ listTeamsQuery.data.value }}.

list channels in a team

First, create a query named listChannelsQuery and select the List channels operation (GET /teams/{team-id}/channels).

Set the Path parameter:

Field	Value
team-id	{{ table1.selectedRow.data.id }}

Next, add a Select component and set its Options property to {{ listChannelsQuery.data.value }} so users can choose a channel.

post a message to a channel

First, add a Text area component (messageInput) for composing a message.

Next, create a query named sendChannelMessageQuery and select the Create chatMessage in channel operation (POST /teams/{team-id}/channels/{channel-id}/messages).

Set the Path parameters:

Field	Value
team-id	{{ table1.selectedRow.data.id }}
channel-id	{{ channelSelect.value }}

Set the Request Body:

Example request body

{
  "body": {
    "content": {{ messageInput.value }}
  }
}

Then, add an event handler to a button's Click event that runs sendChannelMessageQuery and shows a success notification.

list messages in a chat

First, create a query named listChatMessagesQuery and select the List messages in a chat operation (GET /chats/{chat-id}/messages).

Set the Path parameter:

Field	Value
chat-id	{{ chatSelect.value }}

Next, add a Table component and set its Data property to {{ listChatMessagesQuery.data.value }}.

send a chat message

First, add a Text area component (chatMessageInput) for composing a message.

Next, create a query named sendChatMessageQuery and select the Send chatMessage in a chat operation (POST /chats/{chat-id}/messages).

Set the Path parameter:

Field	Value
chat-id	{{ chatSelect.value }}

Set the Request Body:

Example request body

{
  "body": {
    "content": {{ chatMessageInput.value }}
  }
}

Then, add an event handler that runs sendChatMessageQuery when the button is clicked and refreshes listChatMessagesQuery.

Best practices

Follow these best practices to keep Microsoft Teams queries fast, efficient, and safe.

Performance

• Cache responses: For data that doesn't change frequently, such as a list of teams, enable query caching to reduce API calls and improve response times.
• Use $top and $filter: Limit result size and narrow results server-side with OData query parameters instead of filtering large payloads in the browser.
• Enable auto-paginate carefully: Only enable auto-pagination for operations that return large result sets, and set a reasonable limit to avoid long-running queries.
• Minimize payload size: Use $select to request only the fields you need from an operation's response.
• Set appropriate timeouts: Configure query timeouts based on expected Microsoft Graph response times to prevent hung requests.

Data integrity

• Validate user input: Sanitize and validate all user input before including it in a request body or path parameter to prevent malformed requests.
• Handle errors gracefully: Configure error notifications and fallback behavior for failed queries, since Graph API rate limits can cause transient failures.
• Verify responses: Check response status codes and validate response data structure before using it in your app.
• Implement retry logic: For transient failures or throttling responses, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.
• Log query activity: Enable query logging to track requests and responses for debugging and auditing.

Troubleshoot authentication errors

If queries fail with an authentication or permission error, check the following:

• Missing scope: Confirm the resource's OAuth scopes include the Microsoft Graph permission required by the operation you're calling. Reconnect with OAuth after adding a scope.
• Expired token: If the connected account's credentials have expired or been revoked in Azure AD, reconnect the resource with OAuth.
• Tenant restrictions: Confirm your Microsoft 365 tenant's admin consent policies allow the requested permissions for the Azure AD app being used.