Microsoft Teams bots
A Teams bot registration connects one FYAI agent or team to Microsoft Teams. People message the bot in Teams; FYAI runs the conversation with your agent or team and posts the replies back into Teams.
You manage registrations under Settings → Teams Bots (in the Organization group). Each registration belongs to the project you're in when you create it.
How it works
Teams user ──► Azure Bot Service ──► FYAI messaging endpoint
│
finds the registration by Azure App ID
│
runs a chat session with your agent or team
│
Teams user ◄── Adaptive Card reply ◄──────┘
- Each Teams conversation maps to one FYAI chat session. Follow-up messages in the same Teams conversation continue that session, so the agent keeps the context.
- The bot's @mention is removed from the message before it reaches the agent.
- Teams shows a typing indicator while the agent works.
- The reply is posted as an Adaptive Card containing the agent's messages and, for transparency, each tool it called (🔧 tool) and a short excerpt of each result (✅ tool result, cut to 500 characters).
- When the bot is added to a conversation it posts a welcome card ("I'm connected to an AI agent that can help with your requests. Just send a message to get started.").
Before you start
You need:
- An Azure Bot resource in your Azure tenant, with its Microsoft App ID and a client secret (app password). For a single-tenant bot, also its Azure tenant ID.
- The Microsoft Teams channel enabled on the Azure Bot, and a Teams app that installs the bot for your users. This is done in Azure and Teams, not in FYAI.
- In FYAI, an agent or team to connect, and permission to create integrations and Editor-level API keys in the project.
Set up a Teams bot
-
Store the bot's credentials in an integration. Create an integration (see Managing integrations) with these secrets:
Secret name Value MICROSOFT_APP_IDThe Azure Bot's Microsoft App ID (required) MICROSOFT_APP_PASSWORDThe app's client secret MICROSOFT_APP_TENANT_IDYour Azure tenant ID, for a single-tenant bot (optional) -
Create the registration. Go to Settings → Teams Bots and select New Registration. Fill in the fields (see Registration fields) and select Save.
-
Point Azure at FYAI. In the Azure Bot's configuration, set the Messaging endpoint to:
https://notification.fyai.co.nz/bot/api/messages -
Test it. Message the bot in Teams. You should see the typing indicator, then the agent's reply.
When you save a new registration, FYAI creates an API key for it on your behalf, named bot- followed by the display name, with the Editor project role and valid for 365 days. The bot uses this key to act in your project, so you need to be allowed to create Editor-level API keys (see Members and roles). Deleting the registration revokes the key. After 365 days the key expires and the bot stops answering; recreate the registration to issue a new one.
Registration fields
| Field | Required | Description |
|---|---|---|
| Display Name | Yes | Name shown in the registration list, for example "Support Agent Bot" |
| Azure Microsoft App ID | Yes | The Azure Bot's App ID. FYAI uses it to route incoming Teams messages to this registration, so use one registration per Azure Bot |
| Chat Type | Yes | Single Agent or Direct (both talk to one agent) or Agent Team (talks to a team) |
| Agent | For Single Agent / Direct | The agent that answers |
| Agent Team | For Agent Team | The team that answers |
| Integration (credentials) | Yes | The integration holding the secrets above |
| Active toggle | — | Active — bot will respond to Teams messages or Disabled — bot will not respond |
The list shows each registration's name, chat type, target and an Active or Disabled chip. Select a registration to edit it, then Save; select Delete to remove it (Delete Bot Registration? — this disconnects the bot from Teams, active conversations stop getting replies, and it can't be undone).
The Integration (credentials) helper text in the app also mentions a BOT_AGENTAPI_API_KEY secret, and the registration details say credentials can come from environment variables when no integration is linked. Neither applies: FYAI creates the bot's API key itself, and a registration without a linked integration can't answer messages.
Behaviour and limits
| Behaviour | Detail |
|---|---|
| Response wait | FYAI collects the agent's reply for up to 90 seconds per message. A slow run is cut off at that point and whatever has arrived is posted |
| No approvals in Teams | Teams conversations run unattended. Teams has no way to answer an approval request, so connect agents whose tools don't need approval |
| Connected accounts | Tools that use personal sign-ins use your organisation's shared (service) connection, not the Teams user's own account. If there isn't one, the agent is told the connection is missing |
| Not in your Chat list | Teams conversations run under the bot's own identity, so they don't appear in anyone's conversation list on the Chat page |
| Text only | Only the message text is passed to the agent |
Troubleshooting
| Message in Teams | Cause |
|---|---|
| "No FYAI agent is configured for this channel. Please set up a bot registration in the FYAI platform." | No active registration matches the Azure Bot's App ID |
| "Bot is not fully configured. Please check the integration credentials." or "Bot authentication failed. Please check the API key configuration." | The integration's secrets or the registration's API key couldn't be used |
| "Failed to start a chat session." | FYAI couldn't start a session with the agent or team, for example because it was deleted |
| "The agent did not return a response. Please try again." | The agent produced no reply within the wait |
If Teams shows nothing at all, check that:
- the Azure Bot's messaging endpoint is set as above
- the registration is Active and its Azure Microsoft App ID matches the Azure Bot
- an integration is linked and holds
MICROSOFT_APP_IDandMICROSOFT_APP_PASSWORD - the registration's API key hasn't expired or been revoked (recreate the registration if it has)