Microsoft Teams#
How to let your team ask the OSPREY agent questions from a Microsoft Teams channel or chat, and get answers, plots and files back in the same conversation.
Before you start
A project whose build profile has a
dispatch:block — see Event Dispatch.Docker or Podman, for the container path.
An Azure subscription in which you can create an app registration, a bot, a Service Bus namespace and a Function App.
Permission to add an app to your Teams tenant, or a Teams administrator who will do it for you.
The Azure CLI (
az) and the Azure Functions Core Tools (func), signed in to that subscription.
Overview#
The bridge turns a Teams conversation into a way of talking to the agent. Someone mentions the bot in a channel or writes to it in a chat. The question is handed to the event dispatch pipeline, and the answer is posted back in the same conversation.
Teams differs from the other two platforms in one way that shapes the setup. A Teams bot receives messages only as an HTTPS POST to an address reachable from the public internet — there is nothing for the bridge to read from. So the deployment has two pieces rather than one:
A relay: a small Azure Function that is the bot’s public address. It checks that each incoming message really came from Microsoft, and puts it on a Service Bus queue. It is four files that ship with Osprey; you publish them, you do not write them.
The bridge itself, running in your stack beside the dispatcher. It pulls that queue, and posts replies back through the bot connector.
The bridge is therefore still a reader of a queue, not a server. It opens no port, and nothing has to be able to reach it. That is what lets it run on a control-room network with no inbound path from the internet. The relay is the only public surface, and the only thing it can do is put a validated message on your queue.
Like every bridge, it remembers each question and conversation. What is particular to Teams is that there is no reading position to keep. A message the bridge has not finished with stays on the queue. So anything sent while the bridge was down is waiting when it comes back.
Each question gets an acknowledgement as soon as it is picked up, and the answer when the run finishes, each as its own message. Any plots and files follow as further messages. Nothing is edited after it is posted. In a channel all of them are threaded under the question itself. A one-to-one or group chat has no threads in Teams. There the acknowledgement and the answer open with a quote of the question’s first line, so it is clear which message is being answered.
Note
If your tenant is GCC High, the differences are two configuration values,
not a different deployment. Set TEAMS_CLOUD=gcchigh on the bridge and the
same setting on the relay. The sovereign-cloud login host, token scope,
signing-key metadata address and issuer are all selected from that one value.
Point the CLI at the right cloud first with az cloud set --name
AzureUSGovernment, and read azurewebsites.us wherever the commands below
say azurewebsites.net. Everything else on this page is the same.
Enable It in a Profile#
Add a teams_bridge: block to your build profile. It holds two settings:
Which dispatcher trigger the bridge fires. That trigger decides what the agent is allowed to do with a chat question.
Whether the agent may @mention people.
The block is only meaningful next to a dispatch: block:
teams_bridge:
trigger: teams-question # default; must exist in your triggers file
mentions: true # default; false posts @mentions as plain text
dispatch:
triggers: my_triggers.yml # the file that trigger must be declared in
worker_count: 1
env:
required:
- TEAMS_APP_ID
- TEAMS_APP_SECRET
- TEAMS_TENANT_ID
- TEAMS_SERVICEBUS_CONNECTION_STRING
- TEAMS_SERVICEBUS_QUEUE
Note
The bridge and the dispatch pair must sit on the same network. Workers go on
the host’s network whenever the agent has to reach a control system or a
co-deployed bridge at a loopback address (Network attachment: bridge or host).
This bridge then has to move with them: add
services.teams_bridge.network: host to your profile’s config: block.
osprey build refuses a split pair and names the key to change.
The bot’s credentials and the queue it reads are not profile settings. Which
tenant this deployment authenticates in and which queue it drains differ per
deployment. The client secret and the connection string are also secrets that
must never be baked into a build. Listing them under env.required documents
them in .env.example. Fill the values into the profile’s .env, which
is where a secret survives a rebuild. The build derives the project’s .env
from it (created mode 0600, readable only by you).
Two mistakes are caught at build time rather than at runtime: declaring the
bridge without a dispatch: block, and naming a trigger your triggers file
does not declare. Both fail the build with a message naming the problem.
Runtime settings#
These are the ones you create and set yourself.
Variable |
Meaning |
|---|---|
|
The bot’s app-registration (client) id, a GUID. It is also what an @mention is matched against, so a wrong value makes the bridge ignore every channel message instead of failing loudly — worth double-checking. The relay needs the same value. |
|
The client secret of that app registration, which the bridge exchanges for
a token to post with. A secret: it belongs in the |
|
The directory (tenant) id the app registration lives in. Single-tenant bots have no default for this. |
|
Connection string for the queue the relay writes to, taken from the
Listen-only policy ( |
|
The name of that queue. Read the warning below before pointing a second deployment at it. |
|
Optional. Leave it unset, or set it to |
|
Optional. The drive id of the one document library the bot shares files from (see step 9). Unset, files the bridge cannot post inline are named in a closing note rather than shared. |
|
Optional. A folder inside that library, such as |
The bridge refuses to start if any of the required five is missing, naming all the missing variables at once.
Warning
One bridge per queue. Deploy exactly one bridge against a given queue. Service Bus hands each message to only one of a queue’s readers. So a second deployment pointed at the same queue does not get its own copy of every message. It silently splits them: each bridge answers only the messages it happened to receive. The other questions look to your team like they were ignored, and nothing anywhere logs an error. The second deployment can be a staging stack, a container someone forgot to remove, or another facility reusing the name. Give every deployment its own queue, and its own relay writing to it.
Settings that are filled in for you, or safe to leave alone
Variable |
Meaning |
|---|---|
|
The trigger to fire. Comes from the profile block. |
|
Whether @mentions are on. Comes from the profile block. |
|
The two shared secrets the bridge needs to reach the dispatcher and the worker, generated for you when unset — see Authentication. |
|
Where the dispatcher and worker are — the bridge collects answers and files from the worker directly. Filled in for you when they run in the same stack; when they run elsewhere you must set them, and the bridge refuses to start without them. |
|
How long the worker may spend on one run. Comes from your project configuration, so raising it raises it for both halves at once. |
|
How long the bridge waits for an answer before giving up on it. Defaults to 30 seconds more than the worker’s own limit, and may never be less than that limit — the bridge refuses to start if it is. |
|
Seconds between checks on an answer in progress (default 2). |
|
Seconds between sweeps of the queue of questions that could not be handed off yet (default 60). |
|
How long a failed hand-off is held before it is retried, so a brief outage has time to clear (default 20 minutes). |
|
Age at which a question that still cannot be handed off is abandoned (default 48 hours). |
|
Hard ceiling on how long anything may sit in that queue, whatever its state (default 7 days). |
|
Set to |
|
Longest earlier answer, in characters, sent back in full with a
follow-up (default 3000). A longer one is sent as its opening, and the
agent reads the rest only if it needs it. |
|
Optional alert host. With |
|
A release label shown with each acknowledgement, so a conversation
shows which version answered: the acknowledgement reads |
|
Where the bridge keeps the questions it has answered. It defaults to
a file under |
|
Timezone, taken from your project configuration so timestamps match the rest of the stack. |
Bring It Up#
The commands below use one set of names throughout: resource group
osprey-teams, namespace osprey-teams-bus, queue osprey-questions and
Function App osprey-teams-relay. You can paste them in order and change the
names once, at the top. Namespace, Function App and storage-account names are
part of a public address, so they must be unique across Azure; pick something
with your facility in it if these are taken.
1. Create a resource group to hold everything.
az login
az group create --name osprey-teams --location westus2
On a GCC High tenant, run az cloud set --name AzureUSGovernment before
az login, and use one of that cloud’s regions (for example usgovvirginia)
throughout.
2. Give this deployment its own queue. One namespace, and one queue that nothing else reads — see the warning above for what a shared queue does.
az servicebus namespace create \
--resource-group osprey-teams --name osprey-teams-bus --sku Standard
az servicebus queue create \
--resource-group osprey-teams --namespace-name osprey-teams-bus \
--name osprey-questions
3. Create one key for writing and one for reading. The relay may only send, the bridge may only listen; neither half holds the other’s rights.
az servicebus queue authorization-rule create \
--resource-group osprey-teams --namespace-name osprey-teams-bus \
--queue-name osprey-questions --name relay-send --rights Send
az servicebus queue authorization-rule create \
--resource-group osprey-teams --namespace-name osprey-teams-bus \
--queue-name osprey-questions --name bridge-listen --rights Listen
Then read the two connection strings out. Keep them somewhere safe for steps 5 and 8; they are credentials.
az servicebus queue authorization-rule keys list \
--resource-group osprey-teams --namespace-name osprey-teams-bus \
--queue-name osprey-questions --name relay-send \
--query primaryConnectionString --output tsv
az servicebus queue authorization-rule keys list \
--resource-group osprey-teams --namespace-name osprey-teams-bus \
--queue-name osprey-questions --name bridge-listen \
--query primaryConnectionString --output tsv
4. Register the bot and the identity it speaks as. The registration’s name is internal. The name your team sees replying is the one you give the Teams app in step 7. Single-tenant keeps the bot usable only inside your own directory.
az ad app create --display-name "OSPREY agent" --sign-in-audience AzureADMyOrg \
--query appId --output tsv
az account show --query tenantId --output tsv
Note both values — they are TEAMS_APP_ID and TEAMS_TENANT_ID. Then create
a client secret, which is shown once and never again:
az ad app credential reset --id <app id> --display-name teams-bridge \
--query password --output tsv
Now create the bot resource. Its messaging endpoint is the relay’s address. You can write it down before the relay exists. It is the Function App name you are going to use in step 5:
az bot create \
--resource-group osprey-teams --name osprey-agent-bot --sku F0 \
--app-type SingleTenant --appid <app id> --tenant-id <tenant id> \
--endpoint https://osprey-teams-relay.azurewebsites.net/api/messages
az bot msteams create --resource-group osprey-teams --name osprey-agent-bot
The second command turns on the Teams channel; without it the bot exists but Teams will not talk to it.
5. Create the relay’s Function App. Use Flex Consumption with one always-ready instance. Teams expects an answer from the endpoint within 15 seconds. An app that has scaled to nothing spends most of that budget starting up.
az storage account create \
--resource-group osprey-teams --name ospreyteamsrelay \
--location westus2 --sku Standard_LRS
az functionapp create \
--resource-group osprey-teams --name osprey-teams-relay \
--storage-account ospreyteamsrelay \
--flexconsumption-location westus2 \
--runtime python --runtime-version 3.11
az functionapp scale config always-ready set \
--resource-group osprey-teams --name osprey-teams-relay \
--settings http=1
Then give it its settings. These are the relay’s own names and are not the
bridge’s. In particular, the connection string here is the relay-send one.
The setting is called SERVICEBUS_CONNECTION because the Functions host reads
it directly, so the send key never passes through the relay’s own code.
az functionapp config appsettings set \
--resource-group osprey-teams --name osprey-teams-relay \
--settings TEAMS_APP_ID=<app id> \
TEAMS_SERVICEBUS_QUEUE=osprey-questions \
SERVICEBUS_CONNECTION="<the relay-send connection string>"
On a GCC High tenant add TEAMS_CLOUD=gcchigh to that same command. Leave it
unset anywhere else.
6. Publish the relay. osprey build copies it into your deployment
repository, under build/services/teams_bridge/relay/. Publish from that
directory:
cd build/services/teams_bridge/relay
func azure functionapp publish osprey-teams-relay --python
The endpoint is then live at
https://osprey-teams-relay.azurewebsites.net/api/messages — the address you
gave the bot in step 4. It accepts anonymous requests on purpose. The proof that
a message is genuine is the signed token Microsoft sends with it. The relay
checks that token against the bot’s app id before anything reaches your queue. A request
that fails that check is refused and never enqueued.
7. Install the app in Teams. Build a Teams app package — a manifest.json
plus its two icons, zipped — whose bots entry carries the app id from step 4:
{
"bots": [
{
"botId": "<app id>",
"scopes": ["team", "groupChat", "personal"],
"supportsFiles": false,
"isNotificationOnly": false
}
]
}
Upload it in the Teams admin center, or in Teams itself if your tenant allows custom apps, then add the app to each team or chat it should serve. It only sees conversations it has been added to.
8. Fill in the environment file. Set the values in the profile’s .env
(the build derives the project’s .env from it):
TEAMS_APP_ID=00000000-0000-0000-0000-000000000000
TEAMS_APP_SECRET=the-secret-from-step-4
TEAMS_TENANT_ID=11111111-1111-1111-1111-111111111111
TEAMS_SERVICEBUS_CONNECTION_STRING=<the bridge-listen connection string>
TEAMS_SERVICEBUS_QUEUE=osprey-questions
# TEAMS_CLOUD=gcchigh # only on a GCC High tenant
9. Optional: give the bot one file library. Without one, the bridge posts plots inline and names every other file it could not deliver. With one, it uploads those files there and shares each with the people in the conversation. Create or pick a SharePoint document library that nobody else reads. A shared file keeps the library’s own permissions as well as the per-conversation share. So a library with broad membership shares wider than the conversation.
First look up the site and the library ids:
SITE_ID=$(az rest --method get \
--url "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/osprey-files" \
--query id -o tsv)
LIST_ID=$(az rest --method get \
--url "https://graph.microsoft.com/v1.0/sites/$SITE_ID/lists" \
--query "value[?displayName=='OSPREY files'].id" -o tsv)
In the app registration from step 4, add the Microsoft Graph application
permission Lists.SelectedOperations.Selected and grant admin consent. That
permission reaches no list until one is granted to the app. An administrator who
holds Sites.FullControl.All then grants the app the owner role on this
one library — owner is what lets it share a file; write is not enough:
POST https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/permissions
Content-Type: application/json
{
"roles": ["owner"],
"grantedTo": {"application": {"id": "<TEAMS_APP_ID>"}}
}
Read the library’s drive id:
az rest --method get \
--url "https://graph.microsoft.com/v1.0/sites/$SITE_ID/lists/$LIST_ID/drive" \
--query id -o tsv
Then add the two variables to the profile’s .env, with the drive id the
command printed:
TEAMS_FILES_DRIVE_ID=b!the-drive-id
TEAMS_FILES_FOLDER=osprey/answers
On GCC High the Graph host follows TEAMS_CLOUD (graph.microsoft.us).
Confirm your cloud offers the Selected permissions before you set a library,
and leave it unset if it does not.
10. Bring the stack up. The bridge is registered in deployed_services, so
it starts with everything else:
osprey up # add --dev to bake in a local osprey checkout
Then mention the bot in a channel it has been added to and ask it something. If nothing happens, work outwards from the bridge: a missing credential stops it at startup with the missing variable named. A wrong app id is the quieter failure. The bridge runs happily and ignores every channel message, because nothing it sees looks like a mention of itself. If the bridge looks idle, check the Function App’s logs. A message refused there never reaches the queue. A relay whose settings name the wrong queue writes where nobody is reading.
Important
The bridge keeps what it remembers — which questions it has answered and the
recent conversation — in a named volume mounted at /data. Do not remove
that volume. Without it, a restart in the middle of a question can answer it
twice or drop it, and conversations lose their thread of context.