Persistent chat for Django
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Conversate - Persistent chat for Django

A simple lightweight persistent chat app for Django sites, where users may not always be around at the same time.

Requiring nothing other than a working Django installation, messages can be left for users to pick up later, users can opt in to receive e-mail alerts of activity when they are away, and real-time conversations are supported through simple polling so it will work through the most restrictive of firewalls.


  • Admins create rooms and add users to them
  • Messages are stored in the database
  • Full history is available to all users of that room
  • Simple jquery-based polling for real-time updates
  • Users can opt in to receive e-mail alerts of activity when away
  • Support for users without javascript

Version 0.1.0

  • See CHANGES for full changelog and roadmap
  • See UPGRADE for how to upgrade from earlier releases

Please note: this is designed for small groups to have infrequent conversations which are often asynchronous; because each poll event will create a new HTTP connection, installations where a large number of concurrent users are expected should look for a different solution involving long-polling and websockets.

There is an example site in the example directory.


These packages are required:

  • Django >= 1.4

If using a version of Django earlier than 1.7, it is recommended that you use South to manage schema migrations, as future versions of Conversate will need changes to the database.


  1. Install django-conversate (currently only on github):

    pip install -e git+

    Note: The master branch may sometimes contain minor changes made since the version was incremented. These changes will be listed in CHANGES. It will always be safe to use, but versions will be tagged if you only want to follow releases.

  2. Add Conversate to INSTALLED_APPS:


    You may also want to change some settings here (see Settings below)

    If using Django 1.6 or earlier with South, you will need to change SOUTH_MIGRATION_MODULES to {'conversate': 'conversate.south_migrations'}.

  3. Include the URLconf in your project's

    url(r'^conversate/', include('conversate.urls')),
  4. Make sure your base.html template has the necessary blocks, or override Conversate's base, conversate/base.html (see `Templates`_ below). You will also want to create a link somewhere to conversate-index (or conversate.views.index) so users can access it.

  5. Add the models to the database:

    python migrate conversate

    If using South, make sure you set


Add these settings to your file to override the defaults.


If True, adds the bundled version of jQuery when required

Default: True


Number of lines to show on a page

Default: ``100`


The time until the UI decides that the user is idle (in ms)

Default: 60*1000


Minimum poll interval (in ms)

Default: 5 * 1000


Maximum poll interval (in ms)

Default: 60 * 1000


Amount to increase poll interval by when there is no activity (in ms)

Default: 5 * 1000


If True, Conversate's JavaScript will control the layout: * changes the container element to position:relative and padding:0 * maximises container element's height into available space in the window * makes the conversation scroll in place * moves the input field to the bottom of the container

Default: True


How long before marking the user as disconnected (in secs)

Defaults to POLL_MAX plus 30 seconds, 60 + 30


From address for alert e-mails

Default: DEFAULT_FROM_EMAIL (from main Django settings)

Templates and styles

The Conversate templates extend conversate/base.html, which in turn extends base.html. The templates use HTML5 elements.

They will expect the following blocks:

  • js for inserting JavaScript
  • css for inserting CSS
  • title for inserting the title (plain text) - or {{ title }} instead
  • content for the body content

You will need to add these to your base.html template. Alternatively, if you already have the blocks but with different names, create conversate/base.html in your own templates folder and map them; for example:

{% block script %}
    {{ block.super }}
    {% block js %}{% endblock %}
{% endblock %}

Once you have mapped these blocks, the default settings and templates should work out of the box with most designs. However, the conversate container element in your site's base template must:

  • have css position either relative or absolute
  • have an explicit height if CONVERSATE_LAYOUT_FIXED is False, otherwise it must expect its height to be controlled by conversate.

There is a simple layout example in the example project in the git root.

There is a single global JavaScript variable used, CONVERSATE, which the template uses to pass settings and variables to the JavaScript.


Set up one or more rooms in the Django admin site, and the rooms will be listed for your users on the conversate index page.

Users can double-click the poll timer to force a faster poll.


Thanks to all contributors, who are listed in CHANGES.