Welcome to listenclosely’s documentation!¶

Documentation¶

The full documentation is at https://listenclosely.readthedocs.org.

• Asker1 is chatting with the Busy Agent
• Asker2 try to chat but no free Agent was free so is waiting with a Pending chat to be attended by an agent
• Asker3 is opening a chat and Online Agent will be assigned to the chat

Quickstart¶

Install listenclosely:

pip install listenclosely

Then use it in a project:

import listenclosely

Add it to django apps and migrate:

INSTALLED_APPS = [
        ...
'listenclosely',
...
]
python manage.py migrate

Select, install and configure service backend

LISTENCLOSELY_MESSAGE_SERVICE_BACKEND = "listenclosely_telegram.service.TelegramMessageServiceBackend"

Define your agent strategy or define your own:

LISTENCLOSELY_AGENT_STRATEGY = 'listenclosely.strategies.first_free.FirstFreeAgentStrategy'

Add step to your celery app:

from listenclosely.celery import ListenCloselyAppStep
app.steps['worker'].add(ListenCloselyAppStep)

Start your celery app usign gevent:

celery --app=demo_app.celery:app worker -P gevent

Call listen task or define a celery scheduler to execute:

from listenclosely import tasks
tasks.listen.delay()

Features¶

• Connects Askers and Agents in chats to establish a Chat
• Strategies to find Agent to attend new Asker chat. Define your own strategies
• Messaging Service Backend: Define your own messaging service backend implementations.
• Cron tasks for attending pending chats and to terminate obsolete chats to release Agents

Running Tests¶

Does the code actually work?

source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install -r requirements/test.txt
(myenv) $ make test

How it works¶

• Asker1 is chatting with the Busy Agent
• Asker2 try to chat but no free Agent was free so is waiting with a Pending chat to be attended by an agent
• Asker3 is opening a chat and Online Agent will be assigned to the chat

State machines of Agent and Chat:

Agent stategy¶

Just extend strategies.base.BaseAgentStrategy and define your own free_agent function:

class FirstFreeAgentStrategy(BaseAgentStrategy):
"""
Choose first free agent
"""

def free_agent(self):
        free_agents = Agent.online.all()
        if free_agents:
        return free_agents[0]
        return None

Then configure settings:

LISTENCLOSELY_AGENT_STRATEGY = 'your_strategy.YourAgentStrategy'

Message Service Backend¶

Extend services.base.BaseMessageServiceBackend. You must implement some methods:

def listen(self):
    """
    Connect to service and listen for receive messages.
    To implement in concrete services
    """
    raise NotImplementedError('subclasses of BaseMessageServiceBackend must override listen() method')

def send_message(self, id_service, content):
    """
    Send message to a instant messages service
    To implement in concrete services
    :rtype string message_id: identifier for message service
    """
    raise NotImplementedError('subclasses of BaseMessageServiceBackend must override send_message() method')

def disconnect(self):
    """
    Disconnect to service.
    To implement in concrete services
    """
    raise NotImplementedError('subclasses of BaseMessageServiceBackend must override disconnect() method')

Use other services as example. At the moment:

• Whatsapp: https://github.com/jlmadurga/listenclosely-whatsapp
• Telegram: https://github.com/jlmadurga/listenclosely-telegram

Types of Contributions¶

Get Started!¶

Ready to contribute? Here’s how to set up listenclosely for local development.

1. Fork the listenclosely repo on GitHub.

2. Clone your fork locally:

   $ git clone git@github.com:your_name_here/listenclosely.git
   

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

   $ mkvirtualenv listenclosely
   $ cd listenclosely/
   $ python setup.py develop
   

4. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature
   

Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

$ flake8 listenclosely tests
$ python setup.py test
$ tox

To get flake8 and tox, just pip install them into your virtualenv.

6. Commit your changes and push your branch to GitHub:

   $ git add .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature
   

7. Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check https://travis-ci.org/jlmadurga/listenclosely/pull_requests and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ python -m unittest tests.test_listenclosely

Development Lead¶

• Juan Madurga <jlmadurga@gmail.com>

Contributors¶

None yet. Why not be the first?

0.1.0 (2016-01-14)¶

• First release on PyPI.