tbotworkflow

README

tbotworkflow - Telegram Bot Workflows

Use tbotworkflow to build interactive sequential and conditional workflows for your Telegram Bot to gather user input.

Features

• Build interactive Sequential and Conditional workflows for your Telegram Bot.
• No thirdparty library dependencies (except for Official Go Telegram Bot API).
• Does not require access to your Bot Token.

Limitations

• Currently supports only normal Reply Markup Keyboards. Inline keyboards not supported.

Installation

go get -u github.com/hbbtekademy/tbotworkflow

Examples

Sequential Workflow

Conditional Workflow

Optional Parameters

Documentation

Index

• type CancelButtonConfig
  • func NewCancelButtonConfig(buttonText string, buttonReply string) *CancelButtonConfig
• type TBotWorkflow
  • func NewWorkflow(name string, command string, rootStep *TBotWorkflowStep) TBotWorkflow
• type TBotWorkflowController
  • func NewWorkflowController(name string) *TBotWorkflowController
  • func (w *TBotWorkflowController) AddWorkflow(wf *TBotWorkflow)
  • func (w *TBotWorkflowController) DisableLogging()
  • func (w *TBotWorkflowController) EnableLogging(writer io.Writer)
  • func (w *TBotWorkflowController) Execute(msg *tgbotapi.Message, ...) (*UserInputs, bool)
  • func (w *TBotWorkflowController) SetLogger(logger *log.Logger)
  • func (w *TBotWorkflowController) SetMsgParseMode(parseMode string)
• type TBotWorkflowStep
  • func NewWorkflowStep(name string, key string, replyText string, kb *tgbotapi.ReplyKeyboardMarkup) TBotWorkflowStep
• type UserInputs

Types

type CancelButtonConfig

type CancelButtonConfig struct {
	// contains filtered or unexported fields
}

CancelButtonConfig will tell the workflow if a particular user input should be considered as a workflow cancel request.

func NewCancelButtonConfig

func NewCancelButtonConfig(buttonText string, buttonReply string) *CancelButtonConfig

NewCancelButtonConfig returns a pointer to cancel button config. buttonText: Tells the workflow step what is the cancel buttons text. E.g. "Reset", "Cancel", "Restart" etc. buttonReply: Tells the workflow step what reply should be sent to the user when the cancel button is pressed. When user presses the Cancel button, the workflow will exit with the "buttonReply" Text.

type TBotWorkflow

type TBotWorkflow struct {
	// Name of the workflow
	Name string
	// Command for which this workflow should be triggered
	Command string
	// The first step of the Workflow
	RootStep *TBotWorkflowStep
	// Cancel button config for this workflow. Can be overridden by the config set in the TBotWorkflowStep.
	CancelButtonConfig *CancelButtonConfig
}

TBotWorkflow is the workflow to be triggered for a particular Bot Command

func NewWorkflow

func NewWorkflow(name string, command string, rootStep *TBotWorkflowStep) TBotWorkflow

NewWorkflow returns a TBotWorkflow

type TBotWorkflowController

type TBotWorkflowController struct {
	// Name of the Workflow Controller.
	Name string

	// For logging useful information.
	// Logger is disabled by default but can be overriden/enabled/disabled
	// using the methods provided on the WorkflowController.
	Logger *log.Logger
	// Function to override the default Text sent to the users in case
	// this controller cannot handle the command sent by the user.
	WorkflowNotFoundReplyTextFunc func(msg *tgbotapi.Message) string
	// Global function to validate the user inputs.
	// ValidateInputFunc on TBotWorkflowStep takes priority over this function.
	ValidateInputFunc func(msg *tgbotapi.Message, kb *tgbotapi.ReplyKeyboardMarkup) (string, bool)
	// contains filtered or unexported fields
}

TBotWorkflowController controls all the workflows and their execution

func NewWorkflowController

func NewWorkflowController(name string) *TBotWorkflowController

