Skip to main content
Go to the Studio
Integrations

Microsoft Teams

Connect the agent to Microsoft Teams through the Bot Framework (single-tenant), with a manifest ready to publish.

Microsoft Teams

The Microsoft Teams integration lets the agent answer messages directly in your organisation's chat, through a bot registered in Azure / Bot Framework.

Reach it through the Settings icon → Integrations tab → the Microsoft Teams card.

Turning the integration on​

Turn on the toggle in the Microsoft Teams card. The configuration fields appear once it is on.

How it works​

  1. Teams sends an activity (a message, joining a conversation, an attachment) to Roberty's public endpoint.
  2. Roberty validates the JWT the Bot Framework issued (aud = the bot's appId).
  3. The agent matching the payload's tenantId is resolved and run.
  4. The answer goes back to Teams through the Bot Framework's own serviceUrl API, authenticated with OAuth2 client_credentials.

Roberty keeps each conversation's history (by conversationId), respecting the agent's Memory settings, so it has context between messages.

The configuration fields​

FieldWhat it is
Tenant IDThe Azure Active Directory tenant's ID (a UUID)
App ID (Bot)The Application (client) ID of the App Registration created in the Azure portal
App PasswordThe registered application's client secret
Welcome messageShown when a user starts a conversation in Teams (optional)

Prerequisites​

  • An App Registration and an Azure Bot (Azure Bot Service).
  • From the App Registration you need:
    • Application (client) ID → appId
    • Client secret → appPassword
    • Directory (tenant) ID → tenantId
The critical point — the bot is single-tenant

The bot only authenticates in its own tenant, so the App Registration has to exist in the same tenant as the Teams the bot will be used in. If your Azure account lives in a different tenant from Microsoft 365/Teams, create the App Registration in the Teams tenant (App registrations belong to Entra ID and need no Azure subscription). The Azure Bot resource can stay in your subscription, pointing at that app.

Setting the bot up in Azure​

1. Create the App Registration (in the Teams tenant)​

  1. At portal.azure.com, switch the directory to the Teams tenant.
  2. Microsoft Entra ID → App registrations → New registration.
  3. Under Supported account types, choose Accounts in this organizational directory only (single-tenant).
  4. Note the Application (client) ID and the Directory (tenant) ID.
  5. Under Certificates & secrets → New client secret, generate one and copy the value (shown once).

2. Create the Azure Bot​

  1. Create a resource → Azure Bot, type Single Tenant, option Use existing app registration.
  2. Enter the App ID and the App tenant ID (the Directory ID from the previous step).
  3. Under Configuration → Messaging endpoint, enter:
https://agent-backend.roberty.app/integrations/teams
  1. Under Channels, add the Microsoft Teams channel.
info

Roberty uses a single route for Teams and resolves the agent from the tenantId in the payload.

3. Configure the agent in Roberty​

On this screen, fill in Tenant ID, App ID, App Password and, if you want, the welcome message.

4. Download the manifest and publish it to Teams​

Use Download manifest (.zip) in the Teams card — it builds a ready package (manifest.json plus icons) from the agent's name and description and the App ID you entered. The button becomes available once there is an App ID filled in and a published version of the agent.

In the Teams client: Apps → Manage your apps → Upload an app → Upload a custom app, and select the .zip. (Uploading custom apps has to be allowed in the Teams admin.)

What it supports​

  • Conversation memory: the history is kept per conversation and bounded by the window set under the agent's Memory.
  • Ending a conversation: the user can send /reset (or /novaconversa, /encerrar, /limpar, /clear, /new) to finish — the agent writes a closing message and the history is cleared.
  • Attachments: files sent in the chat have their text extracted and handed to the agent. Documents (PDF, DOCX and the like) work natively; images depend on OCR.

Security validation​

Roberty validates every request:

  • The Authorization: Bearer <jwt> header is checked against the public keys at https://login.botframework.com/v1/.well-known/keys.
  • The token's audience must equal the appId configured on the agent.
  • The issuer must be https://api.botframework.com or https://sts.windows.net/<tenantId>/.

Requests with no token, or an invalid one, get a 401.

Troubleshooting​

SymptomLikely cause
AADSTS700016: Application ... was not found in the directoryThe App Registration is not in the tenant being used to authenticate — it has to exist in the Teams tenant (tenantId).
401 Invalid tokenThe appId configured on the agent does not match the App Registration's.
404 Agent not configured for tenantThe agent's tenantId does not match the organisation that sent the message.
The bot shows as "typing" and never answersThe appPassword is wrong or expired; check the secret.
The welcome message does not appearThe conversationUpdate event never arrived, or welcomeMessage is blank.
The manifest fails to validate on uploadThe App ID is not a valid GUID, or the agent has no published version.

References​