API v2

Useful in cl-telegram-bot2/generics:process-state generic-function methods in case if state has additional handler stored in the slot and this slot can be either state or action or a list of actions and states.

This function is recursive, because processing of an action could return another action and we should call FUNC until a new state or NIL will be returned.

Makes bot sleep given number of seconds before processing next workflow action.

Cancels code execution delayed by delay macro.

Creates an object of class sync-delay.

This macro allows to call BODY with given delay.

During the body call current bot's telegram token will be available and you can send messages.

Retruned value (signature) can be used to cancel delayed code using call to cancel-delayed-execution.

Delete all messages created in the current current state.

Shown on the button to cancel a payment. If this button pushed, then on-cancel callback will be called and may return another state.

Additional commands to be available while waiting for the payment.

Called when user pushes the "Cancel" button. If not given then "back" action is returned.

Called when user finished the payment. If not given then "back" action is returned.

Showed on a button needed to be pushed to pay an invoice.

Type of prices arguments for send-invoice class.

(SOFT-LIST-OF HASH-TABLE)

A text to be shown on the "cancel" button.

State or action to be returned after the user pushed the "cancel" button.

State or action to be returned after the successful payment.

A text to be shown on the "pay" button.

A text to be shown in the message shown just to hide the reply keyboard.

Options object of type CL-TELEGRAM-BOT2/API:LINK-PREVIEW-OPTIONS to control if Telegram client should show a preview for some link from the message. Can be a symbol bound to a callable of one positional argument - action itself + keyword arguments :text, :parse-mode and :reply-markup. Shortcut :disable can be used instead of an object.

Supported values are: "Markdown", "MarkdownV2" or "HTML". Read more about formatting options in the Telegram documentaion: https://core.telegram.org/bots/api#formatting-options

If given, then only listed updates will be received by the bot. Or you might pass ADDITIONAL-ALLOWED-UPDATES argument to get some update types additionally to default types. According to TG API documentation, these update types aren't received by default: chat_member, message_reaction, and message_reaction_count.

This slot will be filled with cl-telegram-bot/user:user object on first access using a call to cl-telegram-bot/user:get-me function.

When debug mode is T, then interactive debugger will be called on each error.

HTTPS file-endpoint

Update id

Command processing code will use this cache to update commands list on the server when a new method for cl-telegram-bot/entities/command:on-command generic-function is defined.

This slot is for internal use.

Bot token given by BotFather

When debug mode is T, then interactive debugger will be called on each error.

HTTPS file-endpoint

Update id

Command processing code will use this cache to update commands list on the server when a new method for cl-telegram-bot/entities/command:on-command generic-function is defined.

This slot is for internal use.

Bot token given by BotFather

Returns a list of strings suitable to pass as ALLOWED-UPDATES argument to the bot constructor.

Use this macro to define a class of your Telegram bot.

Each bot has a state machine inside. The simplest bot has only one state:

(defbot test-bot ()
  ()
  (:initial-state
   (state (send-text "Hello world!"))))

This bot will green each who activates it.

To learn more about bot states and actions see States and Actions section.

Representation of callback handlers to be triggered on given callback data.

Returns state's slots or groups of slots as a list.

Renders a map item for a given handler.

It should use render-mapslot-value-with-link or render-mapslot-value functions for proper rendering of PlantUML.

Renders a map with a list of handlers for some event.

Returns a name for a state slot for such objects as callbacks or commands.

Renders object as an entity on PlantUML diagram.

Returns a state with given ID.

Works only during PlantUML diagram rendering.

Returns an alias of obj to be used in PlantUML diagram as a reference.

Call this function after you've finished rendering of the PlantUML object.

Executes block of code after the PlantUML entity with obj-id alias has been rendered. Useful for ensuring that both objects are known to the PlantUML renderer when rendering a link between objects.

Pre-checkout-query object will be passed as this single arguement and function should return a boolean. When the function return True, user may proceed to the payment.

Pre-checkout queries are not bound the the chat, so current-chat and current-state are not available during processing. This is why methods of this generic function should be defined on bot class.

You can use CL-TELEGRAM-BOT2/API:PRE-CHECKOUT-QUERY-INVOICE-PAYLOAD function to extract payload from the query and find associated invoice.

This method is called when some state exits and returns a result using cl-telegram-bot2/term/back:back function.

This method is called when chat actor's state is changed to a given STATE.

Such hook can be used to send some prompt to the user.

This method is called when chat actor's state is returned from a given STATE back to the previous state.

The method is called only when state is removed from the stack. When a new state is added to the stack, this method will not be called for a previous state.

Such hook can be used to hide a keyboard or to delete temporary messages.

This method is called by when processing a single update. It is called multiple times on different parts of an update. Whole pipeline looks like that:

For each update we call:

process-update(bot, update)
new_state = process-state(bot, current_state, update)

This generic-function will be called inside an actor.

Default method resposible for extracting the current state from the stack and calling process-state generic-function to get a new state.

High level API for implementing Telegram bots.

Use this function when you manually call some Telegram API methods from cl-telegram-bot2/api package. Otherwise these messages will not be deleted when you return back from one state to another.

Returns as the first value a list of messages created by reply function called during BODY execution. Values returned by the BODY code are returned as the second, third and following arguments.

Also, messages are collected when these actions are called:

• cl-telegram-bot2/actions/send-text:send-text (1 2)

