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.


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 you can use it for free.


class*args, **kwargs)[source]

Bases: permabots.models.base.PermabotsModel

Model representing a Permabot. Its behavior is shared by all service integrations.

  • 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.

  • hook (Hook Hook) – Notification hook to process
  • data – JSON data from webhook POST
handle_message(message, bot_service)[source]

Process incoming message generating a response to the sender.

  • message – Generic message received from provider
  • bot_service (IntegrationBot IntegrationBot) – Service Integration


Message content will be extracted by IntegrationBot

class*args, **kwargs)[source]

Bases: permabots.models.base.PermabotsModel

Abstract class to integrate new instant messaging service.

  • id (UUIDField) – Id
  • created_at (DateTimeField) – Date created
  • updated_at (DateTimeField) – Date updated
  • enabled (BooleanField) – Enable/disable telegram bot

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.

  • message – Message from the provider
  • target_state – State to set
  • context – Processing generated in the processing

Extract chat identifier from service message.

Parameters:message – Message from provider
Returns:chat identifier

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

Identifier to generate webhook url i.e. primary key UUID

Return type:string

Name of the view to resolve url. i.e. permabots:telegrambot :returns: Named view


Some service identifier to attach in processing context i.e. telegram.

Returns:Service Indentifier
Return type:string

Implement this method to perform some specific intialization to the bot


Extract text message from generic message :param message: Message from provider :returns: text from message :rtype: string


Return a none URL to remove webhook. i.e.: None

Returns:None url


Some providers API accepts None but others need a real url. Use in this case

send_message(chat_id, text, keyboard, reply_message=None, user=None)[source]

Send message with the a response generated.

  • 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


Each provider has its own limits for texts and keyboards buttons. Implement here how to split a response to several messages.


Implement this method set webhook if the services requires

Parameters:url – URL generated to use for this bot


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

class*args, **kwargs)[source]


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

  • 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
  • user_api_id (OneToOneField) – Telegram API info. Automatically retrieved from Telegram
class permabots.views.hooks.telegram_hook.TelegramHookView(**kwargs)[source]

Bases: rest_framework.views.APIView

View for Telegram webhook

post(request, hook_id)[source]
Process Telegram webhook.
  1. Serialize Telegram message
  2. Get an enabled Telegram bot

3. Create Update 5. Delay processing to a task 6. Response provider


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

class*args, **kwargs)[source]


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

  • 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:
  1. Get an enabled Kik bot
  2. Verify Kik signature
  3. Serialize each message
  4. For each message create KikMessage and KikUser
  5. Delay each message processing to a task
  6. 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.


Bots integrations can be enable/disable whenever to avoid processing

class*args, **kwargs)[source]


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 <> _.

  • 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. 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 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.


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


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 }}.

  • 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


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.


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.

  • 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

  • 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
  • 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.

  1. 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 <> _.
  2. Process request (if required)

  3. Generates response. Text and Keyboard

  4. Prepare target_state and context for updating chat&state info

  • 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.

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.

  • 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.{{key}}
  • response_id (OneToOneField) – Template the hook uses to generate the response
  • enabled (BooleanField) – Enable/disable hook
process(bot, data)[source]

Notification hook processing generating a response.

  • bot – Bot receiving the hook
  • data – JSON data from hook POST


class permabots.views.hooks.permabots_hook.PermabotsHookView(**kwargs)[source]

Bases: rest_framework.views.APIView

View for Notification Hooks.

post(request, key)[source]
Process notitication hooks:
  1. Obtain Hook
  2. Check Auth
  3. Delay processing to a task
  4. Respond requester