NAME

Chat::iFly - An interface to the iFlyChat service.

SYNOPSIS

 use Chat::iFly;
 
 my $chat = Chat::iFly->new(
    api_key                 => 'afsdadfafdsadfsafsd',
    static_asset_base_uri   => '//www.myserver.com/ifly',
    ajax_uri                => '//www.myserver.com/chat/login'
 );
 
 my $user = {
    id          => 4321,
    name        => 'Joe Blow',
    avatar_uri  => '//www.myserver.com/uploads/joe.blow.avatar.jpg',
    profile_uri => '//www.myserver.com/users/4321',
 };
 
 my $html_to_inline_into_page = $chat->render_html($user); 
 my $response_to_chat_login = $chat->render_ajax($user);

DESCRIPTION

A wrapper needed to authenticate to iflychat.com.

Setup

You'll need to go here https://iflychat.com/iflyapi/index and register for an API Key. You'll specify that using api_key passed to the constructor.

You'll need to copy the public folder from this distribution onto your web server somewhere. You'll specify where that is using the static_asset_base_uri passed tot he constructor.

You'll need to build 2 things into your web server:

Inline HTML

You'll need to inline the result of render_html into any web page where you want the chat to appear.

AJAX Method

You'll need to set up an ajax method in your app that returns the result of render_ajax. You'll pass the URL where that can be found into the constructor using ajax_uri.

And finally you need to call update_settings to tell the iFly servers what your settings are.

METHODS

The following methods are available.

new ( params )

Constructor.

params

A hash of parameters.

api_key

Required. The key generated on the iFly Chat Dashboard.

static_asset_base_uri

Required. The URL where you have installed the static files found in the public folder of the Chat::iFly github repository.

ajax_uri

Required. The URL where you have installed the response to the render_ajax method.

minimize_chat_user_list

Defaults to 2. Must be 1 or 2. Minimize online user list by default. 2 means Yes. 1 means No.

enable_search_bar

Defaults to 1. Must be 1 or 2. Show search bar in online user list. 1 means Yes. 2 means No.

chat_topbar_color

Defaults to #222222. Choose the color of the top bar in the chat.

chat_topbar_text_color

Defaults to #FFFFFF. Choose the color of the text in top bar in the chat.

font_color

Defaults to #222222. Choose the color of the text in the chat.

chat_list_header

Defaults to Chat. This is the text that will appear in header of chat list.

support_chat_init_label

Defaults to Chat with us. The label for Start Chat button, which when clicked upon will launch chat.

support_chat_box_header

Defaults to Support. This is the text that will appear as header of chat box.

support_chat_box_company_name

Defaults to Support Team. Name of your team or company which the visitors will see in the chat box.

support_chat_box_company_tagline

Defaults to Ask us anything.... Your team/company tagline.

support_chat_auto_greet_enable

Defaults to 1. Must be 1 or 2. 1 means that the auto greeting is enabled.

support_chat_auto_greet_message

Defaults to Hi there! Welcome to our website. Let us know if you have any query!. This is the text of an auto greeting message which will be displayed to visitors.

support_chat_auto_greet_time

Defaults to 1. The delay, in seconds, after which the first time visitors will be shown auto greeting message.

support_chat_init_label_off

Defaults to Leave Message. The label for Leave Message button, which when clicked upon will offline form.

support_chat_offline_message_desc

Defaults to Hello there. We are currently offline. Please leave us a message. Thanks.. This is the description shown in Support Chat Offline window.

support_chat_offline_message_label

Defaults to Message. This is the label for the Message textarea in Support Chat Offline window.

support_chat_offline_message_contact

Defaults to Contact Details. This is the label for the <i>Contact Details</i> textarea in Support Chat Offline window.

support_chat_offline_message_send_button

Defaults to Send Message. This is the label for the Send Button textarea in Support Chat Offline window.

support_chat_offline_message_email

Enter all email addresses (separated by comma) to which notification should be sent when a user leaves a message via Offline Form.

go_online_label

Defaults to Go Online. Set this to change the label of the status of a user to an online state.

go_idle_label

Defaults to Go Idle. Set this to change the label of the status of a user to an idle state.

new_message_label

Defaults to New chat message!. Set this to change the label of the notification when a new chat message has come in.

public_chatroom_header

Defaults to Public Chatroom. This is the text that will appear in header of public chatroom.

enable_chatroom

Defaults to 1. Must be 1 or 2. 1 means that the public chatroom is enabled.

theme

Defaults to light. Must be light or dark. Other options may exist in the future, or you could create your own.

notification_sound

Defaults to 1. Must be 1 or 2. When set to 1 the chat will play a notification sound when a message is posted.

sound_player_uri

Defaults to static_asset_base_uri + /swf/sound.swf. The URL to where the sound player is stored.

sound_file_uri

Defaults to static_asset_base_uri + /wav/notification.mp3. The URL to where the notification sound is stored.

enable_smiley

Defaults to 1. Must be 1 or 2. When set to 1 users will have access to emoticons.

smiley_uri

Defaults to static_asset_base_uri + /smileys/very_emotional_emoticons-png/png-32x32/. The URL to where the emoticons are stored.

log_messages

Defaults to 1. Must be 1 or 2. When set to 1 chat messages will be logged to the user's inbox. See get_message_inbox.

anon_prefix

Defaults to Guest. A prefix that will be applied to anonymous generated usernames.

use_local_anonymous_names

Perl boolean. When true guest names will be pulled from local_anonymous_names, which is faster than consulting the remote server. When false a list of names will be polled from the iFly server.

local_anonymous_names

