Hide
Google+ Platform

Google+ Hangout button

The Hangout button lets you launch a Google+ Hangout directly from your site. When you use the button, you can set up the Hangout in a variety of configurations. For example, you can specify Hangout apps that launch along with the Hangout and setup the Hangout as a regular Hangout or a Hangout On Air.

You can customize the Hangout button to meet the needs of your website by modifying the button size, loading the button when the page loads, or selectively showing the button using JavaScript.

Use of the Hangout button is subject to the Buttons Policy.

Hangout button code

In general, to render the Hangout button, you include the necessary JavaScript resources for rendering the button and then specify where you want the button in your site's HTML.

There are various ways to render the button demonstrated in this section:

  • Tag markup
  • HTML5 markup
  • JavaScript

Lets start with the simplest case, rendering the button using tag markup.

Render button using tag markup

To render using tag markup, include the platform.js script and place the <g:hangout> tag where you want the Hangout button to render.The following example shows a simple example for rendering a button using tag markup.

<script src="https://apis.google.com/js/platform.js" async defer></script>
<g:hangout render="createhangout"></g:hangout>

The script must be sourced as https and can be included at any point on the page.

Render button using HTML5 markup

As an alternative to tag markup, you can specify the Hangout button using standard HTML5 markup. To use HTML5 markup, include platform.js and set the class used in your HTML element to g-hangout.

The following example shows a simple case for rendering the Hangout button using HTML5 markup.

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div class="g-hangout" data-render="createhangout"></div>

Render button using JavaScript

By rendering the Hangout button using JavaScript, you can target any element in your page as a container and programmatically render the Hangout button in that container.

To render the Hangout button with JavaScript, first include the JavaScript file:

<script src="https://apis.google.com/js/platform.js" async defer></script>

Then you need to specify an HTML container to render as the Hangout button, for example:

<div id="placeholder-div"></div>

Finally, render the button in the container by using gapi.hangout.render():

<script>
gapi.hangout.render('placeholder-div', { 'render': 'createhangout' });
</script>

The first parameter passed to the gapi.hangout.render method accepts the target HTML container used to host the Hangout button. The second parameter is an object that contains the parameters that indicate the app to start, the mode, and other information. For more information, see the Hangout button attributes.

Deferred execution with onLoad and script tag parameters

Use the onload callback to execute widget code after all dependencies have loaded.

To specify script tag parameters, use the following syntax:

<script >
  window.___gcfg = {
    lang: 'zh-CN',
    parsetags: 'onload'
  };
</script>
<script src="https://apis.google.com/js/platform.js" async defer></script>

Inviting people to the Hangout

You can specify a list of people to invite to the Hangout when it starts. The list is only a suggestion to the user that starts the Hangout. Before the Hangout begins, that user will be able to skip the invite or change the list of people.

You can specify an invite (object representing who to invite) via three different identifiers:

  • Google+ profile ID: This ID is tied to a specific Google+ user. You can obtain this ID in several ways:
    • From the Google+ signin flow. After the user has signed in, you can use the People get API with the special value me to get the authorized user's Google ID.
    • From various other People APIs.
    • From the user's public profile URL. These are usually of the form https://plus.google.com/<ID>.
    • From a Hangout app. Several APIs return a Participant object and the person.id field is the Google ID.
  • Google+ circle ID: An identifier of a circle. Note this this is strongly tied to the user that starts the Hangout; only IDs of circles that user owns will work. Obtaining a circle ID is only available via the Circles API for Google Apps.
  • E-mail address: A standard e-mail address.

Alternatively, you can invite a phone number to the Hangout. You can invite only a single phone number, and you cannot combine a phone number with inviting other people as documented above.

Adding a Hangout app to the button

If you are launching a Hangout app along with a Hangout, you must set the Hangout button's app_id parameter to the project number of your Hangout app or extension. To get the project number, go to the Google Developers Console, select the Hangouts project you want the button to start, then on the Overview page, copy the number from the Project Number field. It will be at least 12 digits long, such as 123456789012.

The following code uses HTML5 markup to create a Hangout button that will launch a Hangout app. Configure the button to launch your app by specifying the application in the JavaScript array of apps data-initial_apps.

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div class="g-hangout" data-render="createhangout"
    data-initial_apps="[{ app_id : '123456789012', start_data : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }]">
</div>

The Button examples section has more use cases showing you how to load Hangout apps when the user clicks the button.

