Giphy Integration Service for Mattermost

This integrations service is used to enable an external search engine (Giphy) to be queried based on commands issued in a Mattermost channel using Mattermost outgoing webhooks.

Once installed, users can type gif: keyword to send a query to the Giphy search engine and return with a post containing one non-deterministic search result from the Giphy database of animated GIF files matching keyword. The animation will appear below in the posted message.

Project Goal

The goal of this project is to provide a fully-functional template on which the Mattermost community can create their own integration services. Community members are invited to fork this repo to add improvements and to create new integrations.

To have your work included on the Mattermost integrations page, please mail info@mattermost.com or tweet to @MattermostHQ.

Requirements

To run this integration you need:

A web server supporting Python 2.7 or compatible versions.
A Mattermost account where outgoing webhooks are enabled

Many web server options will work, below we provide instructions for Heroku and a general Linux/Ubuntu server.

Heroku-based Install

To install this project using Heroku, you will need:

A Heroku account, available for free from Heroku.com
A GitHub account, available for free from GitHub.com

Here's how to start:

Create a copy of this project to manipulate
Log in to your GitHub account. Go to the Github repository of this project click Fork in the top-right corner to create a copy of this project that you can control and manipulate
Deploy your project copy to Heroku
Go to your Heroku Dashboard and click + in the top-right corner then Create New App
Give your app a unqiue name (like mattermost-giphy-[YOUR_GITHUB_USERNAME]), select your region and click Create App
Heroku directs you to the Deploy tab of the dashboard for your new app, select GitHub as your connection option, then click Connect to GitHub at the bottom of the screen to authorize Herkou to access your GitHub account
In the pop up window, click Authorize Application to allow Heroku to access your accounts repositories. This step does not apply if you've already connected your GitHub account to Heroku.
On your Heroku dashboard, select your GitHub account in the first drop-down, type mattermost-integration-giphy in the repo-name field, then click Search and then the Connect button once Heroku finds your repository
Scroll to the bottom of the new page. Under the Manual Deploy section, make sure the master branch is selected then click Deploy Branch. After a few seconds you'll see a confirmation that the app has been deployed
At the top of your app dashboard, click on the Settings tab and scroll down to the Domains section. Copy the URL below Heroku Domain (we'll refer to this as http://<your-heroku-domain>/ and we'll need it in the next step)
Leave your Heroku interface open as we'll come back to it to finish the setup
Connect your project to your Mattermost account for outgoing webhooks
Log in to your Mattermost account. Click the three dot menu at the top of the left-hand side and go to Account Settings > Integrations > Outgoing Webhooks
Under Add a new outgoing webhook, leave the Channel unselected and enter gif: into Trigger Words. You may select a channel if you only want this integration to be available in a specified channel
Paste your Heroku domain into Callback URLs, making sure to add http:// to the beginning and /new_post to the end so it looks similar to http://myapp.heroku.com/new_post and click Add
Copy the Token from your newly created webhook that appears under the Existing outgoing webhooks section
Go back to your Heroku app dashboard under the Settings tab. Under the Config Variables section, click Reveal Config Vars
Type MATTERMOST_TOKEN as the KEY and paste in the token you copied as the VALUE, and click Add
Connect your project to your Mattermost account for slash commands
Log in to your Mattermost account. Click the three dot menu at the top of the left-hand side and go to Account Settings > Integrations > Slash Commands
Under Add a new command, enter /gif into Command Trigger Word
Paste your Heroku domain into Callback URLs, making sure to add http:// to the beginning
Select POST method
(optional) Choose a username and icon url
(optional) Check the autocomplete checkbox, add [KEYWORD] as the hint, Returns a GIF from Giphy based on the keyword as the description and Get a GIF from Giphy as the descriptive label
Copy the Token from your newly created slash command that appears under the Existing commands section
Go back to your Heroku app dashboard under the Settings tab. Under the Config Variables section, click Reveal Config Vars
Type MATTERMOST_TOKEN as the KEY and paste in the token you copied as the VALUE, and click Add

