Telegram Custom Messages and Message Templates
In this guide:
- Intro
- Text messages
- Custom Keyboard
- Photo messages
- Audio messages
- Location messages
- Venue messages
- Sticker messages
- Contact messages
- Changing chat action
- Pause between messages
- Other attachments
- Sending multiple messages
- Handling errors
Intro
Telegram Template Message builder allows you to generate more complex messages for Telegram Messenger without writing JSON files manually.
To use it, just require telegramTemplate
function from Claudia Bot Builder:
const telegramTemplate = require('claudia-bot-builder').telegramTemplate;
telegramTemplate
exports an object that contains multiple classes that allows you to generate different types of structured messages for Telegram:
- Text messages (we need a template for this just in case you want to add custom keyboard to it)
- Photo
- Audio
- Location
- Venue
- ChatAction
It also allows you to make a pause before the next message.
More info about each type of structured messages can be found in the official documentation.
Text messages
If you simply want to answer with the text you can just return text. But in case you want to answer with text with a custom keyboard or Markdown support you can use Text method.
API
Text
(class) - Class that allows you to build text messages with custom keyboards and with Markdown support.
Arguments:
- text, string (required) - a simple text to send as a reply.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
disableMarkdown | No | No arguments | this for chaining |
Disables Markdown support, it's enabled by default |
addReplyKeyboard | No | keyboardArray (array, required, an array of keyboard keys), resizeKeyboard (boolean, optional, if the keyboard should be resizable), oneTimeKeyboard (boolean, optional, if the keyboard should be hidden after first usage) | this for chaining |
Telegram ReplyKeyboardMarkup, for more info visit official docs |
addInlineKeyboard | No | keyboardArray (array, required, an array of keyboard keys) | this for chaining |
Telegram InlineKeyboardMarkup, for more info visit official docs |
replyKeyboardHide | No | selective (boolean, optional, use this parameter if you want to hide keyboard for specific users only ) | this for chaining |
Telegram ReplyKeyboardHide, for more info visit official docs |
forceReply | No | selective (boolean, optional, use this parameter if you want to hide keyboard for specific users only ) | this for chaining |
Telegram ForceReply, for more info visit official docs |
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Text(`What's your favorite House in Game Of Thrones`)
.addReplyKeyboard([['Stark'], ['Lannister'], ['Targaryen'], ['None of the above']])
.get();
});
Custom Keyboards
Each of the methods below except Pause
and ChatAction
has 4 methods for controling and creating custom keyboards. Only one of them can be used, if you add more of them only the last one will be active.
Following methods are allowed, each of them represents one keyboard markup:
- addReplyKeyboard
- addInlineKeyboard
- replyKeyboardHide
- forceReply
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
addReplyKeyboard | No | keyboardArray (array, required, an array of keyboard keys), resizeKeyboard (boolean, optional, if the keyboard should be resizable), oneTimeKeyboard (boolean, optional, if the keyboard should be hidden after first usage) | this for chaining |
Telegram ReplyKeyboardMarkup, for more info visit official docs |
addInlineKeyboard | No | keyboardArray (array, required, an array of keyboard keys) | this for chaining |
Telegram InlineKeyboardMarkup, for more info visit official docs |
replyKeyboardHide | No | selective (boolean, optional, use this parameter if you want to hide keyboard for specific users only ) | this for chaining |
Telegram ReplyKeyboardHide, for more info visit official docs |
forceReply | No | selective (boolean, optional, use this parameter if you want to hide keyboard for specific users only ) | this for chaining |
Telegram ForceReply, for more info visit official docs |
Example
Reply keyboard:
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Text(`What's your favorite House in Game Of Thrones`)
.addReplyKeyboard([['Stark'], ['Lannister'], ['Targaryen'], ['None of the above']])
.get();
});
Inline keyboard:
const botBuilder = require('claudia-bot-builder');
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Text(`Claudia Bot Builder`)
.addInlineKeyboard([
[{
text: 'Website',
url: 'https://claudiajs.com'
}],
[{
text: 'Tell me more',
callback_data: 'MORE'
}]
])
.get();
});
Photo messages
Photo attachment allows you to send images.
API
Photo
(class) - Class that allows you to build a photo messages with optional custom keyboards.
Arguments:
- photo, string (required) - an url or an ID of already uploaded image.
- caption, string (optional) - a caption for an image.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
Custom Keyboards methods | No | See Custom Keyboard section | this for chaining |
See Custom Keyboard section |
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Photo('https://claudiajs.com/assets/claudiajs.png').get();
});
Audio messages
Audio attachment allows you to send audio files. If you want to send a voice message Telegram has sendVoice
method, but it is not a part of this builder at the moment.
API
Audio
(class) - Class that allows you to build an audio messages with optional custom keyboards.
Arguments:
- audio, string (required) - an url or an ID of already uploaded image.
- caption, string (optional) - a caption for an image.
- duration, integer (optional) - an optional duration of an audio file.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
addTitle | No | title (string, optional, audio file title) | this for chaining |
Track name |
addPerformer | No | performer (string, optional, audio file title) | this for chaining |
Performer name |
Custom Keyboards methods | No | See Custom Keyboard section | this for chaining |
See Custom Keyboard section |
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Audio('http://www.noiseaddicts.com/samples_1w72b820/4927.mp3')
.addTitle('Roar')
.addPerformer('Bear')
.get();
});
File messages
File attachment allows you to send any files.
API
File
(class) - Class that allows you to build file messages with optional custom keyboards.
Arguments:
- document, string (required) - an url or an ID of already uploaded file.
- caption, string (optional) - a caption for file.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
Custom Keyboards methods | No | See Custom Keyboard section | this for chaining |
See Custom Keyboard section |
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.File('http://example.com/files/file.pdf', 'Some File').get();
});
Location messages
Location template allows you to send a location, if you want to send a location of some venue use Venue message template.
API
Location
(class) - Class that allows you to build a location messages with optional custom keyboards.
Arguments:
- latutude, number (required) - location latitude.
- longitude, number (required) - location longitude.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
Custom Keyboards methods | No | See Custom Keyboard section | this for chaining |
See Custom Keyboard section |
get | Yes | No argsuments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Location(44.831115, 20.421277)
.get();
});
Venue messages
Venue template allows you to send a venue info, if you want to send a location without a name and address use Location message template.
API
Venue
(class) - Class that allows you to build a venue messages with optional custom keyboards.
Arguments:
- latitude, number (required) - location latitude.
- longitude, number (required) - location longitude.
- name, string (required) - venue name.
- address, string (required) - venue address.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
Custom Keyboards methods | No | See Custom Keyboard section | this for chaining |
See Custom Keyboard section |
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Venue(44.831115, 20.421277, 'Lemon Chili', 'Zemun Quay, Belgrade, Serbia')
.get();
});
Sticker messages
Sticker template allows you to send a Telegram sticker.
API
Sticker
(class) - Class that allows you to build sticker messages with optional custom keyboards.
Arguments:
- sticker, string (required) - an url (.webp sticker) or an ID of already uploaded sticker.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
Custom Keyboards methods | No | See Custom Keyboard section | this for chaining |
See Custom Keyboard section |
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Sticker('http://example.com/stickers/sticker.webp').get();
});
Contact messages
Contact template allows you to share contact's first name, last name and phone number.
API
Contact
(class) - Class that allows you to build contact messages with optional custom keyboards.
Arguments:
- phone, string (required) - contacts phone number.
- firstName, string (required) - contacts first name.
- lastName, string (optional) - contacts last name.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
Custom Keyboards methods | No | See Custom Keyboard section | this for chaining |
See Custom Keyboard section |
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return new telegramTemplate.Contact('123456789', 'John', 'Doe').get()
});
Changing chat action
Sometimes you just want to simulate user actions before sending a real message, ie. typing, uploading, etc. Claudia Bot Builder supports those chat actions.
API
ChatAction
(class) - Class that allows you to set a chat action.
Arguments:
- action, string (required) - a valid chat action: 'typing', 'upload_photo', 'record_video', 'upload_video', 'record_audio', 'upload_audio', 'upload_document' or 'find_location'. More info in official docs.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Telegram Messenger |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return [
new telegramTemplate.ChatAction('typing').get(),
'Hello'
];
});
Pause between messages
Sometimes it's good to make a short break when you are sending multiple messages, for that use Pause method.
API
Pause
(class) - Class that allows you to set a pause before next message.
Arguments:
durations, integer (optional) - a duration in miliseconds, if it's not provided 0.5 seconds will be set automatically.
Note: This is not the Telegram API method, it's a Claudia Bot Builder method that allows you to build better user experience.
Methods
Method | Required | Arguments | Returns | Description |
---|---|---|---|---|
get | Yes | No arguments | Formatted JSON to pass as a reply | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Claudia Bot Builder |
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return [
'1',
new telegramTemplate.Pause(1000).get(),
'2'
];
});
Other attachments
At the moment, Claudia Bot Builder does not have a full support for all Telegram message types, but you can send any custom message manually.
Here's how it works:
-
If you send simple text we'll wrap it in required format and bot will receive simple text message;
-
If you pass the object in format:
{ text: 'Some text', parse_mode: 'Markdown', reply_markup: JSON.stringify({ keyboard: [ ['First Button'], ['Second Button']], resize_keyboard: true, one_time_keyboard: true }) }
or anything else supported by Telegram (check the API here) we'll send that to the bot and just append chat id if you don't want to overwrite it.
-
If you send a message in format:
{ method: 'sendMessage', body: {} }
it'll do the same thing as step 2 for
reply.body
but it'll also allow you to overwrite reply method, ie. to send a message instead of answering as inline query, or to send video, file, etc.
Sending multiple messages
It's easy to send multiple messages, just pass an array with at least one of the methods mentioned above. You can combine them how ever you want.
Example
const botBuilder = require('claudia-bot-builder');
const telegramTemplate = botBuilder.telegramTemplate;
module.exports = botBuilder(message => {
if (message.type === 'telegram')
return [
new telegramTemplate.ChatAction('typing').get(),
new telegramTemplate.Pause(200).get(),
'Hello!',
new telegramTemplate.ChatAction('typing').get(),
new telegramTemplate.Pause(400).get(),
new telegramTemplate.Text(`What's your favorite House in Game Of Thrones`)
.addReplyKeyboard([['Stark'], ['Lannister'], ['Targaryen'], ['None of the above']])
.get()
];
});
Handling errors
Telegram Template Message builder checks if messages you are generating are following Telegram Messenger guidelines and limits, in case they are not an error will be thrown.
Example:
Calling new telegramTemplate.Text()
without text
will throw Text is required for Telegram Text template
error.
All errors that Claudia bot builder's telegramTemplate library is throwing can be found in the source code.
Errors will be logged in Cloud Watch log for your bot.