Digital Guides
A Python library for building interactive, state-machine-driven conversational guides on WhatsApp (via the WhatsApp Cloud API and pywa).
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 pywa (WhatsApp Cloud API client):
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
The library uses pywa for WhatsApp Cloud API integration. Register a handler on your PyWa client and dispatch the incoming update through your state's handler list:
from pywa import WhatsApp
from pywa.types import Message, CallbackButton, CallbackSelection
import redis
wa = WhatsApp(
phone_id="YOUR_PHONE_NUMBER_ID",
token="YOUR_ACCESS_TOKEN",
server=None, # e.g. a Flask or FastAPI app
callback_url="https://your-domain.com/webhook",
verify_token="YOUR_VERIFY_TOKEN",
)
r = redis.Redis() # Redis client used to track in-flight messages
def handle_update(client: WhatsApp, update: Message | CallbackButton | CallbackSelection):
context = {"state": "start"} # load from your persistence layer
for handler in handlers:
if handler.check_update(update):
new_state = handler.callback(client, update, context, r)
break
update is a pywa.types.Message, CallbackButton, or CallbackSelection object delivered by pywa's webhook dispatcher. 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 thecontextdict
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 contextwriteActions— persist user-sent media (photo, voice, video, document) to S3imageActions— image overlay and GIF generationlistenfrageActions— listening/survey question trackingschaetzfragenActions— 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 timestampWhatsAppUserContextState— 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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file digitalguide-0.0.551.tar.gz.
File metadata
- Download URL: digitalguide-0.0.551.tar.gz
- Upload date:
- Size: 17.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
912da25b7d3355966a5b9fc9817f0744a3db13660acca37f1e05f3c75606ecf4
|
|
| MD5 |
5ab381ffc82df242a07f2a4a08f90ef7
|
|
| BLAKE2b-256 |
bd7d764cd25fc4b2c844c36e871817042decb2285bd24db651ba1b3493554fde
|
File details
Details for the file digitalguide-0.0.551-py3-none-any.whl.
File metadata
- Download URL: digitalguide-0.0.551-py3-none-any.whl
- Upload date:
- Size: 16.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6b2899e5c06c04b07b2a2dd107e07fe26937f58b35f8d29a477a8ad6ef70467c
|
|
| MD5 |
ca5b6289ee9c563caeff514525fa15f5
|
|
| BLAKE2b-256 |
1a04b13f346b9f3a8f7b66dd2fa944abe09ce5c836fefdd34d614e4e4edeb7c8
|
