How to Integrate AdWords with HipChat

Here I'll show an easy way (if you're a developer) to get daily AdWords reports into a HipChat room. We'll use Google App Engine as the integration glue. An alternate approach I'm not using here is to define your own Zapier integration. Before we start, here's an overview of the architecture:

To summarize, the integration will:

1. In AdWords: generate a daily report and email it.
2. In HipChat: a dedicated room will receive and display message.
3. In App Engine: receive email and send HipChat message to HipChat room.

1. AdWords Integration

We will write a small script in AdWords to generate a report and email it to us. In your AdWords account, click the Campaigns tab, then go to Bulk operations / Scripts, and create the following script:

// Make a small report and email it.
function main() {
  // Get enabled campaigns.
  var campaignIterator = AdWordsApp.campaigns()
      .withCondition("Status = ENABLED")
      .withLimit(10)
      .get();

  Logger.log('Active campaigns');
  while (campaignIterator.hasNext()) {
    var campaign = campaignIterator.next();
    var stats = campaign.getStatsFor('ALL_TIME');
    Logger.log(campaign.getName() + ':\n' +
        stats.getClicks() + ' clicks\n' +
        stats.getImpressions() + ' impressions\n' +
        100*stats.getCtr() + ' click thru rate\n' +
        stats.getAverageCpc() + ' avg cpc\n' +
        stats.getCost() + ' cost\n'        
    );
    var percent = stats.getImpressions() ?
        Utilities.formatString('%1.3f', 100*(stats.getClicks() / stats.getImpressions()))
        : 'UNKNOWN';
    var text = campaign.getName() + ':\n  ' +
      stats.getClicks() + ' / ' + stats.getImpressions() + ' clicks (' + percent + '%)\n  $' +
        stats.getAverageCpc() + ' avg cpc, total: $' + stats.getCost()
      ;
    Logger.log(text);

    // Send email.
    MailApp.sendEmail('bot@appid.appspotmail.com', 'Auto Adwords Report', text);
  }
}

Above, in the last line which calls MailApp.sendEmail, replace appid with your App Engine id. The above script creates a line that looks like this to summarize your ad's results:

Your Campaign Title:
   10 / 100 clicks (10.000%)
   $0.25 avg cpc, total: $25.00

The script then emails this text to bot@appid.appspotmail.com .

2. HipChat Integration

In summary, we will create a HipChat room and an integration inside it. In Detail:

Login to the web interface as an Admin and go to hipchat.com . Create a new room, which will hold the daily AdWords reports.

Go to Integrations of the new room, and click "Find New". Click the Create button under the "Build Your Own!", and name the integration whatever you like. To get the url to post to this room, click Configure on the integration, and note the field "Send messages to this room by posting to this URL". We will need it below. The url will look like: https://api.hipchat.com/v2/room/(room-id)/notification?auth_token=(token) .

3. App Engine Integration

Now we will make our App Engine app receive the email and send a HipChat text message. I'll assume you have already created an App Engine app. First, update your app.yaml config file to receive email:

- url: /_ah/mail/.+
  script: handle_incoming_email.app
  login: admin

Second, create a small Python script to handle the email, called handle_incoming_email.py:

import json
import logging
import webapp2
from google.appengine.api import urlfetch
from google.appengine.ext.webapp.mail_handlers import InboundMailHandler

class MailHandler(InboundMailHandler):
    def receive(self, message):
        logging.info('Received message: %s, %s' % (message.sender, message))
        lst = []
        for content_type, body in message.bodies('text/plain'):
            lst.append(body.decode())
        text = '\n'.join(lst)

        data = dict(message='%s' % text, message_format='text', notify=True)
        jsondata = json.dumps(data)
        result = urlfetch.fetch(url='https://api.hipchat.com/v2/room/...',
            payload=jsondata,
            method=urlfetch.POST,
            headers={'Content-Type': 'application/json'})
        logging.info('Done sending message')

app = webapp2.WSGIApplication([MailHandler.mapping()], debug=True)

Above, replace the url 'https://api.hipchat.com/v2/room/...' with the HipChart integration url you noted in step 2.

Testing

To test, go to your AdWords script, and click Run. If all went well, your HipChat room should receive the message. If not, check the logs - first in AdWords (to make sure the email was sent), and second in App Engine (to make sure the email was received and then the HipChat message was sent).

Running

Once the script is working, in AdWords you can set how frequently you want your script to run. I like having it run in the morning. Enjoy!