OpenAI example

The fastest way to understand the bridge is to run its example project - a minimal, working embedding you can copy straight into your own repo. Budget about 10 minutes once the Teams setup is done.

examples/basic-bridge

loadConfig() + startServer() in a few lines, with a custom vision hook (your own model answers the agent’s look tool) and a custom lookup_order function tool the bridge executes. Env-file config and graceful shutdown are built in.

What you need first

Node.js >= 20.
An OpenAI API key with Realtime access (platform.openai.com). No agent to create - the bridge configures each gpt-realtime session itself.
A StandIn identity with its shared secret (from pairing or the dashboard). The sandbox works too if you have no Teams bot yet.

1. Clone and install

git clone https://github.com/komaa-com/openai-msteams-bridge

cd openai-msteams-bridge/examples/basic-bridge

npm install

2. Configure the environment

The example reads the same env file as the CLI - copy the fully commented template from the repo root:

cp ../../.env.example .env

Open .env and fill in the two required values:

Variable	What to put there
`OPENAI_API_KEY`	Your OpenAI API key (server-side only; never sent to the Teams side).
`WORKER_SHARED_SECRET`	The shared secret from StandIn pairing - both sides must match exactly.

Worth setting while you are there: OPENAI_VOICE (e.g. marin), OPENAI_INSTRUCTIONS (the agent’s personality), and OPENAI_FIRST_MESSAGE (a deterministic greeting / AI disclosure). The example still boots with dummy values, so you can check the wiring before the credentials are real. Everything else (PORT, MAX_CALL_MINUTES, goodbye behavior, VAD mode) has sensible defaults - see the configuration reference.

3. Start it

npm start

The bridge prints the WebSocket URL to give StandIn:

Point your StandIn identity's agent WebSocket URL at ws://<this-host>:9442/voice/msteams/stream

4. Expose port 9442

StandIn connects from the internet, so the port needs a public wss:// URL. Any tunnel works:

Tailscale Funnel
cloudflared
ngrok

tailscale funnel --bg --set-path=/voice/msteams/stream http://127.0.0.1:9442/voice/msteams/stream

Your URL: wss://<machine>.<tailnet>.ts.net/voice/msteams/stream

cloudflared tunnel --url http://localhost:9442

Use the printed hostname: wss://<hostname>/voice/msteams/stream

ngrok http 9442

Use the printed hostname: wss://<hostname>/voice/msteams/stream

5. Connect it to StandIn and call

In your StandIn dashboard, set the identity’s Agent calling URL to the wss:// URL from step 4.
Make sure the identity’s shared secret equals WORKER_SHARED_SECRET.
Place a Teams call to your bot (or join the sandbox meeting). StandIn joins, connects to the bridge, and your gpt-realtime agent answers.

The vision hook

The example ships a custom VisionDescriber in index.mjs. When your agent calls its built-in look tool, the bridge hands your function the current camera or screen-share frame and returns your text description to the agent - the raw frame never leaves your process. The example answers with gpt-4o-mini; swap in any vision-capable model. If you prefer configuration over code, the VISION_API_URL / VISION_API_KEY / VISION_MODEL variables do the same against any OpenAI-compatible endpoint - see Vision.

The custom tool

The example also registers a lookup_order function tool:

const tools = [{
  name: "lookup_order",
  description: "Look up the status of a customer order by its order number.",
  parameters: {
    type: "object",
    properties: { orderNumber: { type: "string", description: "The order number, e.g. KO-1234." } },
    required: ["orderNumber"],
  },
  async handler({ orderNumber }, ctx) {
    // call your own backend here; the returned string goes to the agent
    return `Order ${orderNumber} shipped yesterday and arrives tomorrow.`;
  },
}];

startServer(cfg, undefined, describeFrame, { handleSignals: true, tools });

Ask the agent on a call “where is order KO-12?” and it calls your handler, then speaks the answer. This is the pattern for wiring the agent to your own systems (CRM lookups, transfers, bookings); remote MCP servers are the config-only alternative - see Extending the agent’s tools.

From example to your own project

Depend on the published package instead of the local checkout:

npm install @komaa/openai-msteams-bridge

Then copy the example’s index.mjs as your starting point. The library API documents the programmatic surface (config, server options, tools, hooks).

If something does not work

WebSocket rejected with 401 - WORKER_SHARED_SECRET does not match the secret in StandIn.
Bot joins the call but stays silent - the Agent calling URL is unreachable from the internet or points at the wrong port; re-check the tunnel.
Call connects, then ends with agent-unavailable - the OpenAI key is invalid, lacks Realtime access, or OPENAI_REALTIME_MODEL names a model your account cannot use; the log line carries the underlying error.
More: Troubleshooting.

Getting Started

Teams setup

Concepts

OpenClaw plugin

Hermes plugin

ElevenLabs bridge

LiveKit bridge

examples/basic-bridge

What you need first

1. Clone and install

2. Configure the environment

3. Start it

4. Expose port 9442

5. Connect it to StandIn and call

The vision hook

The custom tool

From example to your own project

If something does not work

Links

Example README

Configuration

Library API

examples/basic-bridge

​What you need first

​1. Clone and install

​2. Configure the environment

​3. Start it

​4. Expose port 9442

​5. Connect it to StandIn and call

​The vision hook

​The custom tool

​From example to your own project

​If something does not work

​Links

Example README

Configuration

Library API

What you need first

1. Clone and install

2. Configure the environment

3. Start it

4. Expose port 9442

5. Connect it to StandIn and call

The vision hook

The custom tool

From example to your own project

If something does not work

Links