cl-telegram-bot - Telegram Bot API

CL-TELEGRAM-BOT ASDF System Details

Installation

You can install this library from Quicklisp, but you want to receive updates quickly, then install it from Ultralisp.org:

(ql-dist:install-dist "http://dist.ultralisp.org/"
                      :prompt nil)
(ql:quickload :cl-telegram-bot)

Quickstart

The system uses CLOS to add new methods to process incoming messages. To create a simple bot, all you need is to define on-message method.

If you want to match on a particular command, like /help or /make-me-happy 7 times, then you better to define a on-command method.

During messages processing, function (reply "some text") is available, which will send given text into the right chat. Also, there is send-message and other function exists which allow your bot to post messages, images and other media into the any chat.

Here is example of a simple bot which reacts on the text message and /echo command:

CL-USER> (defpackage the-bot (:use :cl :cl-telegram-bot))
#<Package "THE-BOT">
CL-USER> (in-package the-bot)
#<Package "THE-BOT">
THE-BOT> (defbot echo-bot)
MAKE-ECHO-BOT
THE-BOT> (defmethod on-message ((bot echo-bot)
                                text)
           (reply text))
#<STANDARD-METHOD ON-MESSAGE (ECHO-BOT T)>
THE-BOT> (defmethod on-command ((bot echo-bot)
                                (command (eql :help))
                                text)
           (declare (ignorable text))
           (reply "Just send me any text and I'll reply with the same text."))
#<STANDARD-METHOD ON-COMMAND (ECHO-BOT (EQL :HELP) T)>
THE-BOT> (defmethod on-command ((bot echo-bot)
                                (command (eql :start))
                                text)
           (declare (ignorable text))
           (reply "Welcome Lisper! Have a fun, playing with cl-telegram-bot!"))
#<STANDARD-METHOD ON-COMMAND (ECHO-BOT (EQL :START) T)>

Now, stop for the minute, open your Telegram client, and create a new bot using the BotFather bot:

When you've got token, return to the REPL and start our bot:

THE-BOT> (start-processing (make-echo-bot "5205125**********************************")
                           :debug t)
 <INFO> [08:31:09] cl-telegram-bot core.lisp (start-processing) - Starting thread to process updates for CL-TELEGRAM-BOT/CORE::BOT: #<ECHO-BOT id=0> 
#<PROCESS telegram-bot(33) [Reset] #x30200709246D>
THE-BOT>

This will start a new thread for processing incoming messages.

Now, find your bot in the Telegram client:

And start communicating with him:

API

CL-TELEGRAM-BOT/BOT

package
cl-telegram-bot/bot

Classes

BOT
class
bot

Readers

reader
api-uri
(:API-URI = "https://api.telegram.org/")
reader
bot-info
(= nil)

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.

reader
debug-mode
(:debug-mode = nil)

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

reader
file-endpoint
(:file-endpoint = nil)

HTTPS file-endpoint

reader
get-endpoint
(:endpoint)

HTTPS endpoint

reader
get-last-update-id
(= 0)

Update id

reader
sent-commands-cache
(= nil)

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.

reader
token
(:token = nil)

Bot token given by BotFather

Accessors

accessor
api-uri
(:API-URI = "https://api.telegram.org/")
accessor
debug-mode
(:debug-mode = nil)

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

accessor
file-endpoint
(:file-endpoint = nil)

HTTPS file-endpoint

accessor
get-last-update-id
(= 0)

Update id

accessor
sent-commands-cache
(= nil)

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.

accessor
token
(:token = nil)

Bot token given by BotFather

Macros

macro
defbot
name &optional slots options

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

CL-TELEGRAM-BOT/CALLBACK

package
cl-telegram-bot/callback

Classes

CALLBACK
class
callback

Readers

reader
callback-data
(:data)
reader
callback-id
(:id)
reader
callback-message
(:message)

Generics

generic-function
make-callback
bot callback-data

Called when user clicks callback button. Should return an instance of callback class.

Application may override this method to return objects of different callback classes depending on callback-data string. This way it mab be easier to define more specific methods for on-callback generic-function.

generic-function
on-callback
bot callback

Called when user clicks callback button. Second argument is an object of CALLBACK type.

CL-TELEGRAM-BOT/CHAT

package
cl-telegram-bot/chat

Classes

