- Notifications
You must be signed in to change notification settings - Fork1
Ruby gem for integration with Microsoft Teams Incoming Webhook
License
pedrofurtado/microsoft_teams_incoming_webhook_ruby
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Ruby gem for integration with Microsoft Teams Incoming Webhook.
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
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.
Once you have configured Incoming Webhook inside your Teams channels, you can send a very simpleHello World message:
require'microsoft_teams_incoming_webhook_ruby'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url='YOUR INCOMING WEBHOOK URL HERE'm.text='Hello World!'endmessage.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 sendat least the 2 keys.
TheMicrosoftTeamsIncomingWebhookRuby::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.
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 areurl andtext. 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::Messageobject - After object initialization, but before
sendmethod call
🚨 You can add/replace/remove any fields arbitrarily, but keeping at least the minimum required fields (url andtext). Otherwise, an error will be generated when invokesend method.
Below there are some examples of this manipulation:
- Initialization of attributes in
MicrosoftTeamsIncomingWebhookRuby::Messageobject
require'microsoft_teams_incoming_webhook_ruby'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |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'}endmessage.send
- Addition of attribute after object initialization, but before
sendmethod call
require'microsoft_teams_incoming_webhook_ruby'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url='YOUR INCOMING WEBHOOK URL HERE'm.text='Hello World!'endmessage.builder.my_arbitrary_field='My value'message.builder.my_another_arbitrary_field={my:'value'}message.send
- Remotion of attributes after object initialization, but before
sendmethod call
require'microsoft_teams_incoming_webhook_ruby'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url='YOUR INCOMING WEBHOOK URL HERE'm.text='Hello World!'m.my_custom_field='My custom value'endmessage.builder.delete_field:my_custom_fieldmessage.send
- Redefinition of attributes after object initialization, but before
sendmethod call
require'microsoft_teams_incoming_webhook_ruby'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url='YOUR INCOMING WEBHOOK URL HERE'm.text='Hello World!'m.my_custom_field='My custom value'endmessage.builder.my_custom_field='Updated value'message.send
In case of keys that starts with@, it is necessary to use brackets notation:
require'microsoft_teams_incoming_webhook_ruby'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url='YOUR INCOMING WEBHOOK URL HERE'm.text='Hello World!'m['@my_field']='Lorem ipsum'endmessage.builder['@my_another_new_field']='Ipsum valorium'message.send
If the builder object turn itself invalid before invocation ofsend method, the gem will raise aMicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessage exception:
require'microsoft_teams_incoming_webhook_ruby'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url='YOUR INCOMING WEBHOOK URL HERE'm.text='Hello World!'endmessage.builder.delete_field:urlbeginmessage.sendrescueMicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessageputs'Your message structure is invalid!'end
require'microsoft_teams_incoming_webhook_ruby'beginmessage=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.my_only_one_field='Lorem ipsum'endrescueMicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessageputs'Your message structure is invalid'end
If a non-successful response code be returned by API (1xx, 4xx or 5xx), the gem will raise aMicrosoftTeamsIncomingWebhookRuby::Message::Error::FailedRequest exception:
require'microsoft_teams_incoming_webhook_ruby'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url='YOUR INCOMING WEBHOOK URL HERE'm.text='My message'endbeginmessage.sendrescueMicrosoftTeamsIncomingWebhookRuby::Message::Error::FailedRequestputs'Microsoft API is down, broken, or your network failed!'end
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.
require'microsoft_teams_incoming_webhook_ruby'webhook_url='YOUR INCOMING WEBHOOK URL HERE'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url=webhook_urlm.text='Minimal message!'endmessage.send
require'microsoft_teams_incoming_webhook_ruby'webhook_url='YOUR INCOMING WEBHOOK URL HERE'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url=webhook_urlm.text='Message with theme color!'m.themeColor='FF0000'endmessage.send
require'microsoft_teams_incoming_webhook_ruby'webhook_url='YOUR INCOMING WEBHOOK URL HERE'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url=webhook_urlm.text='Message with title!'m.title='My title'endmessage.send
require'microsoft_teams_incoming_webhook_ruby'webhook_url='YOUR INCOMING WEBHOOK URL HERE'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url=webhook_urlm.text='Message with summary!'m.summary='My summary'endmessage.send
require'microsoft_teams_incoming_webhook_ruby'webhook_url='YOUR INCOMING WEBHOOK URL HERE'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url=webhook_urlm.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'}]}]endmessage.send
require'microsoft_teams_incoming_webhook_ruby'webhook_url='YOUR INCOMING WEBHOOK URL HERE'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url=webhook_urlm.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'}]}]endmessage.send
require'microsoft_teams_incoming_webhook_ruby'webhook_url='YOUR INCOMING WEBHOOK URL HERE'message=MicrosoftTeamsIncomingWebhookRuby::Message.newdo |m|m.url=webhook_urlm.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'}]}]endmessage.send
To execute gem tests locally, use Docker with the commands below:
git clone https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_rubycd microsoft_teams_incoming_webhook_rubydocker 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
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
Bug reports and pull requests are welcome on GitHub athttps://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 thecode of conduct.
The gem is available as open source under the terms of theMIT License.
Everyone interacting in the microsoft_teams_incoming_webhook_ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow thecode of conduct.
About
Ruby gem for integration with Microsoft Teams Incoming Webhook
Topics
Resources
License
Code of conduct
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Uh oh!
There was an error while loading.Please reload this page.