Programmatically Scheduling Hangouts

One pretty common request around Google+ hangouts is the ability to programmatically schedule them, and have a URL which everyone can join in the future. This is useful for being able to send out links beforehand, and make sure people are ready to go.

While there isn't a specific API for this at the moment, there is actually a workaround that makes use of the Hangout integration into Google Calendars.

In the Calendar you want to use to create hangout entries, go to the Settings page under the cog icon on the top right, and enable automatic hangout creation:

This means that any event created on that calendar will automatically have a hangout URL generated, and that can be retrieved via the API. So, to programmatically create a URL for a future hangout, create an event using the calendar insert API. This example is using the PHP client library.

$event = new Google_Event();
$event->setSummary('Future Hangout');
$event->setLocation('The Internet!');


First we set the summary and a location - the general fields we might want in the calendar entry. Of course, if we're not actually going to show this calendar entry to anyone it might not matter what these are set to!



$start = new Google_EventDateTime();
$start->setDateTime('2012-12-19T20:00:00.000-07:00');
$event->setStart($start);
$end = new Google_EventDateTime();
$end->setDateTime('2012-12-19T20:25:00.000-07:00');
$event->setEnd($end);



Next we set the start and end times of the event - you can use the hangout link right away so this isn't necessarily important, but it probably doesn't hurt to set it to the real times of the hangout. 


$attendee1 = new Google_EventAttendee();
$attendee1->setEmail('ianbarber@example.com');
$attendees = array($attendee1);
$event->attendees = $attendees;



Finally, if we want to invite attendees we can, so it will appear in their calendar. 


$createdEvent = $service->events->insert('primary', $event);

When we insert the event we choose which calendar to add it to - in this case we're using primary, but if you didn't want to clutter up your main calendar you could create a special 'hangouts' calendar or similar. Primary in this case is a special ID, so you'll need to get the ID of the calendar to use via the calendarList.list API call.

As long as we have checked the "automatically add Google+ hangouts" button in the settings, the response we get back will have an entry hangoutLink:

["hangoutLink"]=>  string(98) "https://plus.google.com/hangouts/_/calendar/aWFuLmJhcmJlckBnbWFpbC5jb20.k26371tdft6a7qq6bpt4m5hrso"

We can extract this and email it out to our attendees or embed it anywhere else, even if we never expose the calendar invite to them. The full sample listing is in a gist.