Microsoft Teams Incoming Webhook Ruby
Ruby gem for integration with Microsoft Teams Incoming Webhook.
Installation
Add this line to your application's Gemfile:
gem 'microsoft_teams_incoming_webhook_ruby'
And then execute:
bundle install
Or install it yourself as:
gem install microsoft_teams_incoming_webhook_ruby
Usage
Configuration of Incoming Webhook connector on your Teams channels
The first step before using this gem is to configure the connector inside your Teams channels.
For this purpose, please check the official documentation from Microsoft. It's listed below some useful links:
- https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook
- https://techcommunity.microsoft.com/t5/microsoft-365-pnp-blog/how-to-configure-and-use-incoming-webhooks-in-microsoft-teams/ba-p/2051118
- https://www.youtube.com/watch?v=amvh4rzTCS0
After the configuration, keep your generated Incoming Webhook URL in a secret and secure way.
You will use it (the URL) in next sections of README.
Hello World message sending
Once you have configured Incoming Webhook inside your Teams channels, you can send a very simple Hello World
message:
require 'microsoft_teams_incoming_webhook_ruby'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
end
.send
Note that there are 2 keys that is the minimum required to define a valid message for Teams:
url
: The URL of Incoming Webhook connector, generated via Microsoft Teamstext
: The text of your message
There are many other possible keys to be sent to Microsoft Incoming Webhook API. But pay attention to always send at least the 2 keys.
Gem public interface
The MicrosoftTeamsIncomingWebhookRuby::Message
class has 3 main methods:
new
: Initialization of object. You need to pass a block as parameter, containing the message structure. This structure will be converted automatically to JSON and be sent to Microsoft Incoming Webhook API.builder
: Message builder object, that allows add/redefine/remove fields arbitrarily.send
: Invocation of Incoming Webhook API, using HTTPS.
Message structure
The Microsoft Incoming Webhook API allows us to send a variety of fields, that will result in diferents cards displayed in Teams channels.
Because of this, the gem will not enforce any schema in message structure. The only required parameters are url
and text
. Any other options will be accepted, considering that Microsoft Incoming Webhook API accepts it.
The message structure and its fields can be defined in two moments:
- Initialization of
MicrosoftTeamsIncomingWebhookRuby::Message
object - After object initialization, but before
send
method call
🚨 You can add/replace/remove any fields arbitrarily, but keeping at least the minimum required fields (url
and text
). Otherwise, an error will be generated when invoke send
method.
Below there are some examples of this manipulation:
- Initialization of attributes in
MicrosoftTeamsIncomingWebhookRuby::Message
object
require 'microsoft_teams_incoming_webhook_ruby'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
m.my_arbitrary_field = 'My value'
m.my_another_arbitrary_field = { my: 'value' }
end
.send
- Addition of attribute after object initialization, but before
send
method call
require 'microsoft_teams_incoming_webhook_ruby'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
end
.builder.my_arbitrary_field = 'My value'
.builder.my_another_arbitrary_field = { my: 'value' }
.send
- Remotion of attributes after object initialization, but before
send
method call
require 'microsoft_teams_incoming_webhook_ruby'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
m.my_custom_field = 'My custom value'
end
.builder.delete_field :my_custom_field
.send
- Redefinition of attributes after object initialization, but before
send
method call
require 'microsoft_teams_incoming_webhook_ruby'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
m.my_custom_field = 'My custom value'
end
.builder.my_custom_field = 'Updated value'
.send
In case of keys that starts with @, it is necessary to use brackets notation:
require 'microsoft_teams_incoming_webhook_ruby'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
m['@my_field'] = 'Lorem ipsum'
end
.builder['@my_another_new_field'] = 'Ipsum valorium'
.send
Error handling
If the builder object turn itself invalid before invocation of send
method, the gem will raise a MicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessage
exception:
require 'microsoft_teams_incoming_webhook_ruby'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
end
.builder.delete_field :url
begin
.send
rescue MicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessage
puts 'Your message structure is invalid!'
end
require 'microsoft_teams_incoming_webhook_ruby'
begin
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.my_only_one_field = 'Lorem ipsum'
end
rescue MicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessage
puts 'Your message structure is invalid'
end
If a non-successful response code be returned by API (1xx, 4xx or 5xx), the gem will raise a MicrosoftTeamsIncomingWebhookRuby::Message::Error::FailedRequest
exception:
require 'microsoft_teams_incoming_webhook_ruby'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'My message'
end
begin
.send
rescue MicrosoftTeamsIncomingWebhookRuby::Message::Error::FailedRequest
puts 'Microsoft API is down, broken, or your network failed!'
end
Examples
You can build and send messages with any supported card fields provided by Microsoft:
- https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using
- https://adaptivecards.io/samples
- https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference
- https://amdesigner.azurewebsites.net
- https://messagecardplayground.azurewebsites.net
- https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card
- https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/what-are-webhooks-and-connectors
We will provide below some ready-to-go examples to be used, based on API described in links above.
Minimal
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Minimal message!'
end
.send
Theme color
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Message with theme color!'
m.themeColor = 'FF0000'
end
.send
Title
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Message with title!'
m.title = 'My title'
end
.send
Summary
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Message with summary!'
m.summary = 'My summary'
end
.send
Potential action
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Message with potential action!'
m.potentialAction = [
{
'@type': 'ActionCard',
'name': 'Answer',
'inputs': [
{
'@type': 'TextInput',
'id': 'title',
'isMultiline': true,
'title': 'Your text here'
}
],
'actions': [
{
'@type': 'HttpPOST',
'name': 'Send my answer',
'isPrimary': true,
'target': 'https://example.com/example'
}
]
},
{
'@type': 'HttpPOST',
'name': 'Make another action',
'target': 'https://example.com/example2'
},
{
'@type': 'OpenUri',
'name': 'Open a URL',
'targets': [
{
'os': 'default',
'uri': 'https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby'
}
]
}
]
end
.send
Sections
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Message with sections!'
m.sections = [
{
'text': 'Lorem ipsum vastium',
'activityTitle': 'John Smith',
'activitySubtitle': '01/01/1990, 11:45AM',
'activityImage': 'https://connectorsdemo.azurewebsites.net/images/MSC12_Oscar_002.jpg',
'facts': [
{ 'name': 'Repository:', 'value': 'my-repo' },
{ 'name': 'Issue #:', 'value': '123456789' }
]
}
]
end
.send
Advanced
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
= MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Advanced message'
m['@type'] = 'MessageCard'
m['@context'] = 'http://schema.org/extensions'
m.themeColor = '0076D7'
m.summary = 'Larry Bryant created a new task'
m.sections = [
{
'activityTitle': 'Larry Bryant created a new task',
'activitySubtitle': 'On Project Tango',
'activityImage': 'https://teamsnodesample.azurewebsites.net/static/img/image5.png',
'markdown': true,
'facts': [
{ 'name': 'Assigned to', 'value': 'Unassigned' },
{ 'name': 'Due date', 'value': 'Mon May 01 2017 17:07:18 GMT-0700 (Pacific Daylight Time)' },
{ 'name': 'Status', 'value': 'Not started' }
]
}
]
m.potentialAction = [
{
'@type': 'ActionCard',
'name': 'Add a comment',
'inputs': [
{
'@type': 'TextInput',
'id': 'comment',
'isMultiline': false,
'title': 'Add a comment here for this task'
}
],
'actions': [
{
'@type': 'HttpPOST',
'name': 'Add comment',
'target': 'https://docs.microsoft.com/outlook/actionable-messages'
}
]
},
{
'@type': 'ActionCard',
'name': 'Set due date',
'inputs': [
{
'@type': 'DateInput',
'id': 'dueDate',
'title': 'Enter a due date for this task'
}
],
'actions': [
{
'@type': 'HttpPOST',
'name': 'Save',
'target': 'https://docs.microsoft.com/outlook/actionable-messages'
}
]
},
{
'@type': 'OpenUri',
'name': 'Learn More',
'targets': [
{
'os': 'default',
'uri': 'https://docs.microsoft.com/outlook/actionable-messages'
}
]
},
{
'@type': 'ActionCard',
'name': 'Change status',
'inputs': [
{
'@type': 'MultichoiceInput',
'id': 'list',
'title': 'Select a status',
'isMultiSelect': 'false',
'choices': [
{ 'display': 'In Progress', 'value': '1' },
{ 'display': 'Active', 'value': '2' },
{ 'display': 'Closed', 'value': '3' }
]
}
],
'actions': [
{
'@type': 'HttpPOST',
'name': 'Save',
'target': 'https://docs.microsoft.com/outlook/actionable-messages'
}
]
}
]
end
.send
Execute tests/specs
To execute gem tests locally, use Docker with the commands below:
git clone https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby
cd microsoft_teams_incoming_webhook_ruby
docker build -t microsoft_teams_incoming_webhook_ruby_specs .
# Then, run this command how many times you want,
# after editing local files, and so on, to get
# feedback from test suite of gem.
docker run -v $(pwd):/app/ -it microsoft_teams_incoming_webhook_ruby_specs
Similar gems for reference
There are similar and great open source libraries that shares the same purpose of this gem, such as:
- https://github.com/toririn/teams_incoming_clients
- https://github.com/shirts/microsoft-teams-ruby
- https://github.com/oooooooo/msteams-ruby-client
- https://github.com/eduardolagares/msteams_webhook
- https://github.com/adventistmedia/msteams_notifier
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the microsoft_teams_incoming_webhook_ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.