Skip to main content
The Microsoft 365 connector gives the agent read-only access to your Outlook mailbox, your calendars, and your OneDrive and SharePoint documents. Nothing can be sent, created, modified or deleted.

​
Setup

Most organizations only need Step 1. The Azure app registration in Advanced setup is optional and only required if your security policy forbids third-party multi-tenant applications.

​
Step 1: Add the connector

  1. Go to Connectors, open the APIs tab, and choose Microsoft 365.
  2. Choose who signs in:
    • OAuth (Workspace-level): one Microsoft account is connected and shared with everyone you give access to.
    • OAuth (Per-member): each member who uses the connector signs in with their own Microsoft account.
  3. Choose which kinds of access to enable: Only the access you enable is requested at sign-in, so you can connect calendar alone without granting mailbox access. Turning on more access later takes effect after the account signs in again.
  4. Optionally enable Metadata only (see Privacy).
  5. Click Connect, sign in, and review the consent screen.
  6. Click Save.
The connector is private to you until you share it from the APIs tab. With workspace-level sign-in, everyone you share it with reads the connected account, so share it only with people who should see that mailbox.
Sites.Read.All usually requires a Microsoft 365 administrator to grant consent for the whole tenant. If you are not an administrator and enable SharePoint, sign-in will show an “approval required” prompt. Either ask your administrator to approve it, or leave SharePoint off.

​
Step 2: Use it in a chat

Ask normally in any chat that can use API connectors. It composes with your warehouse and BI connectors, so you can ask questions that span both.

​
Advanced: bring your own Azure application

Use this only if your organization requires that the application registration live in your own tenant.
Azure client secrets expire, typically after 6 to 24 months. When yours does, the connector stops working until you create a new secret and sign in again. Set a calendar reminder before the expiry date. Connectors using the platform application have no such expiry.

​
Register the application

  1. In the Azure Portal, go to Microsoft Entra ID → App registrations → New registration.
  2. Name it, choose Accounts in any organizational directory, and click Register.
  3. Under Authentication, click Add a platform → Web and add this redirect URI:
    If you run a VPC or custom deployment, replace https://app.textql.com with your own host, for example https://textql.yourcompany.com/auth/api-oauth/callback.
  4. Under Certificates & secrets, create a New client secret and copy the Value immediately.
  5. Under API permissions, add these Microsoft Graph → Delegated permissions, matching the capabilities you plan to enable:
    • User.Read and offline_access (always required)
    • Mail.Read for Outlook mail
    • Calendars.Read for calendar
    • Files.Read.All for OneDrive
    • Sites.Read.All for SharePoint

​
Use it in the connector form

Click Use your own OAuth app in the connector form and paste the Application (Client) ID and Client Secret before clicking Connect. Leave Tenant as common unless you want to restrict sign-in to a single directory, in which case use your tenant ID or domain.

​
Privacy

Metadata only mode restricts the connector to non-content fields. When it is on:
  • Available: message and file ids, sender and recipient addresses, timestamps, read and attachment flags, file sizes and types, event times and durations.
  • Withheld: subjects, message bodies, file names, file contents, event titles, locations and attendee lists.
Content is never requested from Microsoft in this mode, not merely filtered after the fact.

​
Troubleshooting

The redirect URI registered in Azure does not match the one TextQL uses. It must be exactly https://<your-host>/auth/api-oauth/callback, with no trailing slash. Applications registered for the earlier Microsoft 365 connector need this new redirect URI added. This only applies to bring-your-own-application setups.
The stored grant is no longer valid. Common causes: the refresh token expired after a long period of inactivity, an administrator revoked consent, the account password changed, or (for bring-your-own-application setups) the Azure client secret expired. Open the connector on the APIs tab and click Connect to sign in again. The connector keeps its id, so chats and agents referencing it keep working.
Sign-in succeeded but a specific Graph permission was not consented. The message names the access that is missing. Either have an administrator grant the permission, or turn that access off and sign in again.
The tenant requires administrator consent for one of the requested permissions, most often Sites.Read.All. Ask a Microsoft 365 administrator to approve the application, or turn off SharePoint and sign in again.
Results are bounded so a single question cannot pull an entire mailbox. When more matched than were returned, the agent is told the result was truncated and should say so. Narrow the date range or add filters for full coverage.