nizarmah / telefam

A Telegram Bot API NodeJS Library to ease the use of it

Telefam

A Telegram Bot API NodeJS Library to ease the use of it

Creating your bot

Creating your bot is simple. First thing you need to do is open Telegram and head to @BotFather. To start off, create the bot with it’s name.

/newbot

When prompted for the name, enter the desired name of the bot. Then you must give it a username ending with bot. At last, save your bot token and make sure you don’t share it. Each bot is given a unique authentication token [when it is created][8]. The token looks something like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11, but we’ll use simply <token> in this document instead. You can learn about obtaining tokens and generating new ones in [this document][9].

Installing library

This is a pretty simple step.

Yet, we're gonna need form-data and request

npm install request -save
npm install form-data -save
npm install https://github.com/nizarmah/telefam.git -save

Note
Move telefam to node_modules
Every Method has a callback(error, response)

Initializing your bot

Start off by setting up an Express NodeJS web server if you haven’t. Then initialize the Bot as follows. Remember the bot token you saved previously ? Well, we’ll be using that.

var Telefam = require('telefam');
var Fam = new Telefam('<token>');

Now, similar to the [Telegram Bot API], all methods are available. Also, inline mode is too. Moreover, every method’s parameters are available for use in JSON form. However, some would be included in options. We’ll go over what is included as we discuss every method and the options for each.

Manual

Well, the manual is pretty much almost accurate with the Telegram Web API. However there are some small changes in the way of entering stuff in. One of which is the options JSON Object for specific elements for specific methods.
Those exceptions are stated below with examples.

Options parameters are optional parameters but should be included under options when passing JSON Object.

getUpdates

Use this method to receive incoming updates using long polling (wiki). An Array of Update objects is returned.

Parameters	Required
offset	Options Optional
limit	OptionsOptional
timeout	Options Optional
allowed_updates	Options Optional

Notes
1. This method will not work if an outgoing webhook is set up.
2. In order to avoid getting duplicate updates, recalculate offset after each server response.

The parameters would look something like this.

