Chat API

Neon Chat is simple API Chat platform developed by Laborator that you can use to integrate to your own chat system. It provides bunch of options you can use to support full chat platform. Here you can test the functions and know about their usage details.


See the Markup

Toggle Chat

Link that toggles chat. Just add this attribute to any element: data-toggle="chat"

Toggle Chat Force Open Force Close


With Animation

Toggle Chat w/ Animation Force Open Force Close


Toggle Left Sidebar

This will close the sidebar (if it is already open) when chat shows.

Toggle Chat w/ Sidebar Toggle Chat w/ Sidebar (Animated)

See how its implemented

Code for Toggle Chat 
<a href="#" class="btn btn-default" data-toggle="chat">Toggle Chat</a>

Force open 
<a href="#" class="btn btn-default chat-open">Force Open</a>

Force close 
<a href="#" class="btn btn-default chat-close">Force Close</a>

The above buttons with animation feature 
<a href="#" class="btn btn-default" data-toggle="chat" data-animate="1">Toggle Chat w/ Animation</a>

Toggle Chat + Sidebar 
<a href="#" class="btn btn-default" data-toggle="chat" data-collapse-sidebar="1">Toggle Chat w/ Sidebar</a>

To add animations simply add this attribute: 
data-animate="1"

Chat Bubble

If you want to receive chat notifications, simply add this class .chat-notifications-badge to any element, each time the new message is submitted it will be updated automatically.


Exmaple:

Code 

<span class="badge badge-danger chat-notifications-badge is-hidden"></span>

Always Visible Chat

If you want to have the chat always visible on the right sidebar add class .chat-visible to .page-container element.


Markup

Adding chat functionality to Neon theme its easy. Add #chat container inside .page-content element. Here is an examlpe: 

<div id="chat" class="fixed" data-current-user="Art Ramadani" data-order-by-status="1" data-max-chat-history="25">
<div class="chat-inner">

<h2 class="chat-header">
<a href="#" class="chat-close"><i class="entypo-cancel"></i></a>
<i class="entypo-users"></i>
Chat
<span class="badge badge-success is-hidden">0</span>
</h2>

<div class="chat-group" id="group-1">
<strong>Favorites</strong>
<a href="#" id="sample-user-123" data-conversation-history="#sample_history"><span class="user-status is-offline"></span> <em>Catherine J. Watkins</em></a>
<a href="#"><span class="user-status is-online"></span> <em>Nicholas R. Walker</em></a>
<a href="#"><span class="user-status is-online"></span> <em>Susan J. Best</em></a>
<a href="#"><span class="user-status is-offline"></span> <em>Brandon S. Young</em></a>
<a href="#"><span class="user-status is-idle"></span> <em>Fernando G. Olson</em></a>
</div>
</div>
<!-- conversation template -->
<div class="chat-conversation">
<div class="conversation-header">
<a href="#" class="conversation-close"><i class="entypo-cancel"></i></a>
<span class="user-status"></span>
<span class="display-name"></span> 
<small></small>
</div>
<ul class="conversation-body">
</ul>
<div class="chat-textarea">
<textarea class="form-control autogrow" placeholder="Type your message"></textarea>
</div>
</div>
</div>

<!-- Chat Histories -->
<div class="chat-history" id="sample_history">
<li>
<span class="user">Art Ramadani</span>
<p>Are you here?</p>
<span class="time">09:00</span>
</li>
<li class="opponent">
<span class="user">Catherine J. Watkins</span>
<p>This message is pre-queued.</p>
<span class="time">09:25</span>
</li>
<li class="opponent">
<span class="user">Catherine J. Watkins</span>
<p>Whohoo!</p>
<span class="time">09:26</span>
</li>
<li class="opponent unread">
<span class="user">Catherine J. Watkins</span>
<p>Do you like it?</p>
<span class="time">09:27</span>
</li>
</div>


<!-- Chat Histories -->
<div class="chat-history" id="sample_history_2">
<li class="opponent unread">
<span class="user">Daniel A. Pena</span>
<p>I am going out.</p>
<span class="time">08:21</span>
</li>
<li class="opponent unread">
<span class="user">Daniel A. Pena</span>
<p>Call me when you see this message.</p>
<span class="time">08:27</span>
</li>
</div>

Chat Attributes for #chat container

