> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a Voiceflow agent to Teams

> Connect Microsoft Teams to a Voiceflow text agent. Configure the platform, host the relay, test replies and prepare release.

## Overview

Answer one-to-one Microsoft Teams messages with a Voiceflow agent. This walkthrough uses Microsoft’s Teams SDK for authenticated activity delivery, a single-tenant bot registration and a developer-hosted relay.

<a id="before-you-begin"></a>

## Before you begin

Collect the agent, account and host access.

| Requirement | Obtain before installation |
| --- | --- |
| Voiceflow owner | An existing agent with a known support answer, a private project API key, project ID and reviewed Environment alias. [Build the agent](/docs/documentation/build/overview) first, then [publish the intended release](/docs/documentation/deploy/environments/publishing). |
| Tenant administrator | A Microsoft 365 work or school tenant where you may register an app and upload/install a custom Teams app. |
| Azure resources | An Azure subscription, single-tenant Entra application, client secret and Azure Bot resource with the Teams channel enabled. |
| Runtime | Node.js 22.12 or later and the supplied package pinned to `@microsoft/teams.apps` 2.2.1; commercial cloud personal conversations only. |
| Relay operator | A Node.js host, public HTTPS hostname, private secrets and persistent disk; an operator who can investigate paused conversations. |

The example provides public-policy text support. Keep private Voiceflow and platform credentials on the host; a customer’s messaging identity does not authorize access to orders or account records. Have the agent return text only and provide a support route in its instructions. Buttons, audio and Handoff traces need additional adapters; see [Adapt agent replies](/docs/guides/channels/messaging/adapt-agent-replies).

<a id="create-platform-app"></a>

## Prepare the platform account

Create the exact app or account this relay will use.

### 1. Register the single-tenant bot

In Microsoft Entra, register an application for accounts in your organizational directory. Record its Application (client) ID and Directory (tenant) ID. Create a client secret and save its **Value**, rather than its Secret ID. In Azure, create an **Azure Bot** with that application ID, single-tenant app type and tenant. Enable **Microsoft Teams** under its channels. The registration must use the same identity as the relay.

### 2. Prepare the Teams app package

