Build a Realtime Chat Widget into Your Web App in 5 minutes.

We've built a Realtime Chat Widget that lets you to quickly add chat into your applications. Follow the 3 steps below to get started, it is that EASY!

Get it Now!

... or try it!

The demo should load shortly...

1. Download & Create a Free Account

If you have a github account and are happy using git you can fork or clone the project from github (or download a zip instead).

Once you have the code you should make it accessible on your chosen web server hosting. For the purposes of getting up and running we’ll assume that the code is in a directory named pusher-realtime-chat-widget in the root of your app.

You will also need to Create a Free Pusher Account.

2. Add the Dependencies

To do this we’ll need to include a few JavaScript libraries; the Pusher JavaScript library, jQuery and the PusherChatWidget JavaScript library and stylesheet:

<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.0.2/jquery.min.js"></script> <script src="//js.pusher.com/2.2/pusher.min.js"></script> <!-- Downloaded in step 1 --> <script src="pusher-realtime-chat-widget/src/js/PusherChatWidget.js"></script> <link href="pusher-realtime-chat-widget/src/pusher-chat.css" rel="stylesheet" type="text/css" />

3. Initialize Pusher Chat Widget

Now the libraries are included we need to connect to Pusher and create a PusherChatWidget instance, passing in the pusher instance, which will then subscribe to a chat channel based on the URL of the current page and create the chat widget in the UI. This can be done in just a few lines of code. The only change you’ll need to make is to replace the YOUR_APP_KEY with your app_key.

$(function() { var pusher = new Pusher('YOUR_APP_KEY'); var chatWidget = new PusherChatWidget(pusher, { chatEndPoint: 'pusher-realtime-chat-widget/src/php/chat.php' }); });

In the example above you’ll see that we’ve also passed in a second options parameter to the PusherChatWidget constructor. This is so the widget knows where to make the AJAX requests to in order for the server to validate and then trigger chat messages. The value of chatEndPoint should be updated so that the following file is executed (depending on your server technology):

4. Create & Update your Config

Within the sample application you’ll find a config_example.file_ext file (the config file location and file_ext on which server technology you’ve chosen to use). Copy this file and create a new files called just config.file_ext. Update this new file with your own Pusher credentials:

// config.php define('APP_KEY', 'YOUR_APP_KEY'); define('APP_SECRET', 'YOUR_APP_SECRET'); define('APP_ID', 'YOUR_APP_ID'); # config.rb require 'pusher' Pusher.app_id = 'YOUR_APP_KEY' Pusher.key = 'YOUR_APP_SECRET' Pusher.secret = 'YOUR_APP_ID'

You Are Done, It's That Easy!

Now that you've added the widget to your page, told it where the server trigger code is and configured the server code with your Pusher App credentials the chat widget should now be up and running on your web app or site. If you're experiencing any problems please get in touch.

Create your FREE Account

Where next? A better Realtime Chat Widget

Now you’ve got your Pusher-Powered Realtime Chat widget up and running it’s time to consider how you can make this widget work with your site or application; how can you integrate it with your app and what features can you add to make it much more exciting, usable and valuable? Here are a few ideas:

Personalise by integrating with your existing user accounts

In the example widget we’re using Gravatar to personalise the chat. If a user supplies the optional email address we can use it to look up their Gravatar (Avatar) and display it along with their chosen nickname when they send a chat message. However, many applications already have user accounts so rather than using Gravatar it would be great to use the existing user account information.

For the moment the widget only supports a displayName and and image and you can use your own by passing them into the Activity object constructor:

$options = array( 'displayName' => 'Dave the PHP Guru', 'image' => array( 'url' => 'path_to_avatar_for_dave.png', 'height => '48', 'width => '48' ) ); $activity = new Activity('chat-message', $chat_info['text'], $options); options = { 'displayName' => 'Dave the PHP Guru', 'image' => { 'url' => 'path_to_avatar_for_dave.png', 'height => '48', 'width => '48' } } activity = Activity.new('chat-message', chat_info['text'], options);

Add extra checking to incoming requests

Chat Messages

Whilst the widget does try to strip out any HTML characters it doesn’t try to remove any profanity or anything else that others might find offensive. It might be a good idea to replace sweary words with funny images or reject the messages altogether.

You could also add some funny easter eggs like replacing certain words with images or kicking users out of the chat if they start talking about something you just don’t like - hey it’s your app after all!

Cross-site request forgery (and similar)

You will also want to ensure that the call to your server code has come from your web page or app. For more information simply Google CSRF and see the Wikipedia entry on CSRF.

Only let a logged in user participate in the chat

This is a pretty simple one. You could only display the chat widget if users are logged. Or, you could only let users participate if they are logged in, otherwise they can only view what’s being discussed.

The best way of ensuring that only logged in users can use the chat widget is by using a private channel which requires that the subscription to the channel is authenticated.

Read more about private channels and authenticating users

Make it a site-wide chat widget

The widget currently looks at the URL of the page or web application and creates a channel based on that. You could make widget use just one channel name for the entire site so that all users on the website use the same channel. This can actually be done now by providing a channel name option when creating the PusherChatWidget object:

$(function() { var pusher = new Pusher('YOUR_APP_KEY'); var chatWidget = new PusherChatWidget(pusher, { chatEndPoint: 'pusher-realtime-chat-widget/src/php/chat.php', channelName: 'site-wide-chat-channel' }); });

Read more about Channels

Handle unreliable connections

You can’t guarantee that the user of your web app has the best connection in the world so we’ve provided a way of accessing connection state events. You could update the widget so that it shows the state of the user’s connection. If the users can’t connect and the connection is unavailable then you could stop the user from using the widget and tell them that they appear to be offline at the moment.

Read more about connection states

Show chat participants using Pusher Presence

We provide a way of seeing who’s subscribed to a channel at any time through functionality we call Presence. You could update the chat widget to use a presence channel and then show who was online and participating in the chat at any time. You could also show events within the UI whenever a users joins or leaves the channel.

Read more about Presence

Storing a history of messages

The widget doesn’t save any of the messages to a database so we can’t pre-load any messages when the widget first loads. It also means messages aren’t searchable - which might be a nice feature.

At the moment the widget converts to showing who a users is when they send their first chat message. But if they then navigate to a different page the information about the user will be lost. If the widget were updated to store that information in the user session or a cookie then when the page loads for a user we can update the widget to show the user details, and we won’t need the user to enter them again.

Note: we might update the example to do this since it could get pretty annoying for a user if they have to keep doing that

Questions

If you’ve any questions about the Pusher Realtime Chat Widget examples please get in touch or ask a question by posting an issue/question on the github project.