That's it! Waiting a few minutes for the Heroku process to restart you should be able to type gif: hello or /gif hello into any channel and see a GIF from Giphy's translate service.

Linux/Ubuntu 14.04 Web Server Install

The following procedure shows how to install this project on a Linux web server running Ubuntu 14.04. The following instructions work behind a firewall so long as the web server has access to your GitLab and Mattermost instances.

To install this project using a Linux-based web server, you will need a Linux/Ubuntu 14.04 web server supporting Python 2.7 or a compatible version. Other compatible operating systems and Python versions should also work.

Here's how to start:

Set up this project to run on your web server
Set up a Linux Ubuntu 14.04 server either on your own machine or on a hosted service, like AWS.
SSH into the machine, or just open your terminal if you're installing locally
Confirm Python 2.7 or a compatible version is installed by running:
- python --version If it's not installed you can find it here
Install pip and other essentials
- sudo apt-get install python-pip python-dev build-essential
Clone this GitHub repo with
- git clone https://github.com/numberly/mattermost-integration-giphy.git
- cd mattermost-integration-giphy
Install integration requirements
- sudo python setup.py install
Set up your Mattermost outgoing webhooks
Log in to your Mattermost account. Click the three dot menu at the top of the left-hand side and go to Account Settings > Integrations > Outgoing Webhooks
Under Add a new outgoing webhook, leave the Channel unselected and enter gif: into Trigger Words. You may select a channel if you only want this integration to be available in a specified channel
Paste your Web Server domain into Callback URLs, making sure to add http:// to the beginning and /new_post to the end so it looks similar to http://<your-web-server-domain>/new_post and click Add
Copy the Token from your newly created webhook that appears under the Existing outgoing webhooks section
Set up your Mattermost slash command
Log in to your Mattermost account. Click the three dot menu at the top of the left-hand side and go to Account Settings > Integrations > Slash Commands
Under Add a new command, enter /gif into Command Trigger Word
Paste your Web Server domain into Callback URLs, making sure to add http:// to the beginning
Select POST method
(optional) Choose a username and icon url
(optional) Check the autocomplete checkbox, add [KEYWORD] as the hint, Returns a GIF from Giphy based on the keyword as the description and Get a GIF from Giphy as the descriptive label
Copy the Token from your newly created slash command that appears under the Existing commands section
Run the server with the correct configuration
Back on SSH or your terminal, add the following lines to your ~/.bash_profile
- export MATTERMOST_GIPHY_TOKEN=<your-token-here> This is the token you copied in the last section
- export MATTERMOST_GIPHY_HOST=<your-host> or export HOST=<your-host> The host you want the integration (defaults to 0.0.0.0)
- export MATTERMOST_GIPHY_PORT=<your-port-number> or export PORT=<you-port-number> The port number you want the integration to listen on (defaults to 5000)
Source your bash profile
- source ~/.bash_profile
Run the server
- python run.py

That's it! You should be able to type gif: hello or /gif hello into any channel and see a GIF from Giphy's translate service.

Production Setups

If you'd like to use this integration in a production envrionment, it is strongly recommended that you get a production Giphy API key from here. Once you have that you can configure the integration to use it:

On Heroku

Go to your Heroku Dashboard and click on your app
Click the Settings tab. Under the Config Variables section, click Reveal Config Vars
For KEY type in GIPHY_API_KEY and for VALUE paste in your Giphy API key, then click Add
Wait a minute for the Heroku process to restart

On Linux/Ubuntu 14.04 Web Server

Stop the process currently running the integration
Add the following lines to your ~/.bash_profile or ~/.bashrc
- export GIPHY_API_KEY=<your-api-key-here> With your Giphy API key
Source your bash profile
- source ~/.bash_profile or source ~/.bashrc
Run the server again
- python run.py

victorbello/mattermost-integration-giphy