NewWorkflowController returns a pointer to a new WorkflowController

func (*TBotWorkflowController) AddWorkflow

func (w *TBotWorkflowController) AddWorkflow(wf *TBotWorkflow)

AddWorkflow is used to add a single workflow to the controller.

func (*TBotWorkflowController) DisableLogging

func (w *TBotWorkflowController) DisableLogging()

DisableLogging can be used to disable the logger

func (*TBotWorkflowController) EnableLogging

func (w *TBotWorkflowController) EnableLogging(writer io.Writer)

EnableLogging can be used to enable logging to the required io writer

func (*TBotWorkflowController) Execute

func (w *TBotWorkflowController) Execute(msg *tgbotapi.Message,
	sendFunc func(c tgbotapi.Chattable) (tgbotapi.Message, error)) (*UserInputs, bool)

Execute runs one of the registered workflows given a Message from the user. At the end of the workflow, this method returns the user inputs captured at each step. bool = true means workflow has ended. UserInputs pointer will be "nil" till the workflow ends. This method takes the Message from the user and the Send function of the Telegram Bot API as inputs.

func (*TBotWorkflowController) SetLogger

func (w *TBotWorkflowController) SetLogger(logger *log.Logger)

SetLogger can be used to override the default logger

func (*TBotWorkflowController) SetMsgParseMode

func (w *TBotWorkflowController) SetMsgParseMode(parseMode string)

SetMsgParseMode can be used to set the Telegram message parseMode (HTML or MarkdownV2). Default value is HTML

type TBotWorkflowStep

type TBotWorkflowStep struct {
	// Name of the workflow step.
	Name string
	// Text that should be sent to the user at start of the step.
	ReplyText string
	// Key for the user input that will be available at the end of the workflow.
	Key string
	// Keyboard that should be presented to the user.
	// Set to nil to display the default text input keyboard.
	KB *tgbotapi.ReplyKeyboardMarkup
	// Next step to be executed after this step.
	// Set to nil for the last step.
	Next *TBotWorkflowStep
	// Function to be evaluated to determine the next step for conditional workflows.
	// If ConditionFunc is set, Step defined in "Next" will be ignored.
	ConditionFunc func(msg *tgbotapi.Message) string
	// A map of "ConditionFunc" outputs and the TBotWorkflowStep that should be executed for each of those outputs.
	ConditionalNext map[string]*TBotWorkflowStep
	// Function to generate the Text that should be sent to the user at start of the step.
	// If ReplyTextFunc is set, value defined in "ReplyText" is ignored.
	ReplyTextFunc func(ui *UserInputs) string
	// Function to validate the users input.
	// If the validation fails (function returns false), the string returned by this function is sent to the user.
	ValidateInputFunc func(msg *tgbotapi.Message, kb *tgbotapi.ReplyKeyboardMarkup) (string, bool)
	// Cancel button config for the step. Overrides the config set in the TBotWorkflow.
	CancelButtonConfig *CancelButtonConfig
}

TBotWorkflowStep is the baisc unit of the workflow. A workflow consists of a number of TBotWorkflowStep's chained together.

func NewWorkflowStep

func NewWorkflowStep(name string, key string, replyText string,
	kb *tgbotapi.ReplyKeyboardMarkup) TBotWorkflowStep

NewWorkflowStep returns a pointer to TBotWorkflowStep for given name, key, replyText and Telegram Reply Markup Keyboard. key is the "Key" in the UserInputs available at the end of the workflow. replyText is the text that should be sent to the user at start of the step.

type UserInputs

type UserInputs struct {
	// Telegram User ID
	UID int64
	// Telegram Command
	Command string
	// Data map to store the user inputs.
	// Map key is the "Key" defined in the TBotWorkflowStep
	// Map value is the Text entered by the user.
	Data map[string]string
}

UserInputs captures the user inputs for each step of the workflow