In the [Teams Developer Portal](https://dev.teams.microsoft.com/), create an app and fill in its required name, descriptions, publisher, icons, website, privacy and terms URLs. Under **App features → Bot**, enter the Azure bot’s Microsoft App ID and select **Personal** scope. This text-only bot needs no Graph permission grant or resource-specific channel-history access. Keep file support and group/channel scopes off unless you implement them.

Download the app package for upload. Ask the tenant administrator to allow custom app upload and approve installation according to organizational policy. App registration alone does not install the bot in a person’s Teams chat. See [Microsoft’s registration and deployment guidance](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/deploy-azure-bot-service-manually).

<a id="run-relay"></a>

## Run the relay

Configure and host the supplied executable example.

Use the [configuration file](/docs/examples/messaging/microsoft-teams.env.example) for this platform. Every name below is read by the supplied artifact; IDs identify the resources prepared above. `VF_ENVIRONMENT` is the Environment alias, not a version label pasted from another project.

```dotenv
VF_API_KEY=YOUR_PRIVATE_VOICEFLOW_PROJECT_KEY
VF_PROJECT_ID=YOUR_VOICEFLOW_PROJECT_ID
VF_ENVIRONMENT=YOUR_ENVIRONMENT_ALIAS
DATA_DIR=/var/lib/voiceflow-messaging
PORT=8080
PLATFORM=microsoft-teams
CLIENT_ID=YOUR_ENTRA_APPLICATION_ID
CLIENT_SECRET=YOUR_ENTRA_CLIENT_SECRET_VALUE
TENANT_ID=YOUR_ENTRA_TENANT_ID
```

### 1. Download and configure the relay

On a Linux host you administer, create `/opt/voiceflow-messaging` and extract the [relay archive](/docs/examples/messaging/messaging-relay.zip) there. Use Node.js 22.12 or later. Run `node --test fixtures.test.mjs` first: it generates signed synthetic events and mocks all remote calls, without credentials or live messages. Save the configuration above as `.env`, replacing every `YOUR_` value; restrict it to the service account with `chmod 600 .env`. Set `DATA_DIR` to a private persistent directory that this account can write.

The archive includes `core.mjs`, platform adapters, HTTP/Teams entry points, local fixture tests and a package manifest. Install the pinned Teams dependency with `npm ci --omit=dev`, then run `node --env-file=.env teams.mjs`.

### 2. Expose the HTTPS endpoint

Point your own DNS hostname to the host. Terminate HTTPS with a valid public certificate and proxy to `127.0.0.1:8080`. For example, with [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy) installed:

```sh
caddy reverse-proxy --from support.example.com --to 127.0.0.1:8080
```

Replace the example hostname, allow inbound 80/443 for certificate provisioning and keep the relay port private. Use a separate hostname and credentials for testing. Confirm the authenticated SDK route `https://support.example.com/api/messages` is reachable; an unsigned POST should be rejected.

### 3. Keep one process running

After the foreground check, stop it and create a service using the unit below. Keep one process and one writable data directory per installation. Do not run this file store on ephemeral serverless storage or start multiple replicas.

```ini
# /etc/systemd/system/voiceflow-messaging.service
[Unit]
Description=Voiceflow messaging relay
After=network-online.target

[Service]
User=relay
WorkingDirectory=/opt/voiceflow-messaging
ExecStart=/usr/bin/node --env-file=.env teams.mjs
Restart=on-failure
UMask=0077

[Install]
WantedBy=multi-user.target
```

Create the non-login `relay` service user, give it read access to the application and `.env`, and ownership of `/var/lib/voiceflow-messaging`. Confirm `/usr/bin/node --version` is 22.12 or later, or substitute your actual Node path. Then run `sudo systemctl daemon-reload` and `sudo systemctl enable --now voiceflow-messaging`. Expect the service to stay active; keep the HTTPS proxy running through its own service.

The file store is a small single-process starting point. Back it up privately and monitor disk space, queue age and failures. Higher traffic needs a transactional inbox/outbox and per-conversation workers before adding replicas. Session keys and customer text are stored in the data directory; apply your retention and access policy there as well as in Voiceflow.

<a id="register-events"></a>

## Register incoming events

Connect the platform to your hosted endpoint.

### 1. Save the Azure Bot endpoint

Set the Azure Bot’s **Messaging endpoint** to `https://YOUR_HOST/api/messages` and save it. This is the Teams SDK’s endpoint, rather than the generic relay’s `/webhook`. The SDK authenticates incoming service tokens and obtains bot credentials for replies; the handler additionally requires your tenant and personal scope. Keep `dangerouslyAllowUnauthenticatedRequests` false and do not set its environment override.

### 2. Install and check the personal app

In Teams, upload the app package through **Apps → Manage your apps → Upload an app → Upload a custom app**, or have the administrator distribute it through the organizational catalog. Add it for your test user and open its personal chat. Expect the bot’s app identity and personal conversation to be available. A local playground without service-token validation does not prove this registration.

Microsoft’s [Teams SDK quickstart](https://learn.microsoft.com/en-us/microsoftteams/platform/agents-in-teams/quickstart-create-agent-teams-sdk) also offers CLI provisioning; that is an alternative to the explicit Entra/Azure/Developer Portal setup taught here.

<a id="conversation-routing"></a>

## Route conversations and replies

Keep the customer, agent session and reply destination aligned.

| Stage | Mapping in the example |
| --- | --- |
| Customer identity | Tenant + bot app ID + personal conversation ID + sender ID; reject other tenants and non-personal conversation types. |
| Incoming text | An authenticated Teams `message` activity. Save its activity ID before returning from the SDK handler. |
| Visible reply | The Teams SDK `app.send(conversationId, {type: message, textFormat: plain, text})` posts to the original personal conversation. |
| Duplicate | Deduplicate conversation ID plus activity ID under the tenant/bot account. Installation and other activity types do not execute the agent. |

The relay hashes platform, destination account, customer/thread, project and Environment into a bounded Voiceflow `userID`. It creates a session with the private project key, stores the returned `sessionKey`, launches once, then sends `{ action: { type: "text", payload: text } }` to `/v4/interact`. Text traces become platform replies. Follow-ups reuse the key; starting a session every message would reset the conversation.

The SDK handles the Bot Service authentication contract; copying a bearer token into a generic webhook does not replace it. The pinned package’s current interface is inspected separately from older Bot Framework examples. This recipe does not use the retired Bot Framework SDK, Graph chat-posting permissions or Teams Phone.

The handler acknowledges persisted input, then executes the agent outside the inbound turn. Replies are sent through the bot’s authenticated service client. A removed app, expired client secret or `429` response pauses the conversation; check Bot Service diagnostics and the saved job. Sovereign clouds, channel threads, meeting bots, adaptive cards and files need separate configuration and are outside this example.

<a id="test-conversation"></a>

## Test a customer conversation

Verify the reply in the destination you installed.

### 1. Send a real platform message

Open the installed app’s personal chat in Teams and send the support question. Expect the bot’s text answer in that personal chat.

### 2. Check continuity and isolation

Ask a related follow-up, then test with a second authorized customer. Confirm the intended Voiceflow project and exchange in [Transcripts](/docs/documentation/measure/transcripts). Run `node --env-file=.env relay.mjs inspect` while the service is stopped to compare event IDs, conversation keys and completion states without printing session tokens.

### 3. Check this platform’s delivery behavior

Send a follow-up and repeat as another tenant member. A forged unauthenticated `https://support.example.com/api/messages` request must be rejected before it can create an event or Voiceflow session.

A saved callback, accepted API request or successful Voiceflow Run does not prove this platform conversation. Keep local signed-fixture tests separate from this authenticated customer test.

<a id="troubleshooting" />

### The callback saves but no reply arrives

Check platform access as well as endpoint connectivity.

Compare Entra client ID, secret Value, tenant, Azure Bot identity, Teams channel, messaging endpoint and manifest `botId`. A successful Azure resource deployment does not prove the Teams app is installed or allowed by policy.

### A conversation is paused or a reply is duplicated

Reconcile remote effects before resuming the saved job.

Inspect the event’s `phase`, `failedDuring`, saved traces and accepted chunks in the private data file. A runtime timeout can occur after a tool action; a send timeout can occur after the platform accepted the message. The sample pauses that conversation and does not retry either effect automatically. Follow [Recover failed messages](/docs/guides/channels/messaging/recover-failed-messages), then repeat the platform test.

<a id="go-live"></a>

## Release and maintain the connection

Promote the tested route and keep recovery available.

### 1. Approve the production destination

Deploy the reviewed relay and bot identity, rotate development credentials, and distribute the approved package through the tenant’s catalog. Repeat the personal-chat test as an ordinary member. Organization approval and public Teams Store review are separate distribution paths.

### 2. Release the reviewed agent

Have the Voiceflow owner publish the tested agent to the intended Environment. Deploy that alias and production credentials to the relay, restart its service and repeat the [customer test](#test-conversation) with a fresh customer/session. Existing session keys are not an automatic migration to a new release. Keep the previous deployment and state backup available for rollback.

### Rotate, update or disconnect

Maintain both the provider registration and the relay state.

Stop the service before changing `.env` or running maintenance commands. Rotate the platform credentials using its administrator controls, update the secret file and restart. If a webhook secret changes, update both sides and check a real event. For a release change, drain or reconcile pending jobs first; do not erase the state file to resolve a delivery problem.

To disconnect, disable/remove this callback or uninstall this app in the provider, stop the relay and revoke its unused credentials. Confirm no new events arrive and retain/delete customer state according to your policy. Keep the registration details needed to reconnect. See [Pause automated replies](/docs/guides/channels/messaging/pause-automated-replies) for a temporary conversation-specific pause.