Hangout button attributes

The Hangout button contains attributes for configuring the button, the apps associated with the button, and contains attributes that are returned from a callback triggered when the user clicks the button.

Script tag parameters

These parameters are defined within the <script /> element. The parameters control the language and button loading mechanism that are used across the entire web page.

Key Value Default Description
lang language code en-US Sets the language to use for all of the Google+ plugins on the page. For available language code values, see the list of supported language codes and a lang example.
parsetags explicit, onload onload Sets the loading mechanism to use.
onload
All Hangout button on the page are automatically rendered after the page loads. See the deferred execution onLoad example.
explicit
Hangout button are rendered only with explicit calls to gapi.hangout.go or gapi.hangout.render.

When you use the explicit load in conjunction with go and render calls that point to specific containers in your page, you prevent the script from traversing the entire DOM, which can improve button rendering time. See the gapi.hangout.go and gapi.hangout.render examples.

Hangout button parameters

The following parameters are used to initialize the Hangout button. These parameters determine the type of Hangout to create and the apps to launch when the Hangout starts.

Parameter Type Description
render String Specifies how to render the Hangout button. Currently this parameter must have the value ‘createhangout’.
topic String Pre-populates the topic field for Hangouts on Air. Note that users can change the topic of the Hangout after they have joined.
invites Array This array of JavaScript objects specifies the list of people to invite when the user clicks the Hangout button. Invalid objects and parameters are ignored. See the section above on Inviting people for a full explanation, and the section below on Invite parameters for a list of parameters to the members of this array.
initial_apps Array This array of JavaScript objects specifies the Google+ Hangout apps to launch when a user clicks the Hangout button. Invalid objects and parameters are ignored. The section below on Initial App Parameters, describes the parameters for the members of this array.
hangout_type HangoutType Specifies what type of Hangout should be started. The following values are supported:
normal
(Default) Launch the Hangout app without broadcasting to YouTube or starting a Hangout party.
onair
Launch the Hangout to be broadcast on YouTube as a Hangout On Air.
party
Launch the Hangout app as a Hangout party.
moderated
Launch the Hangout app with Control Room enabled.
widget_size Number Specifies the width of the button. The default value is 136.

Invite parameters

These parameters specify the people invited to the Google+ Hangout when the user clicks the button. The invites are specified in an array of JavaScript objects, each with the following parameters set.

Parameter Type Description
id String The identifier to use
invite_type String Specifies the type of invite. The following values are supported:
PROFILE
A Google+ profile ID.
CIRCLE
A Google+ circle ID.
EMAIL
A standard e-mail address.
PHONE
A phone number. Note that phone numbers and the fields above are exclusive: you may list any number of profile, circle, or e-mail invites OR a single phone number, but not both.

Initial app parameters

These parameters specify the applications that are started along with the Google+ Hangout when a user clicks the button. Each application passed in the array of Hangout apps must have these parameters set.

Parameter Type Description
app_id String The project number retrieved from the Google Developers Console that corresponds to the application that this button launches.
start_data String This optional parameter specifies data to be passed to the initial instantiation of the app. Only the first participant to join the application has this value present in the response from gapi.hangout.getStartData. If you want this data to be referenced later, store the data in the shared Hangout state using the gapi.hangout.data methods.
app_type Enum This optional parameter specifies the type of Hangout app created when the user clicks the button. Setting this parameter changes the way that Hangout applications are loaded for the Hangout and its participants. The following values are supported:
LOCAL_APP
Launches the app for only the user who clicks the widget.
ROOM_APP
Launches the app for every participant who joins the Google+ Hangout. The button defaults to this value.

Button sizes

The button can be rendered at various sizes and renders differently when you specify the button is to be rendered as a Hangout On Air. The following table lists example sizes.

Example Type Width Code
A wide Hangout button.
A wide Hangout button.
Hangout 175

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div id="placeholder-rr"></div>
<script>
  gapi.hangout.render('placeholder-rr', {
    'render': 'createhangout',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
    'widget_size': 175
  });
</script>

The default Hangout button.
The default Hangout button.
Hangout 136 (Default)

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div id="placeholder-div1"></div>
<script>
  gapi.hangout.render('placeholder-div1', {
    'render': 'createhangout',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }]
  });
</script>

