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.

claudiajs / claudia-bot-builder

claudia-bot-builder/docs/TELEGRAM_CUSTOM_MESSAGES.md

Telegram Custom Messages and Message Templates

Intro

Text messages

API

Methods

Example

Custom Keyboards

Methods

Example

Photo messages

API

Methods

Example

Audio messages

API

Methods

Example

File messages

API

Methods

Example

Location messages

API

Methods

Example

Venue messages

API

Methods

Example

Sticker messages

API

Methods

Example

Contact messages

API

Methods

Example

Changing chat action

API

Methods

Example

Pause between messages

API

Methods

Example

Other attachments

Sending multiple messages

Example

Handling errors