Attribute Name Description
data-current-user The current user display name which will be sent messages from.
data-order-by-status You can decide wether you want to sort users in groups by their status by adding 1 value to this attribute. Status ordering: 1 online, 2 busy, 3 idle, 4 offline. To change this ordering edit neon-chat.js file.
data-max-chat-history For each chat conversation there is a limit of N messages. Here you can define how many messages per conversation can be stored at maximum. Default value is: 25 records.

Group Attributes

Chat groups are required! So you should at least have one group. For example you can name it Contacts or whatever. To create chat groups simply add new element with .chat-group class and you are done. To add a name to this group insert the <strong> tag as first element of the group with the group name. Inside chat groups you can insert the contacts.

Attribute Name Description
id Group ID is required if you want to manipulate the group via Neon Chat API. Sample example neonChat.removeGroup("sample-group-id");

Contact Attributes

After you have created the group now you can append the chat contacts to it. Simply add <a> elements, for example: 

<a href="#" id="user-id-123"><span class="user-status is-online"></span> <em>Nicholas R. Walker</em></a>

User status element is required inside the link element. For each user define the status, example: <span class="user-status is-busy"></span>, <span class="user-status is-idle"></span> or <span class="user-status is-offline"></span>

Attribute Name Description
id User ID is required if you want to manipulate the group via Neon Chat API, by default this API will automatically assign an ID to each contact.
Sample example neonChat.getUser("user-123"); or neonChat.setStatus("user-123", "offline"); or neonChat.open("user-123");
data-conversation-history You can pre-load Chat History for any contact by simply specifying this attribute. Inside the attribute apply the ID of chat conversation.

Here is an example: 
<a href="#" data-conversation-history="#sample_history"><span class="user-status is-offline"></span> <em>Catherine J. Watkins</em></a>

<!-- Chat History for this user -->
<div class="chat-history" id="sample_history">
<li>
<span class="user">Art Ramadani</span>
<p>Are you here?</p>
<span class="time">09:00</span>
</li>
<li class="opponent">
<span class="user">Catherine J. Watkins</span>
<p>This message is pre-queued.</p>
<span class="time">09:25</span>
</li>
<li class="opponent">
<span class="user">Catherine J. Watkins</span>
<p>Whohoo!</p>
<span class="time">09:26</span>
</li>
<li class="opponent unread">
<span class="user">Faruk zjermi</span>
<p>Do you like it?</p>
<span class="time">09:27</span>
</li>
</div>

API Functions

Function Name Description and Usage Details

neonChat.showChat(animated)

 This function shows the chat contacts container.
Specifying animated attribute with true value, will add animation.

Example: 
neonChat.showChat(true);
Try it!

neonChat.hideChat(animated)

 This function will hide the chat container.
Specifying animated attribute with true value, will add animation.

Example: 
neonChat.hideChat(false);
Try it!

neonChat.toggleChat(animated, collapse_sidebar)

 It the mix of two above functions, which will decide whether to open it if its closed or close it if its opened.
Attribute: animated applying true value, will add animation.
Attribute: collapse_sidebar applying true value, will hide the left sidebar (if its already open) or will show the sidebar if the chat is closed.

Example: 
neonChat.toggleChat(false, true);
Try it!

neonChat.open(user_id)

 Opens chat conversation window for user_id. User ID can be the group element <a> or id of the element inside chat group.

Example: 
// Primary form
neonChat.open("sample-user-123");
// Secondary form
neonChat.open($(".chat-group a#sample-user-123"));
Try it!

neonChat.close()

 Will close current active chat conversation window, no attributes are required.

Example: 
neonChat.close();
Try it!

neonChat.refreshUserIds()

 It will search all contacts in groups and create/open Chat History for contacts that already don't have. You will be likely to call this method when you manually add chat groups, or contacts to groups, but its not required if you use our predefined user/group management functions.

neonChat.pushMessage(id, msg, from, time, fromOpponent, unread)

 This function neonChat.pushMessage(id, msg, from, time, fromOpponent, unread) will broadcast the messages to contacts. It is used for both, sender and receiver. If you act as receiver, the attribute fromOpponent must be set to true.