A narrow Hangout button.
A narrow Hangout button.
Hangout 72

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div id="placeholder-div2"></div>
<script>
  gapi.hangout.render('placeholder-div2', {
    'render': 'createhangout',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
    'widget_size': 72
  });
</script>

A wide Hangout button with Hangouts on Air enabled.
A wide Hangout button with Hangouts on Air enabled.
Hangout on Air 175

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div id="placeholder-div3"></div>
<script>
  gapi.hangout.render('placeholder-div3', {
    'render': 'createhangout',
    'hangout_type': 'onair',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
    'widget_size': 175
  });
</script>

The default Hangout button with Hangouts on Air enabled.
The default Hangout button with Hangouts On Air enabled.
Hangout on Air 136 (Default)

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div id="placeholder-div4"></div>
<script>
  gapi.hangout.render('placeholder-div4', {
    'topic': 'hats',
    'render': 'createhangout',
    'hangout_type': 'onair',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
  });
</script>

A narrow Hangout button with Hangouts on Air enabled.
A narrow Hangout button with Hangouts on Air enabled.
Hangout on Air 72

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div id="placeholder-div5"></div>
<script>
  gapi.hangout.render('placeholder-div5', {
    'topic': 'cats',
    'render': 'createhangout',
    'hangout_type': 'onair',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
    'widget_size': 72
  });
</script>

Supported languages

If you need to change the language used on the button, provide script tag parameters to configure the button. The following JavaScript code will set the language used on the Hangout Button.

<script>
    window.___gcfg = {
      lang: 'en-US'
    };
</script>

The following table lists values and languages the button supports.

Language Value
Afrikaans af
Amharic am
Arabic ar
Basque eu
Bengali bn
Bulgarian bg
Catalan ca
Chinese (Hong Kong) zh-HK
Chinese (Simplified) zh-CN
Chinese (Traditional) zh-TW
Croatian hr
Czech cs
Danish da
Dutch nl
English (UK) en-GB
English (US) en-US
Estonian et
Filipino fil
Finnish fi
French fr
French (Canadian) fr-CA
Language Value
Galician gl
German de
Greek el
Gujarati gu
Hebrew iw
Hindi hi
Hungarian hu
Icelandic is
Indonesian id
Italian it
Japanese ja
Kannada kn
Korean ko
Latvian lv
Lithuanian lt
Malay ms
Malayalam ml
Marathi mr
Norwegian no
Persian fa
Polish pl
Language Value
Portuguese (Brazil) pt-BR
Portuguese (Portugal) pt-PT
Romanian ro
Russian ru
Serbian sr
Slovak sk
Slovenian sl
Spanish es
Spanish (Latin America) es-419
Swahili sw
Swedish sv
Tamil ta
Telugu te
Thai th
Turkish tr
Ukrainian uk
Urdu ur
Vietnamese vi
Zulu zu

Button examples

The following examples show how to create buttons using various approaches and configurations.

Basic page

<html>
  <head>
    <title>Hangout button demo: Async load</title>
    <link rel="canonical" href="http://www.example.com" />
    <script src="https://apis.google.com/js/platform.js" async defer>
    </script>
  </head>
  <body>
    <g:hangout render="createhangout"></g:hangout>
  </body>
</html>

Basic page with the language set

<html>
<head>
  <script>
      window.___gcfg = {
        lang: 'hi'
        parsetags: 'onload'
      };
  </script>
  <script src="https://apis.google.com/js/platform.js" async defer></script>
  <title>Hangout button demo: Setting the Hangout button language</title>
  <link rel="canonical" href="http://www.example.com" />
</head>
<body>
    <g:hangout render="createhangout"></g:hangout>
</body>
</html>

Basic page with profile and e-mail invites

<html>
<head>
<script>
    <title>Hangout button demo: Inviting people</title>
    <link rel="canonical" href="http://www.example.com" />
</script>
</head>
<body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <g:hangout render="createhangout"
        invites="[{ id : '1234', invite_type : 'PROFILE' },
                  { id : 'foo@example.com', invite_type : 'EMAIL' }]">
    </g:hangout>
</body>
</html>

Basic page with a phone number invite

<html>
<head>
<script>
    <title>Hangout button demo: Inviting a phone number</title>
    <link rel="canonical" href="http://www.example.com" />
</script>
</head>
<body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <g:hangout render="createhangout"
        invites="[{ id : '2025551212', invite_type : 'PHONE' }]">
    </g:hangout>
