teams_rb — Teams SDK for Ruby

A Ruby-native port of the Microsoft Teams SDKs for building Teams bots and apps with Rack or Rails. It includes message routing, proactive messaging, the Bot Framework API client, typed Adaptive Cards, dialogs, message extensions, streaming, meetings, OAuth, Microsoft Graph, tabs, and remote functions.

teams_rb preserves the concepts and wire behavior of the official TypeScript, Python, and C# SDKs while providing an idiomatic Ruby API. Inbound JWT validation and outbound bot token management are built in.

Unofficial. teams_rb is an independent, community-maintained project. It is not affiliated with, endorsed by, or sponsored by Microsoft. The official Teams SDKs are developed by Microsoft at github.com/microsoft/teams-sdk.

• Ruby 4.0 or newer
• A Microsoft 365 tenant with custom app upload enabled
• A public HTTPS tunnel for local development, such as Dev Tunnels

Add the SDK and a Rack server for this standalone example to your Gemfile:

gem "teams_rb"
gem "puma"

Then install it:

bundle install

Create a config.ru:

require "teams"

teams = Teams::App.new

teams.on_message do |ctx|
  ctx.typing
  ctx.reply "echo: #{ctx.activity.text}"
end

run teams.to_rack

The easiest registration path is the optional Teams CLI, which requires Node.js 20 or newer. Install it, sign in, and check that your tenant allows sideloading:

npm install -g @microsoft/teams.cli
teams login
teams status

Start your HTTPS tunnel, then let the CLI create the app, bot registration, and install link:

teams app create \
  --name my-teams-ruby-bot \
  --endpoint https://<your-tunnel>/api/messages

The command prints CLIENT_ID, CLIENT_SECRET, TENANT_ID, and an Install in Teams link. You can also create the app manually in the Teams Developer Portal.

This standalone example uses Puma; teams_rb itself does not require a server gem. Start the bot with the credentials printed by the CLI:

CLIENT_ID=... CLIENT_SECRET=... TENANT_ID=... bundle exec puma -p 3978

Open the install link and send the bot a message. It receives Teams activities at POST /api/messages, validates each request, and replies to incoming messages.

See Running in Teams for the complete registration, tunnel, and installation walkthrough.

Handlers can match message text and respond with typed Adaptive Cards:

teams.on_message(/^status$/i) do |ctx|
  ctx.typing

  card = Teams::Cards::AdaptiveCard.new(
    Teams::Cards::TextBlock.new("Service status", size: "Large", weight: "Bolder"),
    Teams::Cards::TextBlock.new("All systems operational.", wrap: true)
  )

  ctx.post card
end

The official SDKs call plain message sending send. Ruby already defines Object#send, so teams_rb intentionally uses post. This is the one deliberate public API naming difference.

For Rails, define one Teams::App instance during boot and route POST /api/messages to app.to_rack. See App basics for the Rack and Rails forms.

This table tracks supported Teams SDK capabilities. Deprecated upstream AI and devtools packages are intentionally excluded.

• Getting started — quickstart, code basics, and running in Teams
• Essentials — app setup, activities, sending, proactive messaging, API clients, authentication, and Graph
• In-depth guides — cards, dialogs, extensions, streaming, user authentication, tabs, and events
• Examples — runnable Rack apps for common SDK features
• Changelog — release history

Install dependencies and run the Minitest suite:

bundle install
bundle exec rake test

The gem is self-contained. Regenerating the typed Adaptive Card classes requires a sibling checkout of Microsoft's Python SDK; see the Adaptive Cards guide.

Use GitHub Issues for bug reports and feature requests.

teams_rb is available under the MIT License.