Microsoft Teams custom agents

Status: Current | Last reviewed: 2026-06-15

Tenant admins can publish a TrueServe agent as a Microsoft Teams custom app for 1:1 personal chat.

Note: Microsoft Teams custom agents are behind deployment feature flags (NEXT_PUBLIC_FEATURE_TEAMS for the panel and FEATURE_TEAMS for runtime endpoints, both off by default). If you don't see Teams under agent Settings, ask your platform administrator to enable it. Settings now save automatically as you edit — there is no Save button.

Before you start

You need:

V1 is text-only and personal-chat only. Channel chats, group chats, Teams SSO account linking, Adaptive Cards, proactive messages, and Copilot publishing are future phases.

Setup order

There are two Microsoft-side objects:

The Teams Upload app option is therefore the last step, not the first one.

  1. Ask your Microsoft admin to create a Teams conversation bot or Azure Bot registration for this TrueServe agent.
  2. Ask the admin for the Microsoft tenant ID, bot app/client ID, and a new client secret.
  3. In TrueServe, open the agent, select Settings, and turn on Enable Teams agent.
  4. Paste the Microsoft values into the Teams settings — they save automatically.
  5. Copy the TrueServe Messaging endpoint.
  6. Ask the Microsoft admin to paste that endpoint into the bot resource's messaging endpoint setting.
  7. Return to TrueServe and select Download Teams app package.
  8. Upload the package to Teams, or give it to the Teams admin for org publishing.
  9. Install the app in personal scope and start a 1:1 chat with the agent.

Microsoft admin request

Send this request to the Microsoft admin:

Please create a Microsoft Teams conversation bot / Azure Bot registration for a TrueServe agent.

Configuration needed:
- Single-tenant bot in our Microsoft tenant
- Teams channel enabled
- Personal scope only is sufficient for V1
- Public HTTPS messaging endpoint will be provided after TrueServe config is saved

Please send back:
- Microsoft tenant ID
- Bot app / client ID
- New client secret value
- Application ID URI, if SSO metadata is being configured

After TrueServe generates the messaging endpoint, send the admin:

Please set this as the bot resource Messaging endpoint:
<paste TrueServe messaging endpoint>

Configure the agent in TrueServe

  1. Open the agent and select Settings.
  2. In Microsoft Teams, turn on Enable Teams agent. The Teams setup fields stay hidden until this switch is on.
  3. Enter the Microsoft tenant ID, bot app/client ID, and client secret.
  4. Set the app short name, full name, description, and package version.
  5. Upload PNG icons if you want custom icons. If you do not upload icons, TrueServe uses generated defaults.
  6. Copy the Messaging endpoint into the Microsoft bot registration.

Changes save automatically as you edit (a brief "Saving…" indicator appears).

The package status changes to Package ready when the required fields, stored secret, and HTTPS messaging endpoint are present.

Microsoft values

Field Where it comes from
Microsoft tenant ID Microsoft Entra tenant ID for the organization where the Teams app will be installed. In Azure Portal or Microsoft Entra admin center, open Microsoft Entra ID and copy the Tenant ID from Overview or Properties.
Bot app / client ID The Application (client) ID for the app registration used by the Azure Bot or Teams bot registration. In an Azure Bot resource, open Configuration and select Manage to reach the app registration.
Client secret The secret value created on the app registration under Certificates & secrets. Copy the value immediately after creation; Microsoft will not show it again.
Application ID URI Optional for V1 text chat. Use the app registration's Expose an API value only when you are preparing Teams SSO metadata.
Messaging endpoint Generated by TrueServe from the public Teams gateway URL and this agent's Teams config ID. Toggle Enable Teams agent on and wait for the autosave if the endpoint has not appeared yet.

The messaging endpoint must be public HTTPS before Microsoft Teams can call it. For local testing, use an HTTPS tunnel and set the Teams gateway public URL before downloading the app package.

Download and install

Do this only after the Microsoft bot registration exists and the TrueServe messaging endpoint has been copied back into that bot registration.

  1. Select Download Teams app package.
  2. Upload the zip to Teams as a custom app, or publish it through your Teams admin process.
  3. Install it in personal scope.
  4. Start a 1:1 chat with the agent.

The Teams chat resumes the same TrueServe conversation after gateway restarts because TrueServe stores the Teams conversation link.

Troubleshooting

Symptom Check
Package is not ready The Microsoft tenant ID, bot app/client ID, client secret, app display fields, and HTTPS endpoint must all be present
Teams upload fails Confirm custom app upload is allowed and the package contains valid manifest.json, color.png, and outline.png
Bot does not answer Confirm the Azure Bot messaging endpoint exactly matches the TrueServe endpoint and is publicly reachable over HTTPS
Wrong tenant rejected The incoming Teams activity tenant must match the Microsoft tenant ID saved in TrueServe

See also