Neon | Chat API

- John Henderson

- 6
- 10
- 1

- Language:
- Chat 0
- Log Out

# 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.

## Chat 0

Favorites Catherine J. Watkins Nicholas R. Walker Susan J. Best Brandon S. Young Fernando G. Olson
Work Robert J. Garcia Daniel A. Pena Rodrigo E. Lozano
Social Velma G. Pearson Margaret R. Dedmon Kathleen M. Canales Tracy J. Rodriguez

- Art Ramadani

  Are you here?

  09:00
- Catherine J. Watkins

  This message is pre-queued.

  09:25
- Catherine J. Watkins

  Whohoo!

  09:26
- Catherine J. Watkins

  Do you like it?

  09:27

- Daniel A. Pena

  I am going out.

  08:21
- Daniel A. Pena

  Call me when you see this message.

  08:27