Error handling in the Google+ Hangouts Telephone API

Recently, the Google+ Hangouts Telephone API was released to the stable channel (yay!) which means that you now can create production apps that add calls to Hangout apps. Uberconference, for example, released an update that lets you connect Hangout apps to their voice bridge. One key aspect of creating great Hangout apps is handling errors gracefully. In this post, I’ll get you started on detecting errors.

Handling errors for the Hangouts Telephone API

If you read this post on the Telephone API, you have seen the Telephone API work and probably have an amazing Hangout app that places calls programatically on behalf of the user… However, you’re probably wondering, “How do I handle user errors and additional errors that can occur as they happen.” Well, there’s an API for that! onCallStateChanged.

By adding this event handler to a call, you can then identify and respond to errors within your app. Let’s take a look at the basics, checking to see when a user dismisses the dialog to add a call to the hangout. Consider the following code.

  gapi.hangout.telephone.onCallInitiated.add(callInitiatedEventHandler);          
  gCall = gapi.hangout.telephone.beginCall(phoneNumber.number);    

  gCall.onCallStateChanged.add(callStateChangedEventHandler);
  function callStateChangedEventHandler(callState){                                 

    console.log("call state changed to:");
    console.log(callState.newState);
    if (callState.newState == gapi.hangout.telephone.CallState.USER_REJECTED_CALL){
    // The user clicked cancel.
    }
  }

When the user clicks cancel your callback will be triggered because the call state has changed. You can learn about all of the call states from the full index of the Hangouts API. The short list is:

  • CallState.BUSY
  • CallState.CANNOT_CALL_YOURSELF
  • CallState.CONNECTED
  • CallState.DISCONNECTED
  • CallState.ERROR
  • CallState.HANGOUT_FULL
  • CallState.INITIALIZING
  • CallState.INSUFFICIENT_FUNDS
  • CallState.RINGING
  • CallState.USER_ALREADY_IN_CALL
  • CallState.USER_REJECTED_CALL
  • CallState.USER_REJECTED_TOS

When do you use it?

Now that you have detected something is wrong, what do you do?  The answer depends on what is the right thing for the user. In some cases, the user may have accidentally closed the add call to hangout dialog. If you have reason to believe this happened, it’s a great time to let the user know either how they can resolve the issue themselves (e.g. reconnect the call button) or notify the user they probably meant to add the call and show them a way to add it right then.

That’s it for now, have fun making your telephone-capable apps even more awesome!