CHANNEL
class
channel
CHAT
class
chat

Readers

reader
get-chat-id
(:id)
reader
get-has-protected-content
(:has-protected-content)
reader
get-message-auto-delete-time
(:message-auto-delete-time)
reader
get-raw-data
(:raw-data)
reader
get-username
(:username)
GROUP
class
group
PRIVATE-CHAT
class
private-chat

Readers

reader
get-bio
(:bio)
reader
get-first-name
(:first-name)
reader
get-has-private-forwards
(:has-private-forwards)
reader
get-last-name
(:last-name)
SUPER-GROUP
class
super-group

Readers

reader
get-can-set-sticker-set
(:can-set-sticker-set)
reader
get-join-by-request
(:join-by-request)
reader
get-join-to-send-messages
(:join-to-send-messages)
reader
get-slow-mode-delay
(:slow-mode-delay)
reader
get-sticker-set-name
(:sticker-set-name)

Generics

generic-function
get-chat
obj

Returns a chat associated with object.

Object could be a message, update, callback, etc. Should return an object of chat class or NIL. Some types of updates aren't bound to a chat. In this case a method should return NIL.

Functions

function
delete-chat-photo
bot-var1 chat

https://core.telegram.org/bots/api#deletechatphoto

function
export-chat-invite-link
bot-var1 chat

https://core.telegram.org/bots/api#exportchatinvitelink

function
get-chat-administrators
bot-var1 chat

https://core.telegram.org/bots/api#getchatadministrators

function
get-chat-by-id
bot-var1 chat-id

https://core.telegram.org/bots/api#getchat

function
get-chat-member
bot-var1 chat user-id

https://core.telegram.org/bots/api#getchatmember

function
get-chat-members-count
bot-var1 chat

https://core.telegram.org/bots/api#getchatmemberscount

function
kick-chat-member
bot-var1 chat user-id until-date

https://core.telegram.org/bots/api#kickchatmember

function
leave-chat
bot-var1 chat

https://core.telegram.org/bots/api#leavechat

function
pin-chat-message
bot-var1 chat message-id disable-notification

https://core.telegram.org/bots/api#pinchatmessage

function
promote-chat-member
bot-var1 chat user-id can-change-info can-post-messages can-edit-messages can-delete-messages can-invite-users can-restrict-members can-pin-messages can-promote-members

https://core.telegram.org/bots/api#promotechatmember

function
restrict-chat-member
bot-var1 chat user-id until-date can-send-messages can-send-media-messages can-send-other-messages can-add-web-page-previews

https://core.telegram.org/bots/api#restrictchatmember

function
send-chat-action
bot-var1 chat action

https://core.telegram.org/bots/api#sendchataction

function
set-chat-description
bot-var1 chat description

https://core.telegram.org/bots/api#setchatdescription

function
set-chat-photo
bot-var1 chat photo

https://core.telegram.org/bots/api#setchatphoto

function
set-chat-title
bot-var1 chat title

https://core.telegram.org/bots/api#setchattitle

function
unban-chat-member
bot-var1 chat user-id

https://core.telegram.org/bots/api#unbanchatmember

function
unpin-chat-message
bot-var1 chat

https://core.telegram.org/bots/api#unpinchatmessage

CL-TELEGRAM-BOT/CORE

package
cl-telegram-bot/core

Classes

REPLY
class
reply

Generics

generic-function
on-command
bot command rest-text

This method will be called for each command. First argument is a keyword. If user input was /save_note, then first argument will be :save-note.

By default, logs call and does nothing.

generic-function
on-message
bot text

This method gets called with raw text from the message. By default it does nothing.

Functions

function
reply
text &rest args &key parse-mode disable-web-page-preview disable-notification reply-to-message-id reply-markup (immediately \*reply-immediately\*)

Works like a send-message, but only when an incoming message is processed. Automatically sends reply to a chat from where current message came from.

function
start-processing
BOT &KEY DEBUG (DELAY-BETWEEN-RETRIES 10) (THREAD-NAME "telegram-bot")
function
stop-processing
bot

Macros

macro
defbot
name &optional slots options

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

CL-TELEGRAM-BOT/ENTITIES/COMMAND

package
cl-telegram-bot/entities/command

Classes

BOT-COMMAND
class
bot-command

Readers

