https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby
Ruby gem for integration with Microsoft Teams Incoming Webhook
https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby
gem incoming-webhooks microsoft-teams ruby-gem teams
Last synced: 5 months ago
JSON representation
Ruby gem for integration with Microsoft Teams Incoming Webhook
- Host: GitHub
- URL: https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby
- Owner: pedrofurtado
- License: mit
- Created: 2021-09-25T16:28:32.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-05-06T00:47:49.000Z (almost 3 years ago)
- Last Synced: 2024-11-18T03:02:06.636Z (6 months ago)
- Topics: gem, incoming-webhooks, microsoft-teams, ruby-gem, teams
- Language: Ruby
- Homepage: https://rubygems.org/gems/microsoft_teams_incoming_webhook_ruby
- Size: 87.9 KB
- Stars: 5
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Microsoft Teams Incoming Webhook Ruby
[](https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby/actions/workflows/ci.yml)
[](https://codecov.io/gh/pedrofurtado/microsoft_teams_incoming_webhook_ruby)
[](https://codeclimate.com/github/pedrofurtado/microsoft_teams_incoming_webhook_ruby/maintainability)
[](https://badge.fury.io/rb/microsoft_teams_incoming_webhook_ruby)
[]()
[]()
[](https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby)
[](https://github.com/rubocop/rubocop)
Ruby gem for integration with Microsoft Teams Incoming Webhook.
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'microsoft_teams_incoming_webhook_ruby'
```
And then execute:
```shell
bundle install
```
Or install it yourself as:
```shell
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:
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
end
message.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 Teams
- `text`: 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
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
message = 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
message.send
```
- Addition of attribute after object initialization, but before `send` method call
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
end
message.builder.my_arbitrary_field = 'My value'
message.builder.my_another_arbitrary_field = { my: 'value' }
message.send
```
- Remotion of attributes after object initialization, but before `send` method call
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
m.my_custom_field = 'My custom value'
end
message.builder.delete_field :my_custom_field
message.send
```
- Redefinition of attributes after object initialization, but before `send` method call
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
m.my_custom_field = 'My custom value'
end
message.builder.my_custom_field = 'Updated value'
message.send
```
In case of keys that starts with **@**, it is necessary to use brackets notation:
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
m['@my_field'] = 'Lorem ipsum'
end
message.builder['@my_another_new_field'] = 'Ipsum valorium'
message.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:
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'Hello World!'
end
message.builder.delete_field :url
begin
message.send
rescue MicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessage
puts 'Your message structure is invalid!'
end
```
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
begin
message = 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:
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = 'YOUR INCOMING WEBHOOK URL HERE'
m.text = 'My message'
end
begin
message.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
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Minimal message!'
end
message.send
```
### Theme color
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Message with theme color!'
m.themeColor = 'FF0000'
end
message.send
```
### Title
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Message with title!'
m.title = 'My title'
end
message.send
```
### Summary
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
m.url = webhook_url
m.text = 'Message with summary!'
m.summary = 'My summary'
end
message.send
```
### Potential action
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
message = 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
message.send
```
### Sections
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
message = 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
message.send
```
### Advanced
```ruby
require 'microsoft_teams_incoming_webhook_ruby'
webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
message = 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
message.send
```
## Execute tests/specs
To execute gem tests locally, use Docker with the commands below:
```bash
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](https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby/blob/master/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## 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](https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby/blob/master/CODE_OF_CONDUCT.md).