• cl-telegram-bot2/actions/send-photo:send-photo (1 2)

Extracts callback query data from the UPDATE object.

If "quiz" is passed, the user will be allowed to create only polls in the quiz mode. If "regular" is passed, only regular polls will be allowed. Otherwise, the user will be allowed to create a poll of any type.

API: https://core.telegram.org/bots/api#keyboardbuttonpolltype

Makes a call-callback (1 2) button from a (title . data) cons.

Returns object of CL-TELEGRAM-BOT2/API:INLINE-KEYBOARD-MARKUP class.

API docs: https://core.telegram.org/bots/api#replykeyboardmarkup

Returns object of CL-TELEGRAM-BOT2/API:REPLY-KEYBOARD-MARKUP class.

API docs: https://core.telegram.org/bots/api#replykeyboardmarkup

API docs: https://core.telegram.org/bots/api#chatadministratorrights

(MEMBER :IS-ANONYMOUS :CAN-MANAGE-CHAT :CAN-DELETE-MESSAGES
        :CAN-MANAGE-VIDEO-CHATS :CAN-RESTRICT-MEMBERS :CAN-PROMOTE-MEMBERS
        :CAN-CHANGE-INFO :CAN-INVITE-USERS :CAN-POST-STORIES :CAN-EDIT-STORIES
        :CAN-DELETE-STORIES :CAN-POST-MESSAGES :CAN-EDIT-MESSAGES
        :CAN-PIN-MESSAGES :CAN-MANAGE-TOPICS)

(SOFT-LIST-OF CHAT-ADMINISTRATION-PERMISSION)

Should return T if OBJ match to the matcher. The simples matcher compares two strings.

Invokes retry restart if it is available or signals control-error.

If some state class processes update and don't call CALL-NEXT-METHOD, then it have to call this function to register received message id.

If you don't do this, then received messages deletion will not work for this state.

Usually all sent messages are captured automatically during update processing.

However, when messages are sent and deleted in a one workflow-blocks list, delete-messages action will not see these sent messages. Thus we have to call this function explicitly inside send-text action.

Use this macro to capture messages end during process-state generic-function handling in case if your state inherits from base-state but does not call CALL-NEXT-METHOD.

Start processing new updates from the Telegram API.

Pass bot instance as the first argument and maybe some other optional arguments.

If DEBUG argument is T, then bot will ignore updates which it can't to process without errors. Otherwise, an interactive debugger will popup.

Result of these handlers is ignored, but they can be used for side-effects.

Generic-function cl-telegram-bot2/generics:on-state-deletion will be called on these handlers.

Validates if argument is valid for passing as :ON-DELETION argument to the state constructor.

It also normalizes an argument and return it as a list of workflow blocks.

Type of ON-CALLBACK-QUERY argument of the state class.

(SOFT-LIST-OF CALLBACK)

A command description like "/start" or "/help".

An fbound symbol of two arguments (command-argument update-obj) or a workflow object to return from process-state generic-function.

A command name like "/start" or "/help".

This type of command is available only in the state where it is defined.

This command will be available during in all bot states.

(OR SYMBOL WORKFLOW-BLOCK WORKFLOW-BLOCKS)

Delete message with the keyboard and all warning messages when the choice was made or a new state was added to the stack.

Delete usual user messages which he might send by a mistake.

If KEYBOARD argument was not supplied, then existing reply keyboard will stay on screen.

Pass a REPLY-KEYBOARD-MARKUP object as KEYBOARD argument, to show a new keyboard. Pass a NIL as KEYBOARD argument, to hide current reply keyboard keyboard.

On success could be an fbound symbol which function returns a list of workflow blocks or a list of workflow blocks.

When T then value from slot result will be passed to the cl-telegram-bot2/generics:on-result generic-function called on the state where we returned back to. Otherwise cl-telegram-bot2/generics:on-state-activation generic-function will be called on a new current state.

Replaces current state with a new one.

Generic-function cl-telegram-bot2/generics:on-state-deletion will be called on the old state.

A function of on argument - current state. If predicate returns T, then state will be replaced, otherwise it will be kept on stack. By default, any state is replaced.

(OR CL-TELEGRAM-BOT2/API:REPLY-KEYBOARD-MARKUP
    CL-TELEGRAM-BOT2/API:REPLY-KEYBOARD-REMOVE
    CL-TELEGRAM-BOT2/API:INLINE-KEYBOARD-MARKUP
    CL-TELEGRAM-BOT2/API:FORCE-REPLY)

Does a general deep-copy on the given object and sub-pieces. Returns atoms, numbers and chars. Runs copy-tree on lists, and copy-seq on other sequences. Runs copy-structure on pathnames, hash tables and other structure-objects

If value is a fbound SYMBOL, then calls as a function and then returns a result.

If value is a fbound SYMBOL, then calls as a function with given ARG or without it depending on function arity.

This type denotes symbols bound to the functions. Such symbol could be funcalled.

(AND SYMBOL (SATISFIES FBOUNDP))

This variable holds an alist associating special variable symbols to forms to evaluate.

State processing might be done by different threads that is why you might want to keep some context around.

Don't modify this variable, just cons onto it. Preceeding values will take a priority.

(AND SYMBOL (SATISFIES FBOUNDP))

(OR FUNCALLABLE-SYMBOL BASE-STATE ACTION BACK)

(SOFT-LIST-OF WORKFLOW-BLOCK)