reader
bot-username
(:bot-username)
reader
get-command
(:command)
reader
get-rest-text
(:rest-text)

Generics

generic-function
on-command
bot command rest-text

This method will be called for each command. First argument is a keyword. If user input was /save_note, then first argument will be :save-note.

By default, logs call and does nothing.

CL-TELEGRAM-BOT/ENTITIES/GENERIC

package
cl-telegram-bot/entities/generic

Generics

generic-function
make-entity-internal
entity-type payload data

Extendable protocol to support entities of different kinds. First argument is a keyword, denoting a type of the entity. Payload is an object of type `message'. And data is a plist with data, describing the entity.

Functions

function
make-entity
payload data

CL-TELEGRAM-BOT/ENVELOPE

package
cl-telegram-bot/envelope

Classes

CHANNEL-POST
class
channel-post

This container wraps cl-telegram-bot/message:message when somebody sends a message to a channel.

EDITED-CHANNEL-POST
class
edited-channel-post

This container wraps cl-telegram-bot/message:message when somebody edits a message in a channel.

EDITED-MESSAGE
class
edited-message

This container wraps cl-telegram-bot/message:message when user edits a message.

ENVELOPE
class
envelope

This is the container for a message. From the type of container we can understand if this message was sent to a channel or maybe edited, etc.

Readers

reader
wrapped-message
(:message)

Functions

function
channel-post-p

Returns T if current message was posted to a channel.

function
edited-message-p

Returns T if current message is an update for existing message in the channel of group chat.

CL-TELEGRAM-BOT/INLINE-KEYBOARD

package
cl-telegram-bot/inline-keyboard

Classes

CALLBACK-BUTTON
class
callback-button

Readers

reader
callback-button-data
(:data)
INLINE-KEYBOARD-BUTTON
class
inline-keyboard-button

Base class for all inline keyboard buttons.

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

Readers

reader
button-text
(:text)
INLINE-KEYBOARD
class
inline-keyboard

Represents an inline keyboard as specified in API https://core.telegram.org/bots/api#inlinekeyboardmarkup.

Readers

reader
keyboard-rows
(:rows = nil)
URL-BUTTON
class
url-button

Readers

reader
button-url
(:data)

Functions

function
answer-callback-query
bot callback &key text show-alert url

https://core.telegram.org/bots/api#answercallbackquery

function
callback-button
text data

Creates a button which will call a callback.

function
inline-keyboard
rows

Returns an inline keyboard which can be passed to cl-telegram-bot/response:reply (1 2) as REPLY-MARKUP argument.

Each row should be a list of inline-keyboard-button objects or a single object of this class. In latter case, such row will have only one button.

function
url-button
text url

Creates a button which will open an url.

CL-TELEGRAM-BOT/MARKUP

package
cl-telegram-bot/markup

Generics

generic-function
to-markup
obj

Transforms object into markup of Telegram API.

Methods of this class should return a hash-table, representing OBJ in terms of Telegram API.

CL-TELEGRAM-BOT/MESSAGE

package
cl-telegram-bot/message

Classes

ANIMATION-MESSAGE
class
animation-message
ANIMATION
class
animation
AUDIO-MESSAGE
class
audio-message
AUDIO
class
audio

Readers

reader
get-performer
(:performer)

Performer of the audio as defined by sender or by audio tags.

reader
get-title
(:title)

Title of the audio as defined by sender or by audio tags.

DOCUMENT-MESSAGE
class
document-message
DOCUMENT
class
document
FILE-MESSAGE
class
file-message

Readers

reader
get-file
(:file)
FILE
class
file

Readers

reader
get-file-id
(:file-id)

Identifier for this file, which can be used to download or reuse the file.

reader
get-file-name
(:file-name)

Original filename as defined by sender.

reader
get-file-size
(:file-size)

File size in bytes.

reader
get-file-unique-id
(:file-unique-id)

Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.

reader
get-mime-type
(:mime-type)

MIME type of the file as defined by sender.

MESSAGE
class
message

Readers

reader
get-caption
(:caption)

Caption for the animation, audio, document, photo, video or voice.

reader
get-chat
(:chat)
reader
get-entities
(:entities = nil)
reader
get-forward-from
(:forward-from)

For forwarded messages, sender of the original message.

reader
get-forward-from-chat
(:forward-from-chat)

For messages forwarded from channels or from anonymous administrators, information about the original sender chat.

reader
get-forward-sender-name
(:forward-sender-name)

For forwarded messages, sender of the original message.

reader
get-message-id
(:id)
reader
get-raw-data
(:raw-data)
reader
get-sender-chat
(:sender-chat)

Sender of the message, sent on behalf of a chat. For example, the channel itself for channel posts, the supergroup itself for messages from anonymous group administrators, the linked channel for messages automatically forwarded to the discussion group.

reader
get-text
(:text)
PHOTO-MESSAGE
class
photo-message

Readers

reader
get-photo-options
(:photo-options)
PHOTO
class
photo
REPLY
class
reply

Readers

reader
get-reply-to-message
(:reply-to-message)
SPATIAL
class
spatial

Readers

reader
get-height
(:height)

File height as defined by sender.

reader
get-width
(:width)

File width as defined by sender.

STICKER-MESSAGE
class
sticker-message
STICKER
class
sticker

Readers

reader
get-emoji
(:emoji)

Emoji associated with the sticker

reader
get-is-animated
(:is-animated)

True if the sticker is animated.

reader
get-is-video
(:is-video)

True if the sticker is a video sticker.

reader
get-set-name
(:set-name)

Name of the sticker set to which the sticker belongs.

TEMPORAL
class
temporal

Readers

reader
get-duration
(:duration)

Duration of the file in seconds as defined by sender.

UNISPATIAL
class
unispatial

Readers

reader
get-length
(:length)
VIDEO-MESSAGE
class
video-message
VIDEO-NOTE-MESSAGE
class
video-note-message
VIDEO-NOTE
class
video-note
VIDEO
class
video
VOICE-MESSAGE
class
voice-message
VOICE
class
voice

Generics

generic-function
on-message
bot text

This method gets called with raw text from the message. By default it does nothing.

generic-function
send-animation
bot chat animation &rest options &key caption parse-mode caption-entities duration width height thumb disable-notification protect-content reply-to-message-id allow-sending-without-reply reply-markup

Sends animation to a chat.

generic-function
send-audio
bot chat audio &rest options &key caption parse-mode caption-entities duration performer title thumb disable-notification protect-content reply-to-message-id allow-sending-without-reply reply-markup
generic-function
send-document
bot chat document &rest options &key caption parse-mode caption-entities disable-content-type-detection thumb disable-notification protect-content reply-to-message-id allow-sending-without-reply reply-markup
generic-function
send-photo
bot chat photo &rest options &key caption parse-mode caption-entities disable-notification protect-content reply-to-message-id allow-sending-without-reply reply-markup
generic-function
send-sticker
bot chat sticker &rest options &key disable-notification protect-content reply-to-message-id allow-sending-without-reply reply-markup

A function to send sticker.

generic-function
send-video
bot chat video &rest options &key caption parse-mode caption-entities duration width height thumb disable-notification protect-content reply-to-message-id allow-sending-without-reply reply-markup
generic-function
send-video-note
bot chat video-note &rest options &key caption parse-mode caption-entities duration length thumb disable-notification protect-content reply-to-message-id allow-sending-without-reply reply-markup
generic-function
send-voice
bot chat voice &rest options &key caption parse-mode caption-entities duration disable-notification protect-content reply-to-message-id allow-sending-without-reply reply-markup

Functions

function
delete-message
bot chat message

https://core.telegram.org/bots/api#deletemessage

function
forward-message
bot chat from-chat message &key disable-notification

https://core.telegram.org/bots/api#forwardmessage

function
get-current-bot

Returns a bot to which message was addressed.

function
get-current-chat

Returns a chat where currently processing message was received.

function
get-current-message

Returns currently processed message.

function
make-message
data
function
send-message
bot chat text &rest options &key parse-mode disable-web-page-preview disable-notification reply-to-message-id (autosplit nil) reply-markup

https://core.telegram.org/bots/api#sendmessage

CL-TELEGRAM-BOT/NETWORK

package
cl-telegram-bot/network

Classes

REQUEST-ERROR
condition
request-error

Readers

reader
what
(:what)

Functions

function
make-request
bot name &rest options &key (streamp nil) (timeout 3) &allow-other-keys

Perform HTTP request to 'name API method with 'options JSON-encoded object.

function
set-proxy
proxy

CL-TELEGRAM-BOT/PAYMENTS

package
cl-telegram-bot/payments

Generics

generic-function
on-pre-checkout-query
bot query

Called when user enters payment method credentials and hit "Pay" button. Second argument is an object of PRE-CHECKOUT-QUERY type.

A method should respond with with a call to answer-pre-checkout-query function.

Functions

function
answer-pre-checkout-query
bot pre-checkout-query &key error-message

If ERROR-MESSAGE argument was given, then response considered is not OK and transaction will be cancelled.

https://core.telegram.org/bots/api#answerprecheckoutquery

function
answer-shipping-query
b shipping-query-id ok &key shipping-options error-message

https://core.telegram.org/bots/api#answershippingquery

function
send-invoice
b chat-id title description payload provider-token start-parameter currency prices &key photo-url photo-size photo-width photo-height need-name need-phone-number need-email need-shipping-address is-flexible disable-notification reply-to-message-id reply-markup

https://core.telegram.org/bots/api#sendinvoice

CL-TELEGRAM-BOT/PIPELINE

package
cl-telegram-bot/pipeline

Generics

generic-function
process
bot object

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) process(update.payload) For each entity in payload: process(entity)

CL-TELEGRAM-BOT/RESPONSE

package
cl-telegram-bot/response

Classes

ALERT
class
alert
NOTIFY
class
notify
OPEN-URL
class
open-url

Readers

reader
url-to-open
(:text)
REPLY
class
reply
RESPONSE-WITH-TEXT
class
response-with-text

Readers

reader
response-text
(:text)
RESPONSE
class
response

Readers

reader
rest-args
(:args)

Functions

function
alert
text

Works like a send-message, but only when an incoming message is processed. Automatically sends reply to a chat from where current message came from.

function
notify
text

Works like a send-message, but only when an incoming message is processed. Automatically sends reply to a chat from where current message came from.

function
open-url
url

Works like a send-message, but only when an incoming message is processed. Automatically sends reply to a chat from where current message came from.

function
reply
text &rest args &key parse-mode disable-web-page-preview disable-notification reply-to-message-id reply-markup (immediately \*reply-immediately\*)

Works like a send-message, but only when an incoming message is processed. Automatically sends reply to a chat from where current message came from.

CL-TELEGRAM-BOT/RESPONSE-PROCESSING

package
cl-telegram-bot/response-processing

Classes

INTERRUPT-PROCESSING
condition
interrupt-processing

Generics

generic-function
process-response
bot message response

Processes immediate responses of different types.

Functions

function
interrupt-processing

CL-TELEGRAM-BOT/UPDATE

package
cl-telegram-bot/update

Classes

UPDATE
class
update

Readers

reader
get-payload
(:payload)
reader
get-raw-data
(:raw-data)
reader
get-update-id
(:id)

Generics

generic-function
process-updates
bot

By default, this method starts an infinite loop and fetching new updates using long polling.

Functions

function
make-update
data

CL-TELEGRAM-BOT/USER

package
cl-telegram-bot/user

Classes

USER
class
user

Readers

reader
bot-p
(:is-bot)
reader
can-connect-to-business-p
(:can-connect-to-business = nil)
reader
can-join-groups-p
(:can-join-groups = nil)
reader
can-read-all-group-messages-p
(:can-read-all-group-messages = nil)
reader
first-name
(:first-name)
reader
is-premium
(:is-premium = nil)
reader
language-code
(:language-code = nil)
reader
last-name
(:last-name = nil)
reader
raw-data
(:raw-data)
reader
supports-inline-queries-p
(:supports-inline-queries = nil)
reader
user-id
(:id)
reader
username
(:username = nil)

Generics

generic-function
get-user-info
obj

Returns a user object related to the object.

If object is not bound to a user, then NIL should be returned.

Functions

function
get-me
bot

https://core.telegram.org/bots/api#getme

CL-TELEGRAM-BOT/UTILS

package
cl-telegram-bot/utils

Functions

function
api-response-to-plist
plist

Transforms a plist with keys like :|foo_bar| into a plist with keys like :foo-bar.

This can be useful to pass data into CL object contructors.

function
make-keyword
text
function
obfuscate
url
function
split-by-lines
text &key (max-size 4096) (trim-whitespaces-p t)

Credits