An array reference of local names. There's a default list of 50 or so English sounding names. For use with use_local_anonymous_names.

use_stop_word_list

Defaults to 1. Must be 1. Whether to use stop_word_list to filter user posts. 1 means don't filter. 2 means filter in public chat room. 3 means filter in private chats. 4 means filter in all chats.

stop_word_list

A comma separated string of "bad" words. A list of about a hundred defaults this list.

stop_links

Defaults to 1. Must be 1, 2, 3, or 4. 1 means don't block links. 2 means block in public chatroom. 3 menas block in private chat rooms. 4 means block in all chats.

allow_anon_links

Defaults to 2. Must be 1 or 2. 1 means apply stop_links only to anonymous users. 2 means apply stop_links to all users.

allow_render_images

Defaults to 1. Must be 1 or 2. When set to 1 images and video links will be rendered inline in the chat.

allow_user_font_color

Defaults to 1. Must be 1 or 2. When set to 1 users can set their name color.

allow_single_message_delete

Defaults to 1. Must be 1, 2, or 3. Allow users to delete messages selectively when in private conversation. 1 means allow all users. 2 means allow moderators. 3 means do not allow.

allow_clear_room_history

Defaults to 1. Must be 1, 2, or 3. Allow users to clear all messages in a room. 1 means allow all users. 2 means allow moderators. 3 means do not allow.

rel

Defaults to 2. Must be 1 or 2. When set to 2 the chat will be in "Community" mode, which means users can talk to each other. When set to 1 the chat is in "Support" mode and users can only talk to admins.

user_picture

Defaults to 1. Must be 1 or 2. 1 means to enable user avatars.

no_users_html

Determine how to render the list when no users are online. Defaults to:

 <div class="item-list"><ul><li class="drupalchatnousers even first last">No users online</li></ul></div>

uri

The base URI of the service you're interacting with. Defaults to https://api.iflychat.com.

port

The port you're interacting with for iFly. Defaults to 443.

agent

A HTTP::Thin object.

render_html( user )

This method renders the HTML you need to inline into your web page to configure the chat.

user

A hash reference containing a user as defined in get_key. However, you only need to pass this in if the user is registered with the site, not for anonymous users.

render_ajax( user )

This method renders the response that will log the user into the chat.

NOTE: For best performance and to ensure persistent user names for anonymous users you should cache the result of this method in your session management system.

user

Required. A hash reference containing a user definition. For an anonymous user call generate_anonymous_user. Otherwise define the user as described in the get_key method.

init( user )

This method is called by render_html to generate the list of settings to initialize the chat. There should proably not be a reason for you to call it yourself.

user

A hash reference containing a user as defined in get_key. However, you only need to pass this in if the user is registered with the site, not for anonymous users.

generate_anonymous_user()

Generates an anonymous user hash reference to be used with get_key or render_ajax.

fetch_anonymous_name( )

Retrieves a random name from the iFly servers for anonymous users. This is called by generate_anonymous_user and probably doesn't need to be used by you.

get_key( user )

This method is used to essentially log a user into the chat system. It generates a key that is used by the javascript to communicate back to the chat server.

user

A hash reference containing the definition of a user. If this is an anonymous user then generate it using generate_anonymous_user.

id

The unique id of the user. It can be any alphanumeric string, and cannot contain special characters or start with a number. I recommend hex encoding your string and then prepending "ifly" on it to create a string that fits their ID scheme.

name

The name or username of the user.

is_admin

Defaults to 0. Can be set to 1 if the user should have chat admin privileges.

custom_roles

Defaults to normal. Ignored entirely if is_admin is set to 1. You can also pass in a hash of custom roles (not admin or normal) that will be used as CSS classes for styling. For example:

 {
    1   => 'cool',
    2   => 'slick',
 }

avatar_uri

A URI string that references a picture used to identify the user.

profile_uri

A URI string that will link other users to this user's profile on the web site.

relationships_set

This allows you to set up buddy lists within the chat. It is a hash reference taking the form of:

 {
    1   => {
        name        => 'friend',
        plural      => 'friends',
        valid_uids  =>  ['user_id_1', 'user_id_5', 'user_id_3']
    },
    2   => {
        name        => 'co-worker',
        plural      => 'co-workers',
        valid_uids  =>  ['user_id_3', 'user_id_4', 'user_id_2']
    },
 }

update_settings( )

Updates the iFly servers with all the configured settings you passed into the constructor of this object. This must be called when you first start using this module, and also each time that you make changes to your settings.

get_message_thread(uid1, uid2)

Returns a hash reference of a message thread between two users.

uid1

Required. The unique user id of the first user in the discussion.

uid2

Required. The unique user id of the second user in the discussion.

get_message_inbox(uid)

Returns a hash reference containing the messages in the user's inbox.

uid

The unique user id of the user who's inbox you want to retrieve.

get(path, params)

Performs a GET request, which is used for reading data from the service.

path

The path to the REST interface you wish to call.

params

A hash reference of parameters you wish to pass to the web service.

post(path, params)

Performs a POST request, which is used for creating data in the service.

path

The path to the REST interface you wish to call.

params

A hash reference of parameters you wish to pass to the web service.

PREREQS

HTTP::Thin Ouch HTTP::Request::Common JSON URI Moo

SUPPORT

Repository

http://github.com/rizen/Chat-iFly

Bug Reports

http://github.com/rizen/Chat-iFly/issues

AUTHOR

JT Smith <jt_at_plainblack_dot_com>

LEGAL

This module is Copyright 2014 Plain Black Corporation. It is distributed under the same terms as Perl itself.

cpanm Chat::iFly

perl -MCPAN -e shell
install Chat::iFly