Actions

Your add-on can contribute specialized actions in multiple locations in HipChat. These actions can be used by users to act on messages or objects which are surfaced in Sidebar Views.

Input actions

Input actions are triggered from the input field using the "" icon.

This action should only be used to add content directly into chat.

Card and message actions

Actions are triggered from the "" icon.

Card actions

Cards can support multiple actions - click to expand or collapse.

Message actions

Action buttons are used to provide actions like discuss, open in browser or open in application in the main chat view.

View actions

Actions are triggered from the "" icon from within the full view.

Using actions

Declaring an action

Your add-on must declare the action in the add-on descriptor. Actions can open sidebar views, dialogs or external pages.

For example to add a message action which opens a custom Dialog View:

1
2
"capabilities": {
    ...,
    "action": [
        {
            "key": "message.reminder",
            "name": {
                "value": "Set Reminder"
            },
            "target": "dialog-key",               --> This can be the key of a web panel, dialog or external page
            "location": "hipchat.message.action"  --> or hipchat.input.action
        }
    ]
}

Action target

The target of an action can be:

• Opening a Dialog
• Opening a Sidebar
• Opening an External Page (open a new browser tab, load a URL, passing context parameters)

Processing an Action

If the target of an action is a Dialog or Sidebar you can register a listener for this action in the target view (dialog or sidebar) using the Javascript API. If the action is a message action, you can also retrieve the message content:

1
2
AP.register({
  "message.reminder": function (message) {  --> (the registration uses the key from the action descriptor entry)
    handle(message);
  }
});

Action conditions

Message actions can be context sensitive. For example, you can choose to show actions only if a message contains a link or a certain pattern:

1
2
"capabilities": {
    ...,
    "action": [
        {
            "key": "message.reminder",
            "name": {
                "value": "Set Reminder"
            },
            "target": "dialog-key",
            "location": "hipchat.message.action",
            "conditions": [
                {
                    "condition": "message_contains_link"
                }
            ]
        }
    ]
}

Action conditions for cards

A common use case is exposing actions on cards. These actions may vary with the card contents, and card metadata in combination with conditions can be used for this.

Example Card

1
2
{
  "style": "image",
  "id": "29c45d11-f0ea-45da-8500-1cd233f78da0",
  "url": "https://example.com",
  "title": "A title",
  "description": "A card",
  ...
  "metadata": {
    "status": "open"
  }
} 

1
2
{
  "condition": "card_matches",
  "params": {
    "style": "image"
   }
}

1
2
{
  'condition': 'card_matches',
  'params': {
    'metadata': [
      { 'attr': 'status',
      'eq': 'open'}
    ]
  }
}

1
2
"metadata": {
  "indicent": {
    "status": "open"
  }
}

1
2
'metadata': [
  { 'attr': 'indicent.status',
  'eq': 'open'}
]

Other supported conditions

1
2
{
  "condition": "room_is_public"
}

1
2
 {
  "condition": "user_is_admin"
}

1
2
{
  "condition": "user_is_guest"
} 

1
2
 {
  "condition": "user_is_room_owner"
}

1
2
 {
  "condition": "message_matches",
  "params": {
    "type": "notification"
  }
}

1
2
 {
  "condition": "message_matches",
  "params": {
    "regex": {
      "pattern": "\(yey\)",
      "flags": "i"
    }
  }
}

1
2
 {
  "condition": "message_matches",
  "params": {
    "sender": "My Add-on"
  }
}

1
2
{
  "condition": "message_contains_link"
}

1
2
 {
  "condition": "message_sent_by_current_user"
}

You can negate a condition by using the "invert" attribute on a condition:

1
2
{
  "condition": "user_is_admin",
  "invert": true
}