Permalink
Fetching contributors…
Cannot retrieve contributors at this time
168 lines (106 sloc) 4.91 KB

Usage

With Permabots you can build chat bots and with the same configuration use it for several instant messaging providers. Permabots was born to be a microservice to connect messaging providers to your apps using REST APIs.

A bot in Permabots defines how to react to each client messages. To build responses the bot works with a context to generate responses with Jinja2 templates. This bot behavior can be shared by several instant messaging providers, saving time.

Note

Permabots django app do not have a dashboard. You can configure bots with the REST API (recommended) or using django admin. Remember there is an online implementation with dashboard in Permabots.com you can use it for free.

Bots

.. autoclass:: permabots.models.bot.Bot
        :members: handle_message, handle_hook
        :show-inheritance:

.. autoclass:: permabots.models.bot.IntegrationBot
        :members:
        :show-inheritance:


Telegram

Integrate to Telegram platform only requires token obtained when creating a bot with BotFather

.. autoclass:: permabots.models.bot.TelegramBot
        :members:
        :show-inheritance:

.. autoclass:: permabots.views.hooks.telegram_hook.TelegramHookView
        :members:
        :show-inheritance:


https://github.com/jlmadurga/permabots/raw/master/docs/images/telegram_demo.gif

Kik

Kik platform needs username and api-key. Visit Kik for more information.

.. autoclass:: permabots.models.bot.KikBot
        :members:
        :show-inheritance:

.. autoclass:: permabots.views.hooks.kik_hook.KikHookView
        :members:
        :show-inheritance:

https://github.com/jlmadurga/permabots/raw/master/docs/images/kik_demo.gif

Facebook Messenger

Permabots only require Page Access Token but webhook can't be set automatically. Facebook Messenger requires to set it in its dev dashboard. Permabots generates webhook with bot integration id which is uuid. This url completed with your domain will be used as the webook https://yourdomain/processing/messengerbot/permabots_messenger_bot_id/ When Facebook requires a Verify Token for validate webhook use bot integration id.

Note

Bots integrations can be enable/disable whenever to avoid processing

.. autoclass:: permabots.models.bot.MessengerBot
        :members:
        :show-inheritance:

.. autoclass:: permabots.views.hooks.messenger_hook.MessengerHookView
        :members:
        :show-inheritance:

https://github.com/jlmadurga/permabots/raw/master/docs/images/messenger_demo.gif

Context

Context is used to parametrize processing and to render templates. Some context data is available just bots starts its processing and other is attached as a result of the processing.

Environment

Each bot can have an environment to generate key/value variables to use them accross all processing context. Environement is attached in context as env

Tip

Imagine you are using some auth token to build API requests, set token in environment instead of copying in every place you need it.

.. autoclass:: permabots.models.environment_vars.EnvironmentVar
        :members:
        :show-inheritance:

States

Permabots works generating responses depending on the input, but this is not enough. A bot can be modelled as a state machine and depending on its actual state handle messages. Several states can be defined for each bot.

Permabots maintains associations between chats and states.

Context used in the state transition is attached to the state. Previous state context can be accessed with state_context variable.

Tip

This is useful for example when making some kind of form of questionary to store responses.

.. autoclass:: permabots.models.state.State
        :members:
        :show-inheritance:


Conversation Handlers

A Conversation Handler defines how to react to an incoming message.

  • Pattern: Regular expression the incoming message must fullfil to be executed
  • Request: An HTTP request
  • Response: Templates to generate text and keyboard response
  • Source States: Bot must be in one of the states of this list to be executed
  • Target State: State the bot transitionates when its is processed successfully
  • Priority: It is usefull when more than handler fullfil conditions to be executed
.. autoclass:: permabots.models.handler.Handler
        :members:
        :show-inheritance:


Notification Hooks

Notification hooks can be used to send messages to clients. Just define a response to be generated by POST data and a list of recipients for different providers.

.. autoclass:: permabots.models.hook.Hook
        :members:
        :show-inheritance:


.. automodule:: permabots.views.hooks.permabots_hook
        :members:
        :show-inheritance: