digitalguide 0.0.531

A Python Library to write digital guides for telegram

Digital Guides

A Python library for building interactive, state-machine-driven conversational guides on WhatsApp (via the WhatsApp Cloud API).

Overview

Digital Guides lets you define guided experiences as JSON — each state contains a list of handlers that match incoming messages and a list of actions that are sent in response. The library handles webhook parsing, pattern matching, message sending, and persistence so you can focus on the conversation flow.

Installation

pip install digitalguide

With MongoDB persistence and WhatsApp client support:

pip install "digitalguide[full]"

With image processing (PIL) and S3 storage:

pip install "digitalguide[full]" boto3 Pillow

Configuration

Create a config.ini file in your working directory:

[bot]
bot_name = my_bot_name   # used as the MongoDB database alias

[space]
space_name = my-s3-bucket
space_region = fra1
space_endpoint = https://fra1.digitaloceanspaces.com

Set S3/DigitalOcean Spaces credentials as environment variables:

export SPACES_KEY=your_access_key
export SPACES_SECRET=your_secret_key

Quick Start

1. Define states and actions as JSON

handlers_json = [
    {
        "handler": "MessageHandler",
        "filter": "regex",
        "regex": "WEITER_PATTERN",   # matches "weiter", "next", "ok", etc.
        "action": "welcome_action"
    },
    {
        "handler": "MessageHandler",
        "filter": "text",
        "action": "fallback_action"
    }
]

actions_json = [
    {"type": "message", "text": "Willkommen, {profile_name}!"},
    {"type": "message", "text": "Schreib etwas, um fortzufahren."},
    {"type": "return", "state": "next_state"}
]

2. Build handlers and actions

from digitalguide.generateStates import read_state
from digitalguide.generateActions import Action

handlers = read_state(handlers_json)
action = Action(actions_json)

3. Process an incoming webhook

from digitalguide.WhatsAppUpdate import WhatsAppUpdate

# `payload` is the raw dict from the WhatsApp webhook POST body
update = WhatsAppUpdate(payload)

context = {"state": "start"}

for handler in handlers:
    if handler.check_update(update):
        new_state = handler.callback(client, update, context, r)
        break

client is a heyoo WhatsApp instance. r is a Redis client used to track in-flight messages.

Action Types

Type	Description
message	Send a text message. Supports reply_buttons and interactive list via button + section_title + rows.
photo	Send an image by url or media id.
video	Send a video by url.
audio / voice	Send audio by url or media id.
sticker	Send a sticker by url.
carousel	Send a card carousel with text and cards.
venue	Send a location pin with title, address, latitude, longitude.
poll	Send a text poll with question and options list.
function	Call a special action function by func (module:function_name) with extra keyword arguments.
return	Transition to a new state. Must be the last item; returns state string to the caller.

Message placeholders

Inside text fields you can use:

• {profile_name} — the user's WhatsApp display name
• {echo} — the user's last message text
• {any_context_key} — any value stored in the context dict

Handler Types

MessageHandler

Matches incoming messages. Supported filter values:

Filter	Matches
regex	A named pattern (e.g. JA_PATTERN) or a custom regex string
text	Any text message
photo	Any image message
voice	Any audio/voice message

Named patterns available: EMOJI_PATTERN, JA_PATTERN, NEIN_PATTERN, WEITER_PATTERN, ZURUECK_PATTERN, WOHIN_PATTERN, JAHRESZAHL_PATTERN, KOMMAZAHL_PATTERN, DATENSCHUTZ_PATTERN.

CommandHandler

Matches a specific command string (e.g. /start):

{"handler": "CommandHandler", "command": "start", "action": "start_action"}

TypeHandler

Matches by update type. Currently supports "Update".

Special Actions

Register additional action functions by passing an action_functions dict to Action:

from digitalguide.special_actions import contextActions, writeActions

action_functions = {
    **contextActions.whatsapp_action_functions,
    **writeActions.whatsapp_action_functions,
}

action = Action(actions_json, action_functions=action_functions)

Or reference them directly in JSON with module:function syntax:

{"type": "function", "func": "contextActions:save_text_to_context", "key": "user_answer"}

Available modules:

• contextActions — save values to the session context
• writeActions — persist user-sent media (photo, voice, video, document) to S3
• imageActions — image overlay and GIF generation
• listenfrageActions — listening/survey question tracking
• schaetzfragenActions — year/decimal estimation questions with feedback

Data Persistence

When [full] dependencies are installed and MongoDB is connected, the library automatically persists:

• WhatsAppUser — user profile name and WhatsApp ID (created on first interaction)
• WhatsAppInteraction — every incoming message with its state and timestamp
• WhatsAppUserContextState — per-user session context and current state

Connect MongoDB before processing updates:

import mongoengine
mongoengine.register_connection(alias="my_bot_name", name="my_bot_name", host="mongodb://localhost")

Running Tests

pip install "digitalguide[test]"
pytest

License

MIT