Attributes:

  • id - Contact ID that will receive the message.
  • msg - The message text that will be sent.
  • from - The name of sender - string value.
  • time - Could be sent as new Date() object or time as string 17:45.
  • fromOpponent - Its a boolean attribute, that will mark the message that is being set as from receiver, also styled differently.
  • unread - This attribute will be used mostly when the previous attribute fromOpponent is true. This function attribute is set to true when you want a message to be marked as new message. If this attribute is set to true the number of unread messages will be updated.

Try it! Send message to Nicholas R. Walker as Susan J. Best
Try it! Reply message to Susan J. Best as Nicholas R. Walker
Try it! Send message to Robert J. Garcia as Daniel A. Pena

neonChat.getStatus(user_id)

 Get the current status of user which is selected by user_id. Will return status_id which can be fetched on neonChat.statuses[status_id].

The status object contains these properties i.e: {class: 'is-online', order: 1, label: 'Online'}.

neonChat.setStatus(user_id, new_status)

 Sets the user status which is selected by user_id. This will also update the CSS Style on contacts list. Available choices: 
// Set online
neonChat.setStatus("sample-user-123", "online");
// Set busy
neonChat.setStatus("sample-user-123", "busy");
// Set away/idle
neonChat.setStatus("sample-user-123", "idle");
// Set offline
neonChat.setStatus("sample-user-123", "offline");
Try it! Set online status for Catherine J. Watkins
Try it! Set busy status for Catherine J. Watkins
Try it! Set idle status for Catherine J. Watkins
Try it! Set offline status for Catherine J. Watkins

neonChat.orderGroups()

 If sorting is enabled (read here) via data-order-by-status attribute, this function can be used to re-sort contacts inside groups. The sorting is determined with Status Priority which can be set on js/neon-chat.js on statues variable. Set order priority for each status. The statuses with lower number will be ordered to top.

neonChat.countUnreadMessages(user_id)

 Will calculate the total number of unread messages on chat history. If you specify the user_id (which is optional) it will return the unread messages for selected user.

neonChat.createGroup(group_name, prepend)

 Create new (blank) chat group. The group_name is required, while prepend is optional.

Attributes:

  • group_name - Group name that will be created.
  • prepend - If you set this to true it will create the group as first entry on the chat groups, otherwise it will append to the bottom.

Returns group_id which can be used then to add, remove, or move contacts from/to this group.

Sample Code: 
var new_group_id = neonChat.createGroup('Party', true);

Try it! Create new group named "Party"

neonChat.removeGroup(group_id, move_users_to_group)

 Delete existing chat group. The group_id is required, while move_users_to_group is optional.

Attributes:

  • group_id - Group ID that will be deleted.
  • move_users_to_group - The current users of this group to place to another group id.

Sample Code: 
neonChat.removeGroup('group-3', 'group-2');

Try it! Delete group "Social" and place contact to "Work"

neonChat.addUser(group_id, display_name, status, prepend, user_id)

 Add user to specified group. The group_id is required, also display_name, status are required to init the user. Last two parameters prepend, user_id are optional.

Attributes:

  • group_id - Existing group ID to add the user
  • display_name - Display Name for this contact
  • status - Status for this user, see status options.
  • prepend - (Optional) Wether to add this user to the top, or to the bottom. This option is valid if contact ordering is off.
  • user_id - (Optional) By default if you don't specify this attribute, it will be automatically generated, or you can apply your desired id.

Returns user_id of newly created user. The equivalent method is neonChat.addUserId(group_id, user_id, display_name, status, prepend) which will require user_id to be set, if you are going to add contacts with IDs.

Sample Code: 
neonChat.addUser(group_id, 'John Doe 123', 'busy', true);

Try it! Add user to "Party" Group (if this group exists)

neonChat.getUser(user_id)

 Will return user object by selecting it via user_id. The user object contains these properties: {$el: $dom_element, messages: [], unreads: 2, status: 'online'}.

neonChat.moveUser(user_id, new_group_id, prepend)

 Will move specific user to specific group. The user_id and new_group_id are required, while prepend is optional.

Attributes:

  • user_id - Existing user ID which is about to move
  • new_group_id - The group ID that will accept this user.
  • prepend - Set the user to the top of group. This option is valid if contact ordering is off.

Sample Code: 
neonChat.moveUser('sample-user-123', 'group-2', true);

Try it! Move Catherine J. Watkins to Work group.