NAME

WebService::HipChat

VERSION

version 0.2001

SYNOPSIS

    my $hc = WebService::HipChat->new(auth_token => 'abc');
    $hc->send_notification('Room42', { color => 'green', message => 'allo' });

    # get paged results:
    my $res = $hc->get_emoticons;
    my @emoticons = @{ $res->{items} };
    while ($res = $hc->next($res)) {
        push @emoticons, @{ $res->{items} };
    }

DESCRIPTION

This module provides bindings for the HipChat API v2. It also provides the command line utility hipchat-send.

METHODS

All methods return a hashref. The $room param can be the id or name of the room. The $user param can be the id, email address, or @mention name of the user. If a resource does not exist for the given parameters, undef is returned.

get_rooms

    get_rooms()
    get_rooms(query => { 'start-index' => 0, 'max-results' => 100 });

Example response:

    {
      items => [
        {
          id => 2,
          links => {
            self => "https://hipchat.com/v2/room/2",
            webhooks => "https://hipchat.com/v2/room/2/webhook",
          },
          name => "General Discussion",
        },
        {
          id => 3,
          links => {
            self => "https://hipchat.com/v2/room/3",
            webhooks => "https://hipchat.com/v2/room/3/webhook",
          },
          name => "Important Stuff",
        },
      links => { self => "https://hipchat.com/v2/room" },
      maxResults => 100,
      startIndex => 0,
    }

get_room

    get_room($room)

Example response:

    {
      created => "2014-06-25T02:28:04",
      guest_access_url => undef,
      id => 2,
      is_archived => 0,
      is_guest_accessible 0,
      last_active => "2014-07-19T02:40:55+00:00",
      links => {
        self => "https://hipchat.com/v2/room/2",
        webhooks => "https://hipchat.com/v2/room/2/webhook",
      },
      name => "General Discussion",
      owner => {
        id => 1,
        links => { self => "https://hipchat.com/v2/user/1" },
        mention_name => "bob",
        name => "Bob Williams",
      },
      participants => [],
      privacy => "public",
      statistics => {
        links => { self => "https://hipchat.com/v2/room/2/statistics" },
      },
      topic => "hipchat commands",
      xmpp_jid => "1_general_discussion\@conf.btf.hipchat.com",
    }

create_room

    create_room({ name => 'monkeys' })

Example response:

    {
      id => 46,
      links => { self => "https://hipchat.com/v2/room/46" },
    }

update_room

    update_room($room, {
        is_archived         => JSON::false,
        is_guest_accessible => JSON::false,
        name                => "Jokes",
        owner               => { id => 17 },
        privacy             => "public",
        topic               => "funny jokes",
    });

set_topic

    set_topic($room, 'new topic');

delete_room

    delete_room($room)

send_notification

    send_notification($room, { color => 'green', message => 'allo' });

get_webhooks

    get_webhooks($room)
    get_webhooks($room, query => { 'start-index' => 0, 'max-results' => 100 });

Example response:

    {
      items => [
        {
          event => "room_message",
          id => 1,
          links => { self => "https://hipchat.com/v2/room/API/webhook/1" },
          name => "hook1",
          pattern => undef,
          url => "http://yourdomain.org/hipchat-webhook",
        },
      ],
      links => { self => "https://hipchat.com/v2/room/API/webhook" },
      maxResults => 100,
      startIndex => 0,
    }

get_webhook

    get_webhook($room, $webhook_id);

create_webhook

    create_webhook($room, {
        url   => 'http://yourdomain.org/hipchat-webhook'
        event => 'room_message',
        name  => 'hook1',
    });

delete_webhook

    delete_webhook($room, $webhook_id);

send_private_msg

    send_private_msg($user, { message => 'allo' });

send_room_msg

    send_room_msg($room, { message => 'allo' });

get_private_history

    $hc->get_private_history($user)
    $hc->get_private_history($user, query => { 'max-results' => 5 });

Example response:

   {
    items        [
        [0] {
            date       "2014-11-13T10:48:33.322506+00:00",
            from       {
                id             123456,
                links          {
                    self   "https://api.hipchat.com/v2/user/123456"
                },
                mention_name   "Bob",
                name           "Bob Williams"
            },
            id         "38988c8c-9120-44ce-87c5-6731a7a3b6",
            mentions   [],
            message    "heres a message and a link http://www.sun.com/",
            type       "message"
        },
        [1] {
            date       "2014-11-13T10:49:02.377436+00:00",
            from       {
                id             123456,
                links          {
                    self   "https://api.hipchat.com/v2/user/123456"
                },
                mention_name   "Bob",
                name           "Bob Williams"
            },
            id         "c1f47537-6506-4f46-b820-eaade5adc5",
            mentions   [],
            message    "A message",
            type       "message"
        }
    ],
    links        {
        self   "https://api.hipchat.com/v2/user/123456/history"
    },
    maxResults   5,
    startIndex   0
   }

get_members

    get_members($room);
    get_members($room, query => { 'start-index' => 0, 'max-results' => 100 });

Example response:

    {
      items => [
        {
          id => 73,
          links => { self => "https://hipchat.com/v2/user/73" },
          mention_name => "momma",
          name => "Yo Momma",
        },
        {
          id => 23,
          links => { self => "https://hipchat.com/v2/user/23" },
          mention_name => "jackie",
          name => "Jackie Chan",
        },
      ],
      links => { self => "https://hipchat.com/v2/room/Test/member" },
      maxResults => 100,
      startIndex => 0,
    }

add_member

Adds a user to a room.

    add_member($room, $user);

remove_member

Removes a user from a room.

    remove_member($room, $user);

get_users

    get_users()
    get_users(query => { 'start-index' => 0, 'max-results' => 100 });

Example response:

    {
      items => [
        {
          id => 1,
          links => { self => "https://hipchat.com/v2/user/1" },
          mention_name => "magoo",
          name => "Matt Wondercookie",
        },
        {
          id => 3,
          links => { self => "https://hipchat.com/v2/user/3" },
          mention_name => "racer",
          name => "Brian Wilson",
        },
      ],
      links => { self => "https://hipchat.com/v2/user" },
      maxResults => 100,
      startIndex => 0,
    }

get_user

    get_user($user)

Example response:

    {
      created        => "2014-06-20T03:00:28",
      email          => 'matt@foo.com',
      group          => {
                          id => 1,
                          links => { self => "https://hipchat.com/v2/group/1" },
                          name => "Everyone",
                        },
      id             => 1,
      is_deleted     => 0,
      is_group_admin => 1,
      is_guest       => 0,
      last_active    => 1405718128,
      links          => { self => "https://hipchat.com/v2/user/1" },
      mention_name   => "magoo",
      name           => "Matt Wondercookie",
      photo_url      => "https://hipchat.com/files/photos/1/abc.jpg",
      presence       => {
                          client => {
                            type => "http://hipchat.com/client/linux",
                            version => 98,
                          },
                          idle => 3853,
                          is_online => 1,
                          show => "away",
                        },
      timezone       => "America/New_York",
      title          => "Hacker",
      xmpp_jid       => '1_1@chat.hipchat.com',
    }

delete_user

    delete_user($user)

get_emoticons

    get_emoticons()
    get_emoticons(query => { 'start-index' => 0, 'max-results' => 100 });

Example response:

    {
      items => [
        {
          id => 166,
          links => { self => "https://hipchat.com/v2/emoticon/166" },
          shortcut => "dog",
          url => "https://hipchat.com/files/img/emoticons/1/dog.png",
        },
      ],
      links => { self => "https://hipchat.com/v2/emoticon" },
      maxResults => 100,
      startIndex => 0,
    }

get_emoticon

    get_emoticon()

Example response:

    {
      creator => {
        id => 11,
        links => { self => "https://hipchat.com/v2/user/11" },
        mention_name => "bob",
        name => "Bob Ray",
      },
      height => 30,
      id => 203,
      links => { self => "https://hipchat.com/v2/emoticon/203" },
      shortcut => "dog",
      url => "https://hipchat.com/files/img/emoticons/1/dog.png",
      width => 30,
    }

get_room_history

    $hc->get_room_history($room)
    $hc->get_room_history($room, { 'max-results' => 5 });

Example response:

   {
    items        [
        [0] {
            date       "2014-11-13T10:48:33.322506+00:00",
            from       {
                id             123456,
                links          {
                    self   "https://api.hipchat.com/v2/user/123456"
                },
                mention_name   "Bob",
                name           "Bob Williams"
            },
            id         "38988c8c-9120-44ce-87c5-6731a7a3b6",
            mentions   [],
            message    "heres a message and a link http://www.sun.com/",
            type       "message"
        },
        [1] {
            date       "2014-11-13T10:49:02.377436+00:00",
            from       {
                id             123456,
                links          {
                    self   "https://api.hipchat.com/v2/user/123456"
                },
                mention_name   "Bob",
                name           "Bob Williams"
            },
            id         "c1f47537-6506-4f46-b820-eaade5adc5",
            mentions   [],
            message    "A message",
            type       "message"
        }
    ],
    links        {
        self   "https://api.hipchat.com/v2/room/XXX/history/latest"
    },
    maxResults   2,
    startIndex   0
   }

share_link

    $hc->share_link($room, { message => 'msg', link => 'http://www.sun.com' });

share_file

    $hc->share_file($destination, { message => 'msg', file => '/tmp/file.png' });

Shares files with $destination, whether that be a room OR a user. If sent to a user, make sure it is their '@' name OR email address. Otherwise we'll think it is a room. For example: '@JohnQPublic' OR 'johnq@public.test instead of 'SomeRoom'

    next($data)

Returns the next page of data for paginated responses.

Example:

    my $res = $hc->get_emoticons;
    my @emoticons = @{ $res->{items} };
    while ($res = $hc->next($res)) {
        push @emoticons, @{ $res->{items} };
    }

CONTRIBUTORS

Andy Baugh <https://github.com/troglodyne>
Chris C. <https://github.com/centreti>
Chris Hughes <https://github.com/chrisspang>
Ken-ichi Mito <https://github.com/mittyorz>
Tim Man <https://github.com/teebszet>

AUTHOR

Naveed Massjouni <naveed@vt.edu>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install WebService::HipChat, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WebService::HipChat

CPAN shell

perl -MCPAN -e shell
install WebService::HipChat

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

get_rooms

get_room

create_room

update_room

set_topic

delete_room

send_notification

get_webhooks

get_webhook

create_webhook

delete_webhook

send_private_msg

send_room_msg

get_private_history

get_members

add_member

remove_member

get_users

get_user

delete_user

get_emoticons

get_emoticon

get_room_history

share_link

share_file

next

CONTRIBUTORS

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions