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¶
-
class
permabots.models.bot.
Bot
(*args, **kwargs)[source]¶ Bases:
permabots.models.base.PermabotsModel
Model representing a Permabot. Its behavior is shared by all service integrations.
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- owner_id (ForeignKey) – User who owns the bot
- name (CharField) – Name for the bot
- telegram_bot_id (OneToOneField) – Telegram Bot
- kik_bot_id (OneToOneField) – Kik Bot
- messenger_bot_id (OneToOneField) – Messenger Bot
-
handle_hook
(hook, data)[source]¶ Process notification hook.
Parameters: - hook (Hook
Hook
) – Notification hook to process - data – JSON data from webhook POST
- hook (Hook
-
handle_message
(message, bot_service)[source]¶ Process incoming message generating a response to the sender.
Parameters: - message – Generic message received from provider
- bot_service (IntegrationBot
IntegrationBot
) – Service Integration
Note
Message content will be extracted by IntegrationBot
-
class
permabots.models.bot.
IntegrationBot
(*args, **kwargs)[source]¶ Bases:
permabots.models.base.PermabotsModel
Abstract class to integrate new instant messaging service.
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- enabled (BooleanField) – Enable/disable telegram bot
-
build_keyboard
(keyboard)[source]¶ From an arrays of strings generated specific keyboard for integration
Parameters: keyboard – list(strings) Returns: specific keyboard
-
create_chat_state
(message, target_state, context)[source]¶ Crate specific chat state modelling for the integration. It is called only when first chat interaction is performed by a user.
Parameters: - message – Message from the provider
- target_state – State to set
- context – Processing generated in the processing
-
get_chat_id
(message)[source]¶ Extract chat identifier from service message.
Parameters: message – Message from provider Returns: chat identifier
-
get_chat_state
(message)[source]¶ Each integration has its own chat state model. Implement this method to obtain it from message
Parameters: message – Message from provider Returns: generic chat state
-
hook_id
¶ Identifier to generate webhook url i.e. primary key UUID
Returns: Identifier Return type: string
-
hook_url
¶ Name of the view to resolve url. i.e. permabots:telegrambot :returns: Named view
-
identity
¶ Some service identifier to attach in processing context i.e. telegram.
Returns: Service Indentifier Return type: string
-
message_text
(message)[source]¶ Extract text message from generic message :param message: Message from provider :returns: text from message :rtype: string
-
null_url
¶ Return a none URL to remove webhook. i.e.: None
Returns: None url Note
Some providers API accepts None but others need a real url. Use https://example.com in this case
-
send_message
(chat_id, text, keyboard, reply_message=None, user=None)[source]¶ Send message with the a response generated.
Parameters: - chat_id – Identifier for the chat
- text – Text response
- keyboard – Keyboard response
- reply_message – Message to reply
- user – When no replying in some providers is not enough with chat_id
Note
Each provider has its own limits for texts and keyboards buttons. Implement here how to split a response to several messages.
Telegram¶
Integrate to Telegram platform only requires token
obtained when creating a bot with BotFather
-
class
permabots.models.bot.
TelegramBot
(*args, **kwargs)[source]¶ Bases:
permabots.models.bot.IntegrationBot
Telegram integration.
Permabots only requires token to set webhook and obtain some bot info.
Follow telegram instructions to create a bot and obtain its token https://core.telegram.org/bots#botfather.
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- enabled (BooleanField) – Enable/disable telegram bot
- token (CharField) – Token provided by Telegram API https://core.telegram.org/bots
- user_api_id (OneToOneField) – Telegram API info. Automatically retrieved from Telegram
Kik¶
Kik platform needs username
and api-key
. Visit Kik for more information.
-
class
permabots.models.bot.
KikBot
(*args, **kwargs)[source]¶ Bases:
permabots.models.bot.IntegrationBot
Kik integration.
Permabots sets webhook. Only requires api_key and username from Kik provider.
Follow Kik instructons to create a bot and obtain username and api_key https://dev.kik.com/.
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- enabled (BooleanField) – Enable/disable telegram bot
- api_key (CharField) – Kik bot api key
- username (CharField) – Kik bot user name
-
class
permabots.views.hooks.kik_hook.
KikHookView
(**kwargs)[source]¶ Bases:
rest_framework.views.APIView
View for Kik webhook.
-
post
(request, hook_id)[source]¶ - Process Kik webhook:
- Get an enabled Kik bot
- Verify Kik signature
- Serialize each message
- For each message create
KikMessage
andKikUser
- Delay each message processing to a task
- Response provider
-
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
-
class
permabots.models.bot.
MessengerBot
(*args, **kwargs)[source]¶ Bases:
permabots.models.bot.IntegrationBot
Facebook Messenger integration.
Permabots only uses Page Access Token but webhook is not set. It mus be set manually in Facebook dev platform using UUID generated as id of the messenger bot after creation in Permabots.
This bot is used to Verify Token and generate url https://domain/processing/messengerbot/permabots_messenger_bot_id/
Read Messenger documentation <https://developers.facebook.com/docs/messenger-platform/quickstart> _.
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- enabled (BooleanField) – Enable/disable telegram bot
- token (CharField) – Messenger token
-
class
permabots.views.hooks.messenger_hook.
MessengerHookView
(**kwargs)[source]¶ Bases:
rest_framework.views.APIView
View for Facebook Messenger webhook
-
get
(request, hook_id)[source]¶ Verify token when configuring webhook from facebook dev.
MessengerBot.id is used for verification
-
post
(request, hook_id)[source]¶ - Process Messenger webhook.
- 1. Get an enabled Messenger bot
3. For each message serialize
4. For each message create
MessengerMessage
5. Delay processing of each message to a task 6. Response provider
-
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.
-
class
permabots.models.environment_vars.
EnvironmentVar
(*args, **kwargs)[source]¶ Bases:
permabots.models.base.PermabotsModel
Environment Variable associated to a Bot.
Use it in contexts as {{ env.variable_key }}.
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- bot_id (ForeignKey) – Bot which variable is attached.
- key (CharField) – Name of the variable
- value (CharField) – Value of the variable
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.
-
class
permabots.models.state.
State
(*args, **kwargs)[source]¶ Bases:
permabots.models.base.PermabotsModel
Represents a state for a conversation and a bot.
Depending the state of the chat only some actions can be performed.
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- name (CharField) – Name of the state
- bot_id (ForeignKey) – Bot which state is attached to
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
-
class
permabots.models.handler.
Handler
(*args, **kwargs)[source]¶ Bases:
permabots.models.base.PermabotsModel
Model to handler conversation message
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- bot_id (ForeignKey) – Bot which Handler is attached to
- name (CharField) – Name for the handler
- pattern (CharField) – Regular expression the Handler will be triggered. Using https://docs.python.org/2/library/re.html#regular-expression-syntax
- request_id (OneToOneField) – Request the Handler processes
- response_id (OneToOneField) – Template the handler uses to generate response
- enabled (BooleanField) – Enable/disable handler
- target_state_id (ForeignKey) – This state will be set when handler ends processing
- priority (IntegerField) – Set priority execution. Higher value higher priority
-
process
(bot, message, service, state_context, **pattern_context)[source]¶ Process conversation message.
- Generates context
- service: name of integration service
- state_context: historic dict of previous contexts. identified by state
- pattern: url pattern dict
- env: dict of environment variables associated to this bot
- message: provider message
- emoji: dict of emojis use named notation with underscores <http://apps.timwhitlock.info/emoji/tables/unicode> _.
Process request (if required)
Generates response. Text and Keyboard
Prepare target_state and context for updating chat&state info
Parameters: - bot – Bot the handler belongs to
- message – Message from provider
- service (string) – Identity integration
- state_context (dict) – Previous contexts
- pattern_context (dict) – Dict variables obtained from handler pattern regular expression.
Returns: Text and keyboard response, new state for the chat and context used.
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.
-
class
permabots.models.hook.
Hook
(*args, **kwargs)[source]¶ Bases:
permabots.models.base.PermabotsModel
Notification Hook representation.
The webhook url is generated with the key.
Parameters: - id (UUIDField) – Id
- created_at (DateTimeField) – Date created
- updated_at (DateTimeField) – Date updated
- bot_id (ForeignKey) – Bot which Hook is attached
- name (CharField) – Name of the hook
- key (CharField) – Key generated to complete the Hook url. http://permabots.com/process/hook/{{key}}
- response_id (OneToOneField) – Template the hook uses to generate the response
- enabled (BooleanField) – Enable/disable hook