Purpose

Currently, content previews (for services like YouTube, Imgur, Twitter) in Hipchat Server are disabled. This page outline the steps to:

• generate the API keys for the services
• the configuration to enable the previews
• known limitation
• troubleshooting bad key error from the logs.

Solution

Retrieving the API keys

Twitter

1. Create an application from https://apps.twitter.com/app/new (use the URL of your server)
2. Record the consumer key and consumer secret
3. Retrieve a bearer token from Twitter, using the instructions listed here (refer to this script for an example)

YouTube

1. Navigate to https://console.developers.google.com/apis, and either create a new project, or select an existing one
2. Enable the youtube v3 API for your project by going to https://console.developers.google.com/apis/api/youtube/overview and clicking on the 'Enable' button at the top
3. Go to https://console.developers.google.com/apis/credentials and create an API Key credential
4. Leave the IP restriction open, and save the key

Imgur

1. Create an Imgur application via https://api.imgur.com/oauth2/addclient with these specifications:
   1. Give it a meaningful name
   2. Choose authorization type: OAuth 2 authorization type without a callback URL
   3. Leave the authorization callback URL empty
   4. Enter your email
   5. Click submit
2. Save the client_id and secret key somewhere safe, as they can't be retrieved later. 

Github

1. Create a personal token from https://github.com/settings/tokens
2. Check the repo:status and public_repo scopes
3. Click Generate Token
4. Save the generated token somewhere save, as it can't be retrieved later

Bitly

1. Login and view your api key via https://app.bitly.com/default/bitlinks/?actions=accountMain&actions=settings&actions=advancedSettings&actions=apiSupport

Once you have a key(s), do the following:

For Hipchat Server v2.2.3 and newer (including HCDC):

1. SSH to your Hipchat Server deployment as the admin user

2. Run the following command to get a list of the specific service commands:

   hipchat labs apikeys --help

3. Find the service you want to apply a token/key to and apply using this command:

   hipchat labs apikeys --[SERVICE] KEY/TOKEN

For Hipchat Server v2.2.2 and older:

1. SSH to your Hipchat Server deployment as the admin user

2. Escalate to root privilege by running the command:

   sudo dont-blame-hipchat
   

3. Update the parameters by filling in the blanks of the services you're using with the keys generated.

   1. If you are running on Hipchat Server 2.1.3 or earlier, please use the hipchat-scm/chef-repo/data_bags/configs-btf/api_keys.json file

      {
          "id": "api_keys",
          "bitly": {
              "login": "hipchat",
              "api_key": "R_00000000000000000111111111111111"
          },
          "github": "0000000000000000000001111111111111111111",
          "imgur": {
              "client_id": "111111111111111",
              "secret": "0000000000000000000001111111111111111111"
          },
          "twitter": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
          "youtube": "000000000000000000000011111111111111111",
          "chef_type": "data_bag_item",
          "data_bag": "configs-btf"
      }

   2. If you are running on Hipchat Server 2.2.0, please use the /hipchat-scm/chef-repo/cookbooks/hipchat/attributes/hipchat.rb instead

      # storage configuration
      default['hipchat']['remote_storage'] = false
      
      default['hipchat']['api_keys']['bitly']['login'] = ''
      default['hipchat']['api_keys']['bitly']['api_key'] = ''
      default['hipchat']['api_keys']['github'] = ''
      default['hipchat']['api_keys']['imgur']['client_id'] = ''
      default['hipchat']['api_keys']['imgur']['secret'] = ''
      default['hipchat']['api_keys']['youtube'] = ''
      default['hipchat']['api_keys']['twitter'] = ''

4. Exit root privilege escalation by running the command:

   exit

5. Apply the new configuration and restart services by running the command:

   hipchat upgrade --restart
   

   Note this command will not initiate a version upgrade.

Known Limitation

• For version 2.2.2 and older, keys will be reset to empty on a Hipchat Server upgrade
• For version 2.2.3 and newer, the keys will remain after an upgrade.

Troubleshooting

You will see the following error in /var/log/hipchat/tetra.log if a wrong/bad key is specified:

2015-11-13T00:52:25.732609+00:00 ip-10-0-1-89 tetra-app-1: [] Error unknown calling external URL 'https://www.googleapis.com/youtube/v3/videos?part=snippet%2Cstatistics&maxResults=1&key=AIzaSyCWSINcFJDYITCH3wDb5is_1VETIdU5EL4&id=c38rO_PzIlE' in 54ms. Cause: [Failure instance: Traceback (failure with no frames): <class 'twisted.web.error.Error'>: 403 Forbidden\n]

2015-11-13T00:52:25.733382+00:00 ip-10-0-1-89 tetra-app-1: [] WARN: Error hitting API: "403 Forbidden", url=https://www.youtube.com/watch?v=c38rO_PzIlE, message=u'https://www.youtube.com/watch?v=c38rO_PzIlE'