Microsoft Teams guide

Bring your own Azure Bot: register your app ID and password, paste the webhook URL into your Azure Bot's messaging endpoint, and your agent answers in Teams channels under your bot's identity.

Prerequisites#

• An Azure Bot resource (or an Azure App Registration with Bot Framework service connected) and its Application (client) ID and a client secret (app password). For single-tenant bots, also the Directory (tenant) ID.
• An AgentSky API token with write scope.

Register the channel app#

Register in Channel apps or through the API below. Teams must be enabled in the deployment; when disabled, existing apps remain readable and deletable, while new registration, credential rotation and connections are unavailable.

Registration proves the credentials by obtaining a Bot Framework client-credentials token from Azure AD. For multi-tenant bots (no tenant ID), leave app_tenant_id out. For single-tenant bots (Azure Bot created with a specific tenant), include app_tenant_id:

curl -s -X POST https://api.agentsky.dev/v1/channels/apps \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"platform": "teams", "label": "My bot", "credentials": {"app_id": "…", "app_password": "…"}}'
# -> { "id": "app_...", "setup": { "webhook_url": "https://.../webhooks/teams/app_..." } }

Single-tenant bots include app_tenant_id:

-d '{"platform": "teams", "label": "My bot", "credentials": {"app_id": "…", "app_password": "…", "app_tenant_id": "…"}}'

Finish in the Azure portal#

After registration, paste setup.webhook_url into your Azure Bot's Configuration → Messaging Endpoint. Azure verifies it with a signed JWT on the first message — the webhook validates it automatically.

Enable Microsoft Teams under the Azure Bot resource's Channels settings.

Install the Teams app#

The Azure Bot resource alone does not install your bot in Teams. Create an app in Developer Portal for Teams, complete its basic information, and add a Bot capability using the same Azure Application (client) ID. Select Personal for direct messages and Team for channel conversations; include Group chat only if you will use that scope.

Upload a color PNG and an outline PNG icon. Validate and download the app package: its ZIP must contain manifest.json and both referenced icon files at the root. Check that the manifest's bots[].botId matches the registered Azure bot and its scopes include the places where you will install it. See Microsoft's app package requirements.

For ordinary follow-ups without mentioning the bot, request resource-specific consent (RSC) in the app package. In Developer Portal, open Configure → Permissions: add ChannelMessage.Read.Group under Team permissions, and ChatMessage.Read.Chat under Chat/Meeting permissions if using group chats. The corresponding manifest fragment is:

{
  "webApplicationInfo": { "id": "<AZURE-APPLICATION-CLIENT-ID>", "resource": "https://RscBasedStoreApp" },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        { "name": "ChannelMessage.Read.Group", "type": "Application" },
        { "name": "ChatMessage.Read.Chat", "type": "Application" }
      ]
    }
  }
}

Include only permissions for the scopes you enable. These permissions let the provider deliver messages from the installed team or group chat, including messages without a mention; describe that access in your app information. The team or chat owner must consent during installation. After changing permissions, update the package version and upgrade or reinstall it in the target conversation so the new consent takes effect. See Microsoft's RSC message delivery instructions.

In Teams, use Apps → Manage your apps → Upload an app → Upload a custom app, select the ZIP, and install it for yourself or the chosen team. If custom upload is unavailable, your organization's Teams administrator must allow it or distribute the app through the organization's catalog. Complete installation before using the connection link below.

Connect#

Create a pending connection for the session you want to reach:

curl -s -X POST https://api.agentsky.dev/v1/channels/connections \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"platform": "teams", "app": "app_...", "destination": {"session": "sess-..."}}'
# -> { "id": "...", "status": "PENDING", "connect": { "code": "LINK:...", "expires_at": "...", "url": "https://teams.microsoft.com/..." } }

Open connect.url and send connect.code to the bot. To connect a channel instead, add the bot there and send the same code while mentioning the bot. Send only the code, with an optional bot mention; surrounding prose or mentions of other people do not claim a connection. The code expires after 15 minutes.

The connection becomes CONNECTED only after the message is received, and binds that specific conversation to the session. Other conversations using the same bot need their own connections. Changing the default session sends a notice back to the conversation where you linked the connection.

Capabilities#

The SDK supports Markdown messages, message edits, and reactions. Generic working/done/failed markers are not advertised for Teams. Proactive delivery targets an already connected conversation; it does not create an unsolicited chat with a new person. Streaming uses message edits through the channels API.

Troubleshooting#

• App creation answers 400 invalid_credentials — Azure AD rejected the app ID or client secret; re-copy both from the Azure portal (app ID is the Application (client) ID, not the object ID).
• platform_unavailable on registration — Azure AD was unreachable; retry in a moment.
• LINK works but ordinary follow-ups do not arrive — verify the matching RSC permission in the installed package and the team/chat owner's consent. A local AgentSky subscription cannot grant Teams permission; without RSC, continue mentioning the bot until the installation is upgraded.
• Bot receives nothing — confirm Microsoft Teams is enabled in Azure, the Teams package uses the same bot ID, and the app is installed in the intended personal or team scope. A direct-chat link does not replace installation.
• 401 on the messaging endpoint — the Bot Framework signature, issuer, app audience, or service URL failed validation. Check the Azure Bot app ID and messaging endpoint; direct unsigned requests are rejected.
• The LINK code does nothing — send the exact code, mention the bot in a channel, and mint a new connection if the code expired.