</body>
</html>

Basic page with a Hangout app

<html>
<head>
<script>
    <title>Hangout button demo: Specifying Hangout apps</title>
    <link rel="canonical" href="http://www.example.com" />
</script>
</head>
<body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <g:hangout render="createhangout"
        initial_apps="[{ app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type': 'ROOM_APP' }]">
    </g:hangout>
</body>
</html>

Basic page using HTML5 markup

<html>
  <head>
    <title>Hangout button demo: Async load</title>
    <link rel="canonical" href="http://www.example.com" />
    <script src="https://apis.google.com/js/platform.js" async defer>
    </script>
  </head>
  <body>
    <div class="g-hangout" data-render="createhangout"></div>
  </body>
</html>

Deferred execution and JavaScript render with a language code

<html>
<head>
    <title>Hangout button demo: Deferred execution with language code</title>
    <link rel="canonical" href="http://www.example.com" />
</head>
<body>
  <div id="placeholder-div"></div>
  <script>
    window.___gcfg = {
      lang: 'zh-CN',
      parsetags: 'onload'
    };

    function renderButtons(){
      gapi.hangout.render('placeholder-div', {
          'render': 'createhangout',
        });
    }
  </script>
  <script src="https://apis.google.com/js/platform.js" async defer></script>
</body>
</html>

Deferred execution with language code and a Hangout app

<html>
<body>
  <div id="placeholder-div"></div>
</body>
<script>
    window.___gcfg = {
      lang: 'zh-CN',
      parsetags: 'onload'
    };

    function renderButton(){
      gapi.hangout.render('placeholder-div', {
          'render': 'createhangout',
          'initial_apps': [
            { app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }
          ]
        });
    }
</script>
<script src="https://apis.google.com/js/platform.js" async defer></script>
</html>

Troubleshooting

This section includes resolutions to issues encountered when using the Hangout button.

Button does not render

Open the JavaScript console and check if you see the error:
Failed to load resource: the server responded with a status of 500 (Internal Server Error)

If you see this error, ensure that you are specifying how to render the button. For example, the following code will cause this error, because the button has no render attribute:

<script src="https://apis.google.com/js/platform.js" async defer></script>
<g:hangout></g:hangout>

The following example shows how to update this code to correctly render the Hangout button:

<script src="https://apis.google.com/js/platform.js" async defer></script>
<g:hangout render="createhangout"></g:hangout>

Button renders in the wrong language

You must specify the lang script tag parameter before loading platform.js. The following example will not work because the language is set after loading platform.js:

<html>
<head>
<script src="https://apis.google.com/js/platform.js" async defer></script>
<script>
    window.___gcfg = {
      lang: 'fr'
    };
</script>
</head>
<body>
    <g:hangout render="createhangout"></g:hangout>
</body>
</html>

The following example will correctly set the language. Use the onload callback to execute your code after all dependencies have loaded:

<html>
<head>
<script>
    window.___gcfg = {
      lang: 'fr'
      parsetags: 'onload'
    };
</script>
<script src="https://apis.google.com/js/platform.js" async defer></script>
</head>
<body>
    <g:hangout render="createhangout"></g:hangout>
</body>
</html>

Google+ Hangout app is not loading

First, make sure that you are specifying a valid app ID, which you can find as described in the Initial app parameters section.

Next, you need to make sure that the JavaScript array of apps is valid, and is in fact an array as opposed to just a JavaScript object. In the following example where there is an issue, a JavaScript object is passed instead of an array which will prevent the app from including the Google+ Hangout app:

<html>
  <head>
  <script>
      <title>Hangout button demo: Setting the Hangout button language</title>
      <link rel="canonical" href="http://www.example.com" />
  </script>
  </head>
  <body>
      <script src="https://apis.google.com/js/platform.js" async defer></script>
      <g:hangout render="createhangout"
          initial_apps="{ app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type' : 'LOCAL_APP' }">
      </g:hangout>
  </body>
</html>

The following example correctly specifies the array of Hangout apps:

<html>
  <head>
  <script>
      <title>Hangout button demo: Setting the Hangout button language</title>
      <link rel="canonical" href="http://www.example.com" />
  </script>
  </head>
  <body>
      <script src="https://apis.google.com/js/platform.js" async defer></script>
      <g:hangout render="createhangout"
          initial_apps="[{ app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }]">
      </g:hangout>
  </body>
</html>