Fam.getUpdates({
	options: {
		offset: 1,
		limit: 10,
		timeout: 5000
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

For polling, the bot would get updates in this manner ( from getUpdates.js )

var lastUpdateId = 0;
setInterval(function () {
	Bot.getUpdates({
		options: {
			offset: lastUpdateId++
		}
	}, function (error, response) {
		if (error) throw error;
	if (response.result.length > 0)
		lastUpdateId = response.result[response.result.length - 1].update_id;

	for (var i = 0; i < response.result.length; i++) {
		// do stuff with the new updates here
	}
});

}, 1000);

InputFile

This object represents the contents of a file to be uploaded. Must be posted using multipart/form-data in the usual way that files are uploaded via the browser.

Note
You can only upload local files and not remote ones.
One file at a time, sadly.

This is how uploading an input file looks like.

/*
* path for local files
* url for online files (HTTP)
*/
file_type: {
	path: "the/path/to/file.extension"
	url: "http://linkhere.com/file.extension"
}

If the file_type isn't an object but a String; consequently, it searches for the file_id that's supposed to be in the bot files and sends it, instead of uploading it.

For an example, check sendPhoto.js

sendMessage

Parameters	Required
chat_id	Yes
text	Yes
parse_mode	Options Optional
disable_web_page_preview	Options Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardHide or ForceReply	Options Optional	Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to hide reply keyboard or to force a reply from the user.

Formatting options

The parameters would look something like this.

Fam.sendMessage({
	chat_id: 3489324, /* chat message being sent to */
	text: "More _Random_ Stuff from https://nizarmah.me/",
	options: {
		parse_mode: "Markdown",
		disable_notification: false,
		disable_web_page_preview: false,
		reply_to_message_id: 32, /* message that's being replied to */,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

forwardMessage

Parameters	Required
chat_id	Yes
from_chat_id	Yes
disable_notification	Options Optional
message_id	Yes

The parameters would look something like this.

Fam.forwardMessage({
	chat_id: 2348972, /* chat_id message being forwarded to */
	from_chat_id: 3289718, /* chat_id message being forwarded from */
	message_id: 134, /* id of message being forwarded */
	options: {
		disable_notifcation: true
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendPhoto

Parameters	Required
chat_id	Yes
photo	Yes
caption	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

The parameters would look something like this.

Fam.sendPhoto({
	chat_id: 32428324,
	photo: "something.png",
	caption: "Photo of Something",
	options: {
		disable_notification: true,
		reply_to_message_id: 34,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendAudio

For sending voice messages, use the sendVoice method instead.

Parameters	Required
chat_id	Yes
audio	Yes
caption	Optional
title	Optional
performer	Optional
duration	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

The parameters would look something like this.

Fam.sendAudio({
	chat_id: 32428324,
	audio: "audio.mp3",
	title: "My heavenly voice",
	performer: "Typical Me",
	duration: 35800,
	options: {
		disable_notification: false,
		reply_to_message_id: 16,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendAudio

For sending video note messages, use the sendVideoNote method.

Parameters	Required
chat_id	Yes
video_note	Yes
duration	Optional
length	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

sendDocument

Parameters	Required
chat_id	Yes
document	Yes
caption	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

The parameters would look something like this.

Fam.sendDocument({
	chat_id: 32428324,
	document: "resume.pdf",
	caption: "My Resume",
	options: {
		disable_notification: true,
		reply_to_message_id: 34,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendSticker

Use this method to send .webp stickers. On success, the sent Message is returned.

Parameters	Required
chat_id	Yes
sticker	Yes
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

To get existing sticker file_ids, send them to the bot, and check the getUpdates; consequently, file_id.

The parameters would look something like this.

Fam.sendSticker({
	chat_id: 32428324,
	sticker: "", /* at this time i was still collecting some sticker file_ids */
	options: {
		disable_notification: true,
		reply_to_message_id: 34,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendVideo

Parameters	Required
chat_id	Yes
video	Yes
duration	Optional
width	Optional
height	Optional
caption	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

The parameters would look something like this.

Fam.sendVideo({
	chat_id: 32428324,
	video: "mytwerk.mp4",
	caption: "My Twerk",
	width: 800,
	height: 600,
	duration: 50000,
	options: {
		disable_notification: true,
		reply_to_message_id: 34,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendVoice

Parameters	Required
chat_id	Yes
voice	Yes
caption	Optional
duration	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

The parameters would look something like the one for sendAudio.

sendLocation

Parameters	Required
chat_id	Yes
latitude	Yes
longitude	Yes
live_period	Options Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

The parameters would look something like this.

Fam.sendLocation({
	chat_id: 32428324,
	latitude: 32,
	longitude: 150,
	options: {
		disable_notification: true,
		reply_to_message_id: 34,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendVenue

Parameters	Required
chat_id	Yes
latitude	Yes
longitude	Yes
title	Yes
address	Yes
foursquare_id	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

The parameters would look something like this.

Fam.sendVenue({
	chat_id: 32428324,
	latitude: 32,
	longitude: 150,
	title: "Hell",
	address: "Devil's Street, 52nd Avenue"
	foursquare_id: 2342,
	options: {
		disable_notification: true,
		reply_to_message_id: 34,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendContact

Parameters	Required
chat_id	Yes
phone_number	Yes
first_name	Yes
last_name	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

The parameters would look something like this.

Fam.sendContact({
	chat_id: @devilschannel,
	phone_number: "[phone],
	first_name: "Lucifer",
	options: {
		disable_notification: true,
		reply_to_message_id: 34,
		reply_markup: {
			force_reply: true
		}
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

sendChatAction

Parameters	Required
chat_id	Yes
action	Yes

The parameters would look something like this.

Fam.sendChatAction({
	chat_id: @devilssupergroup,
	action: "typing"
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

getUserProfilePhotos

Parameters	Required
user_id	Yes
offset	Options Optional
limit	Options Optional

The parameters would look something like this.

Fam.getUserProfilePhotos({
	user_id: 32428324,
	options: {
		offset: 10,
		limit: 10
	}
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

answerCallbackQuery

Parameters	Required
callback_query_id	Yes
text	Optional
show_alert	Optional

The parameters would look something like this.

Fam.answerCallbackQuery({
	callback_query_id: 1348134234232,
	text: "Received Query Fam",
	show_alert: false /* test out the false and true, they are nice to check out */
}, function (error, res) {
	if (error) throw error;
if (!res.ok) return console.log(res);
// treat res here. 

});

editMessageCaption

Use this method to edit captions of messages sent by the bot or via the bot (for inline bots). On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.

Parameters	Required
chat_id	Optional
message_id	Optional
inline_message_id	Optional
caption	Optional
reply_markup	Options Optional

sendInvoice

Parameters	Required
chat_id	Yes
title	Yes
description	Yes
payload	Yes
provider_token	Yes
start_parameter	Yes
currency	Yes
prices	Yes
photo_url	Optional
photo_size	Optional
photo_width	Optional
photo_height	Optional
need_name	Optional
need_phone_number	Optional
need_email	Optional
need_shipping_address	Optional
is_flexible	Optional
disable_notification	Options Optional
reply_to_message_id	Options Optional
reply_markup	Options Optional

answerShippingQuery

Parameters	Required
shipping_query_id	Yes
ok	Yes
shipping_options	Optional
error_message	Optional

answerPreCheckoutQuery

Parameters	Required
pre_checkout_query_id	Yes
ok	Yes
error_message	Optional