About the JavaScript API

The Javascript API can only be used in pages loaded in Dialog and Sidebar.

1
2
<!--Required -->
<script src="https://www.hipchat.com/atlassian-connect/all.js"></script>

Working with Dialogs

Open a Dialog

Details can be found here: Dialog

1
2
HipChat.dialog.open({
    key: "myaddon-dialog",         // Use the dialog key declared in the descriptor
    options: dialogOptions,        // Customize the dialog
    parameters: customParameters   // Anything you want
});

Update a Dialog

Details can be found here: Dialog

1
2
HipChat.dialog.update(dialogOptions);

Close a Dialog

1
2
HipChat.dialog.close();

Working with Sidebar Views

Open a Sidebar View

1
2
HipChat.sidebar.openView({
    // references the key of the webPanel in the descriptor
    key: 'myaddon-sidebar-key',        
    parameters: {
        // parameters to be passed to the sidebar view
        greetings: 'from somewhere else'
    }
  });

The parameters argument can be received by the sidebar iframe by declaring an event handler:

1
2
function receiveParameters(parameters) {
  // do something with the parameters
}

HipChat.register({
  "receive-parameters": receiveParameters
});

Close a Sidebar View

1
2
HipChat.sidebar.closeView();

Working with Actions

Register a listener for a HipChat Action

See Actions.

This works if the View the Javascript is run on is the target of the Action.

1
2
HipChat.register({
    // Use the key from the HipChat Action descriptor entry
    "myaddon-action-opendialog": function (message) {
        // In case of a Message Action, The HipChat message is passed as a parameter
        handle(message);
    }
});

The following parameters are available on events triggered by message actions:

A Message sent by a user

Example

1
2
{
  "body": "Hello",
  "sender": {
    "id": 356,
    "name": "Patrick Streule",
    "mention": "PatrickStreule"
  },
  "mid": "7d8d27bb-4292-48eb-ba74-15efffe25050",
  "metadata": {}
}

A Notification or Card sent by an add-on

Example

1
2
{
  "body": "<b>Fallback message</b>",
  "sender": {
    "name": "HCTester"
  },
  "mid": "d45b077e-4d0d-4918-9a2c-55c96952898c",
  "metadata": {
    "foo": "bar"
  }
}

Interacting with the HipChat App

Create a HipChat room

This opens a "create room" dialog in the HipChat client, populated with the information you pass in.

1
2
HipChat.room.create("The Room Name", "The Room Topic", "public/private");

Insert text in the chat input

1
2
HipChat.chat.appendMessage('Hello!!');

Focus the chat input

1
2
HipChat.chat.focus();

Insert binary data in the chat input for upload

The image data is passed as a base64 data URI

1
2
HipChat.chat.addFileForUploadWithBase64(base64DataUri, name);

Open a HipChat room

Open a HipChat room (specifying a Sidebar to be opened is not possible yet)

1
2
HipChat.room.open({
    roomId: 123456
});
// or
HipChat.room.open({
    roomName: "my room name"
});

Open a HipChat 1-1 chat

1
2
HipChat.room.open({
    userId: 123456
});
// or
HipChat.room.open({
    userMentionName: "@admin"
});
// or
HipChat.user.open({
    userId: 123456
});
// or
HipChat.user.open({
    userMentionName: "@admin"
});

Open a chat with a message

Either of the above APIs can also be called with a message to prepopulate the chat box with.

1
2
HipChat.room.open({
    roomId: 123456,
    message: "Hello!"
});
//or
HipChat.user.open({
    userId: 123123,
    message: "Hello!"
});

Invite Users to a room

Works with user IDs and mention names

1
2
HipChat.room.invite([342, 653, 782]);
// or
HipChat.room.invite(["@peter", "@paul", "@mary"]);

Open a file in the File Viewer

You can open a single file or a list of files.

1
2
var file1 = {
  id: "id1",
  name: "File 1",
  url: "https://example.com/img/id1.png"
}
var file2 = {
  id: "id2",
  name: "File 2",
  url: "https://example.com/img/id2.png"
}

// Allow to navigate through file1 and file2 and show file1
HipChat.file.openInFileViewer(file1, [file1, file2]);

// Show file1
HipChat.file.openInFileViewer(file1);

Interacting with the add-on backend

Your views may need to retrieve information from your backend via AJAX calls. In order to authenticate these calls, HipChat provides a convenience method returning a JWT which can be used to authenticate the AJAX call. You can verify these tokens like any another JWT you receive from HipChat.

1
2
HipChat.auth.withToken(function(err, token) {
  if (err) {
    // error
  } else {
    $.ajax({
      type: 'GET',
      url: '/data',
      headers: { 'Authorization': 'JWT ' + token },
      ...
    });
  }
});

Getting contextual information from the HipChat Client

The following javascript APIs will allow you to request information from the HipChat client rather than making a REST call to the server. Access to these methods is restricted to add-ons with the correct scopes:

Get Room Participants

Returns the list of participants in the current room grouped into guests and members.

1
2
HipChat.room.getParticipants(function(err, success) {
    if (err) {
      // error
    } else {
      // success
    }
});

Get Room Details

Returns information for the currently opened room.

1
2
HipChat.room.getRoomDetails(function(err, success) {
    if (err) {
      // error
    } else {
      // success
    }
});

Get Current User

Returns information about the current user.

1
2
HipChat.user.getCurrentUser(function(err, success) {
    if (err) {
      // error
    } else {
      // success
    }
});

Responding to Updates

There are several strategies you can use to keep your view in sync with the rest of your integration.

Registering to events

The HipChat javascript API lets you register listeners for specific events in web panels. For example, your web panel can be notified when your glance is updated, or a message was received from your add-on in the room where the add-on web panel is open (so you can refresh or change the content of the web panel)

1
2
HipChat.register({
    "glance-update": function(data) {
        // Event is triggered on glance updates
    },
    "message-received": function(data) {
        // Event is triggered when messages are received from your addon
    }
});

Event: Glance update

• Event name: glance-update
• **Description: ** fired when any glance in your addon is updated. 
• Properties: 
  • **addon_key: **the key for your addon
  • module_key: the module key for the glance which was updated
  • metadata: the metadata that was included in your glance push

Event: Message received

• Event name: message-received 
• Description: fired when any message or Card is received from your addon.
• Properties:
  • body - the notification body
  • sender
    • name - The from name for the notification
  • mid - the id of the message
  • metadata - the metadata that was included in your card
  • card - only present if the notification contained a card
    • title - The title of the card
    • description - The description of the card

Web Sockets / Long Polling / Polling

HipChat Connect does not provide any other mechanisms for updating your sidebar. If you need more frequent / real time updates you may need to make use of web sockets or polling your backend servers.