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.

Powered by Giphy.

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:

1. A web server supporting Python 2.7 or compatible versions.
2. 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:

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

Here's how to start:

1. Create a copy of this project to manipulate

2. 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

3. Deploy your project copy to Heroku

4. Go to your Heroku Dashboard and click + in the top-right corner then Create New App

5. Give your app a unqiue name (like mattermost-giphy-[YOUR_GITHUB_USERNAME]), select your region and click Create App

6. 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

7. 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.

8. 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

9. 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

10. 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)

11. Leave your Heroku interface open as we'll come back to it to finish the setup

12. Connect your project to your Mattermost account for outgoing webhooks

13. 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

14. 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

15. 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

16. Copy the Token from your newly created webhook that appears under the Existing outgoing webhooks section

17. Go back to your Heroku app dashboard under the Settings tab. Under the Config Variables section, click Reveal Config Vars

18. Type MATTERMOST_TOKEN as the KEY and paste in the token you copied as the VALUE, and click Add

19. Connect your project to your Mattermost account for slash commands

20. 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

21. Under Add a new command, enter /gif into Command Trigger Word

22. Paste your Heroku domain into Callback URLs, making sure to add http:// to the beginning

23. Select POST method

24. (optional) Choose a username and icon url

25. (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

26. Copy the Token from your newly created slash command that appears under the Existing commands section

27. Go back to your Heroku app dashboard under the Settings tab. Under the Config Variables section, click Reveal Config Vars

28. 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:

1. Set up this project to run on your web server

2. Set up a Linux Ubuntu 14.04 server either on your own machine or on a hosted service, like AWS.

3. SSH into the machine, or just open your terminal if you're installing locally

4. Confirm Python 2.7 or a compatible version is installed by running:

   • python --version If it's not installed you can find it here

5. Install pip and other essentials

   • sudo apt-get install python-pip python-dev build-essential

6. Clone this GitHub repo with

   • git clone https://github.com/numberly/mattermost-integration-giphy.git
   • cd mattermost-integration-giphy

7. Install integration requirements

   • sudo python setup.py install

8. Set up your Mattermost outgoing webhooks

9. 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

10. 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

11. 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

12. Copy the Token from your newly created webhook that appears under the Existing outgoing webhooks section

13. Set up your Mattermost slash command

14. 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

15. Under Add a new command, enter /gif into Command Trigger Word

16. Paste your Web Server domain into Callback URLs, making sure to add http:// to the beginning

17. Select POST method

18. (optional) Choose a username and icon url

19. (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

20. Copy the Token from your newly created slash command that appears under the Existing commands section

21. Run the server with the correct configuration

22. 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)

23. Source your bash profile

    • source ~/.bash_profile

24. 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

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

On Linux/Ubuntu 14.04 Web Server

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