Lumpia

• 1: Pengantar
• 2: Konsep
• 3: Versi
• 4: Inisiasi
• 5: Bot
• 6: Telegram
• 7: Context
• 8: Update Type
• 9: Helper

1 - Pengantar

Pengantar

Apa ini?

Lumpia Framework atau kita sebut saja lumpia adalah sebuah framework Google Apps Script untuk mempermudah pembuatan bot api pada Telegram.

Google Apps Script atau kita sebut GAS saja, menyediakan fitur library untuk menyematkan sumber kode pihak lain untuk mempermudah membangun sebuah aplikasi.

Lumpia Framework bekerja pada fitur modul library yang tersedia pada Google Apps Script.

Pendahuluan

Library Google Apps Script (GAS) untuk Telegram edisi ke-3, merupakan suksesi dari GAS Library sebelumnya, yakni GASLib edisi 1 dan edisi 2 Lib v2 yang telah berhasil banyak dimanfaatkan.

Terinspirasi dari Telegraf yang dirasa cukup praktis dan efektif pada penggunaan sehari-hari. GASLibv3 membuat karakteristiknya sendiri, lantaran coding pada GAS memiliki banyak keterbatasan seperti tidak support proses (true) async, promise, deteksi tipe blob / stream, tidak banyak paket ready yang bisa langsung diberdayakan, dan berbagai kendala lainnya.

Namun, tidak perlu bekecil hati, framework GASLibv3 ini insyaAllah, lebih dari cukup guna kebutuhan sebuah proyek dalam skala kecil hingga menengah. Apalagi ditambah dukungan komunitas Grup Telegram @botIndonesia yang cukup baik menjadikan kamu tidak bingung harus pergi kemana untuk sharing.

Pada edisi ini, terdapat perubahan cukup besar dan cukup signifikan secara struktur, konsep, dan penggunaan. Tidak lagi seolah sebuah library namun menjadi sebuah framework sempurna dan modern untuk bot telegram. Dengan demikian, harapannya, penggunaan bisa menjadi lebih produktif untuk kebutuhan pekerjaan, kesenangan, maupun tools pembantu lainnya.

Fitur

• Semakin simple lagi dan lagi
• Konsep modern, terdapat middleware untuk melakukan hook message
• Support untuk penyediaan plugin yang dapat disisipkan pada middleware
• Tidak ribet memikirkan pondasi kodingan, sehingga bisa lebih berfokus pada proses flow proyek bot kamu
• Dokumentasi bagus, mudah dipelajari dan diikuti
• Terdapat panduan dan tutorial, secara tertulis maupun video
• Sumber kode terbuka, yang dapat diperiksa, diteliti, dan dipelajari oleh siapapun
• GRATIS jika merasa bermanfaat bebas berdonasi untuk mendukung proyek ini.. dipersilakan.
• Didukung oleh komunitas telegram @botindonesia yang cukup aktif.

Pros

• Menggunakan bahasa pemrograman javascript yang telah dikenal sangat luas, banyak literasi dan dukungan komunitas luas. Sampai saat ini masih terus dikembangkan.
• Integrasi dengan seluruh service yang disediakan Google (Drive, Docs, Translate, Map, Bigdata, dan ratusan service lainnya).
• Bisa dijadikan service restful guna diintegrasikan lebih luas dengan proyek-proyek lainnya
• Mendukung remote database (oracle, mysql, mariadb, nosql: mongodb, dynamodb, firebase, dlsb), internal (user service properties) ataupun “psedo” seperti spreadsheet.
• Masih berstatus aktif dalam pengembangan

Cons

• Sebagaimana halnya melekat pada service Google Apps Script, maka melekat pula kelemahannya pada framework ini. Misal diantaranya, tidak support proses async, terdapat pembatasan fetch, dan limitasi lainnya.
• Memiliki limitasi sesuai ketentuan Google.

Compare

Kelebihan dibandingkan versi lama

Dan masih banyak lainnya..

Kecocokan

Bagi pengguna library versi 1 dan 2, lumpia (GAS Lib v3) tidak kompatible.

Selamat menyesuaikan!

2 - Konsep

Lumpia dibangun atas 3 segment saat prosesi. Karena GAS tidak support async, maka ketiganya dipilih secara berurutan.

Misalkan middleware diletakkan pada codingan paling bawah, tetep dijalankan dibagian paling atas (didahulukan).

Bagan

graph TD;
    lumpia("🍥 Lumpia") --- helper("🧱 helper"):::green;
    lumpia --- markup("🛠 markup"):::green;
    lumpia --- fetch("🕸 fetch");
    lumpia --- db[("👥 user db")];
    lumpia --- init;
    init --> bot((bot));
    bot(("🤖 bot")) -.-> debug([debug]);
    tg("✈️ telegram client") ---> |shorthand|bot
    user(["👤 user"]) --> |text, photo, cb inline, etc..|update[/update/]
    update --> |doPost|bot
    lumpia -.- tg
    subgraph .
        bot --> |ctx|middleware;
        middleware --> ctx{{context}}
        ctx --> broadcast;
        ctx --> trigger;
    end
    broadcast --> ends(["👤 user"])
    trigger --> ends
    
    style lumpia color:blue,fill:#bdd5ef
    style fetch fill:#efd9bd;
    style init fill:#e1efbd
    style ctx fill:#ecedea,color:grey
    style ends color:white,fill:#000;
    style user color:white,fill:#000;
    classDef green fill:#9de0b2
    click broadcast "/docs/lumpia/konsep/#2-broadcast"
    click ctx "/docs/lumpia/ctx"

1. Middleware

Cakupan: use, middleware

Middleware ini bisa mengentikan proses. Misalnya:

bot.use(ctx => console.log('stop') );

Maka, proses akan terhenti tidak dilanjutkan pada event berikutnya.

2. Broadcast

Cakupan: on

Cek bagian update type

3. Trigger

Cakupan: cmd, command, hear, hears, action

Karakteristik

Broadcast dan triger berjalan bersamaan (didahulukan brodcast) ketika middleware sudah selesai diproses dan menghasilkan context

Keduanya tidak saling menghentikan.

Contoh:

bot.on('text' , ctx => ctx.reply('masuk 1'));
bot.cmd('start', ctx => ctx.reply('masuk 2'));

Pesan user yang berupa text dan trigger /start akan dieksekusi (ditangkap keduanya), yang didahulukan adalah jenis broadcast (bot.on), meskipun seandainya codingan diatas dibalik, diletakkan dibawahnya trigger (bot.cmd).

Bisa dianggap sebagai fitur, tapi juga bisa dianggap sebagai bugs juga.

Pandai-pandailah memanfaatkan setuasi-nya.

3 - Versi

ID Library

lumpia

Adalah versi stabil dari GAS Lib v3.

Semua dokumentasi menggunakan acuan ini.

• New
• Legacy

1Yo6vQRwjG5Gl9jeEF0g2tBTUa0XN5MyT4G_HeDpRr9DvabxhRcSdhPNj

MUD_wfLskZT2D99lRXLh94vvg_do21SJR

bakpia

adalah versi beta, digunakan hanya oleh pengembang buat bahan testing.

• New
• Legacy

1OSN8eNlJtw2ehf3ul7h48Jb8rdeljKhC5Rw3cJo4nkEFITdS01Di0N_S

M2iDAxzI3JJ4n6a8sryWJsfvg_do21SJR

Jika menggunakan bakpia, set variable paling atas untuk menyesuaikan dengan seluruh isi dokumentasi dan sample yang berada di sini:

var lumpia = bakpia;

const token = '12345:abcde';
const bot = new lumpia.init(token);

// dst..

matoa

adalah versi alpha (tahap development)

• tidak dirilis secara publik.
• tidak ada versi librarynya, karena dibangun secara langsung

ketikda dikonversi menjadi library, berubah nama menjadi bakpia dan lumpia.

Versi

Nama

Seperti halnya android, kita mengenal Kit Kat, Oreo, dlsb.

Maka, kode library ini diberi kode penamaan nama makanan yang ada di pasar. Jadi kalau dibahas jadi enak, kita ngobrolin makanan hehe..

Nomor

Penomoran versi

Misalnya v3.1

• Versi mayor adalah versi 3

Dimana nomor 3 adalah generasi atau edisi ke-3 dari Library GAS untuk Telegram ini. Versi ini tidak berubah, atau setidaknya tidak akan berubah dalam jangka dekat bilamana belum ada edisi baru lagi.

• Versi minor adalah 1

Versi minor adalah versi build. Yang akan terus bertambah nilainya lantaran hasil snapshot dari release versi pada GAS.

Jika terdapat nomor minor yang lompat (tidak ada), berarti dicabut rilisnya. Bisa jadi dikarenakan gagal / cacat, atau kesalahan teknis release.

Log History

Silakan cek pada halaman berikut:

• Github Release

4 - Inisiasi

RESUME

Table resume semua properti yang melekat pada lumpia.

Berikut ini penjelasan bagaimana mendeklarasikan, atau menginisasi awal object-object pada saat menggunakan lumpia

init

Dipergunakan saat pertama kali atau tiap kali membuat objek lumpia.

Syntax: new lumpia.init(token, options)

• token adalah token bot yang didapatkan dari botfather

options

Diisi dalam format JSON.

const token = '123456:abcde';
const adminbot = 213567634;
const usernamebot = 'strukturbot';
const bot = new lumpia.init(token, {
    log_id: adminbot,
    username: usernamebot,
    prefix_command: '.!/'
});

// ... next code

Dapat juga diakses secara langsung (sesudah bot diinisiasi) :

bot.options.log_id = 213567634;
bot.options.prefix_command = '.!/';

DEBUG

Memaksa bot menampilkan JSON apapun yang diterima ke log_id yang diseting saat pertama kali init.

Berguna untuk debugging isi message.

• default: false

const token = '123456:abcde';
const bot = new lumpia.init(token, { log_id: 213567634 });

lumpia.DEBUG = true;

function doPost(e) {
  bot.doPost(e);
}

verbose

Mengaktifkan logging secara detail dipergunakan saat debugging.

Verbose hanya berjalan pada mode panel editor pada GAS ketika menjalanan sebuah fungsi ke doPost atau handleUpdate().

Di bot tidak ada perbedaan apa-apa. Matikan mode verbose ini jika sudah tahap produksi, agar tidak terlalu banyak script bekerja.

• default: false;

lumpia.verbose = true;

version

Untuk mengetahui versi lumpia yang sedang dipergunakan.

Syntax: lumpia.version

Hasil berupa tipe data object (json) bersifat informasi.

bot.cmd(['ver', 'versi', 'version'], ctx => {
    let version = lumpia.version;
    let pesan = `🤖 Bot ini dibangun menggunakan <b>${version.name}</b> <code>v${version.number}.${version.build}</code>`;
    pesan += `\n\n✅ Sumber bersama belajar <b>Bot Telegram Indonesia</b>`

    let keyboard = [
        button.url('📚 Docs', 'https://lumpia.js.org'),
        button.url('👥 @botindonesia', 'https://t.me/botindonesia')
    ]
    ctx.replyWithHTML(pesan, {
        reply_markup: markup.inlineKeyboard(keyboard)
    });
})

5 - Bot

RESUME

Resume method dan params yang dipergunakan oleh bot.

Penjelasan

bot

Adalah variable umum (kamu boleh menggantinya jika mau), yang berupa object gabungan segala middleware, method atau fungsi-fungsi, dan data-data penunjang lainnya.

Seperti halnya pada sistem lainnya (Ruby, Go, NodeJS, PHP, dsb), menggunakan bot sebagai variable untuk menghandlenya.

Pendeklarasian

Contohnya sebagai berikut:

const token = '123:abc';
const bot = new lumpia.init(token);

bot menjadi sebuah object sebagai perwakilan atas bot Telegram dengan ‘jiwa’ token-nya.

Token bot adalah identitasnya. Sehingga misalnya, botnya adalah belarGASbot dengan token 123:abc. Maka ketika kita coding, menyebut bot adalah si belajarGASbot nya (yang telah disambungkan dengan identias token).

Amsal

Sebagai permisalan dalam kehidupan ini, adalah sebagai berikut:

• botfather adalah ortu yang melahirkan bot
• Ada permintaan nama, karena belum pernah ada.. kemudian diberilah nama belajarGASBot
• Selanjutnya mendapatkan token sebagai nomor identitas (Akta Lahir) nya.
• bot dikalungkan token sebagai tanda peserta. Yakni di deklarasikan, diumumkan.. Wooi si bot ini adalah pengenal untuk belajarGASbot

Sehingga, menyebut bot adalah menyebut object yang telah ditentukan tersebut.

Sebagaimana manusia, bot memiliki fungsi atau istilahnya disebut method.

Kalau manusia bisa makan, minum, jalan-jalan, kencan, dan lainnya. Maka bot memiliki method untuk mengirim pesan, kirim gambar, suara, kick orang, dan lain lain.

Mengenal Method Bot

Contoh fungsi dari telegram.. yakni mengirim pesan. Maka, cara mengaksesnya adalah:

bot.telegram.sendMessage(chat_id, text)

Terdapat 3 field pada susunan diatas:

• bot penyebutan / pemanggilan bot kita
• telegram method atau fungsi dari/untuk/ke Telegram
• sendMessage menjalankan fungsi untuk mengirim pesan.

Fungsi kirim pesan (sendMessage) sendiri memiliki kelengkapan minimal 2 syarat agar terkirim:

• chat_id adalah ruangan obrolan
• text adalah isi pesan yang akan dikirim.

Misalnya, mau berkirim pesan ke ruangan (grup) yang memiliki id -10010000001, maka:

bot.telegram.sendMessage(-10010000001, 'Halo Brok!');

maka bot akan mengirim pesan Halo Brok! ke ruangan ber kode id -10010000001.

Darimana kode ruangan (chat_id) ini berasal? Chat ID ditentukan oleh telegram. Kita tidak bisa menentukan sendiri kodenya. Namun kita bisa mengetahui ID nya dengan beberapa cara yang (insyaAllah) nanti akan dijelaskan pada halaman lainnya.

Implementasi GAS

// token bot dari bapak bot
const token = '123:abc';  

// adminbot variable untuk chat_id: boleh id kamu sendiri, boleh id grup
const adminbot = 213567634;   // ini adalah id saya, @hasanudinhs

// inisiasi bot
const bot = new lumpia.init(token);

// fungsi mengirim pesan
function sendMessage() {
  let result = bot.tg.sendMessage(adminbot, 'halo mas brok');
  Logger.log(JSON.stringify(result, null, 2));
}

Kemudian jalankan fungsi tersebut pada Google Apps Script. Cara menjalankannya, bisa disimak pada materi menjalankan fungsi.

Jika berhasil, pesan kamu akan terkirim. Dan pada program, mendapatkan log sendMessage.

{
  "ok": true,
  "result": {
    "message_id": 885,
    "from": {
      "id": 1719983221,
      "is_bot": true,
      "first_name": "belajarBotGas",
      "username": "belajarGASbot"
    },
    "chat": {
      "id": 213567634,
      "first_name": "‏bangHasan",
      "last_name": "HS",
      "username": "hasanudinhs",
      "type": "private"
    },
    "date": 1629863141,
    "text": "halo mas brok"
  }
}

Semoga penjelasan sederhana ini bisa dimengerti :-)

Method dan Params

options

Secara fungsi sama seperti options dalam inisiasi.

Namun pada bot dapat diakses secara langsung sebagai setter atau getter.

bot.options.log_id = 213567634;
bot.options.prefix_command: '.!/';
bot.options.username: 'strukturbot';

token

Use this property to get/set bot token.

bot.token = [string]

Log ID

Use this property to get/set bot options log_id.

Alias bot.options.log_id

bot.log_id = [number/string]

doPost

memproses data POST pada function doPost buil-in pada Google Apps Script

bot.doPost(e)

Contoh:

function doPost(e) {
  bot.doPost(e);
}

on

Menangkap event yang disediakan atas tangkapan ctx.broadcast

bot.on(updateTypes, fn)

Contoh:

bot.on('photo', ctx => console.log(ctx.photo));

hears

Menangkap dan memproses pesan yang bertipe text.

Alias: hear

bot.hears(triggers, fn)

user: Assalamu'alaikum
bot: Waa'alaikumussalam Wr Wb

bot.hears("Assalamu'alaikum", ctx => ctx.replyIt("Waa'alaikumussalam Wr Wb"));

command

Command handling.

Alias: cmd

bot.command(commands, fn)

user: /ping
bot: Pong!

bot.cmd("ping", ctx => ctx.reply("Pong!"));

start

Handler for /start command.

bot.start(fn)

Dapat menghandle juga beberapa kondisi sebagai berikut :

• /start@namabot jika nama bot di-set pada parameter username saat inisiasi (lumpia.init) pada options
• PAYLOAD dapat diakses pada ctx.payload jika terdapat data yang dikirimkan.

user: /start
bot: Hello Human!

bot.start(ctx => ctx.reply("Hello Human"));

action

Registers for handling callback_data actions with string or regular expressions.

bot.action(triggers, fn)

use

Register a middleware.

Alias middleware

bot.use(fn)

fn is function. With Parameters:

bot.use( (ctx, next) => {
  ctx.hooked = true;
  // eksekusi next() untuk melanjutkan ke middleware berikutnya
  next();
})

6 - Telegram

RESUME

Table resume semua properti yang melekat pada bot.telegram.

bot.telegram dapat juga disingkat menjadi bot.tg

variable bot bisa apa saja. Oleh karena dalam list ini, cukup dituliskan method telegram agar disesuaikan dengan variable penyertanya sendiri.

callApi

Main method to call api telegram.

telegram.callApi(method, data)

// call getMe() method
telegram.callApi('getMe', {});

// call sendMessage() method
telegram.callApi('sendMessage', { 
    chat_id: 213567634, 
    text: 'Hello Lumpia!' 
});

addStickerToSet

Use this method to add a new sticker to a set created by the bot.

telegram.addStickerToSet(ownerId, name, stickerData) 👉🏼 📑

answerCallbackQuery

alias untuk answerCbQuery

answerCbQuery

Use this method to send answers to callback queries.

telegram.answerCbQuery(callbackQueryId, text, [showAlert], [extra]) 👉🏼 📑

answerGameQuery

Use this method to send answers to game query.

telegram.answerGameQuery(callbackQueryId, url)

answerShippingQuery

Use this method to send answers to shipping query.

telegram.answerShippingQuery(shippingQueryId, ok, shippingOptions, [errorMessage])

answerPreCheckoutQuery

Use this method to send answers to shipping query.

telegram.answerPreCheckoutQuery(preCheckoutQueryId, ok, [errorMessage])

answerInlineQuery

Use this method to send answers to an inline query.

telegram.answerInlineQuery(inlineQueryId, results, [extra])

approveChatJoinRequest

Use this method to approve a chat join request.

telegram.approveChatJoinRequest(chatId, userId, [extra])

banChatSenderChat

Use this method to ban a channel chat in a supergroup or a channel.

banChatSenderChat(chatId, senderChatId, extra) 👉🏼 📑

createNewStickerSet

Use this method to create new sticker set owned by a user.

telegram.createNewStickerSet(ownerId, name, title, stickerData, [isMasks]) 👉🏼 📑

declineChatJoinRequest

Use this method to decline a chat join request.

telegram.declineChatJoinRequest(chatId, userId, [extra])

deleteChatStickerSet

Use this method to delete a group sticker set from a supergroup.

telegram.deleteChatStickerSet(chatId) 👉🏼 📑

deleteMessage

Use this method to delete bot messages.

telegram.deleteMessage(chatId, messageId) 👉🏼 📑

setStickerSetThumb

Use this method to set the thumbnail of a sticker set.

telegram.setStickerSetThumb(name, userId, [thumb]) 👉🏼 📑

deleteStickerFromSet

Use this method to delete a sticker from a set created by the bot.

telegram.deleteStickerFromSet(stickerId) 👉🏼 📑

editMessageCaption

Use this method to edit captions of messages sent by the bot or via the bot.

telegram.editMessageCaption(chatId, messageId, inlineMessageId, caption, [extra])

editMessageMedia

Use this method to edit media of messages sent by the bot or via the bot.

telegram.editMessageMedia(chatId, messageId, inlineMessageId, media, [extra])

editMessageLiveLocation

Use this method to edit live location messages sent by the bot or via the bot.

telegram.editMessageLiveLocation(latitude, longitude, chatId, messageId, inlineMessageId, [markup]) 👉🏼 📑

editMessageReplyMarkup

Use this method to edit only the reply markup of messages sent by the bot or via the bot.

telegram.editMessageReplyMarkup(chatId, messageId, inlineMessageId, markup, [extra])

editMessageText

Use this method to edit text messages sent by the bot or via the bot.

telegram.editMessageText(chatId, messageId, inlineMessageId, text, [extra])

forwardMessage

Forwards message.

telegram.forwardMessage(chatId, fromChatId, messageId, [extra])

sendCopy

Sends message copy.

telegram.sendCopy(chatId, message, [extra])

copyMessage

Use this method to copy messages of any kind.

telegram.copyMessage(chatId, message, [extra])

getWebhookInfo

Use this method to get current webhook status. Requires no parameters. On success, returns a WebhookInfo object. If the bot is using getUpdates, will return an object with the url field empty.

telegram.getWebhookInfo()

getChat

Use this method to get up to date information about the chat (current name of the user for one-on-one conversatio ns, current username of a user, group or channel, etc.).

telegram.getChat(chatId) 👉🏼 📑

getChatAdministrators

Use this method to get a list of administrators in a chat. On success, returns an Array of ChatMember objects that contains information about all chat administrators except other bots. If the chat is a group or a supergroup and no administrators were appointed, only the creator will be returned.

telegram.getChatAdministrators(chatId) 👉🏼 📑

setGameScore

Use this method to set the score of the specified user in a game. On success, if the message was sent by the bot, returns the edited Message, otherwise returns True. Returns an error, if the new score is not greater than the user’s current score in the chat.

telegram.setGameScore(userId, score, inlineMessageId, chatId, messageId, [editMessage], [force]) 👉🏼 📑

getGameHighScores

Use this method to get data for high score tables. Will return the score of the specified user and several of his neighbors in a game. On success, returns an Array of GameHighScore objects.

telegram.getGameHighScores(userId, inlineMessageId, chatId, messageId) 👉🏼 📑

getChatMember

Use this method to get information about a member of a chat.

telegram.getChatMember(chatId, userId) 👉🏼 📑

getChatMembersCount

Use this method to get the number of members in a chat.

telegram.getChatMembersCount(chatId) 👉🏼 📑

getFile

Returns basic info about a file and prepare it for downloading.

telegram.getFile(fileId) 👉🏼 📑

getFileLink

Returns link to file.

telegram.getFileLink(fileId)

getMe

Returns basic information about the bot.

telegram.getMe() 👉🏼 📑

getMyCommands

Use this method to get the current list of the bot’s commands. Requires no parameters. Returns Array of BotCommand on success.

telegram.getMyCommands() 👉🏼 📑

getStickerSet

Use this method to get a sticker set.

telegram.getStickerSet(name)

getUserProfilePhotos

Returns profiles photos for provided user.

telegram.getUserProfilePhotos(userId, [offset], [limit]) 👉🏼 📑

setChatPermissions

Use this method to set default chat permissions for all members.

telegram.setChatPermissions(chatId, permissions)

banChatMember

Use this method to ban a user in a group, a supergroup or a channel. In the case of supergroups and channels, the user will not be able to return to the chat on their own using invite links, etc.

telegram.banChatMember(chatId, userId, [extra])

restrictChatMember

Use this method to restrict a user in a supergroup.

telegram.restrictChatMember(chatId, userId, [extra])

promoteChatMember

Use this method to promote or demote a user in a supergroup or a channel.

telegram.promoteChatMember(chatId, userId, [extra])

setChatAdministratorCustomTitle

New custom title for the administrator; 0-16 characters, emoji are not allowed

telegram.setChatAdministratorCustomTitle(chatId, userId, [extra])

exportChatInviteLink

Use this method to export an invite link to a supergroup or a channel.

telegram.exportChatInviteLink(chatId) 👉🏼 📑

setChatPhoto

Use this method to set a new profile photo for the chat.

telegram.setChatPhoto(chatId, photo) 👉🏼 📑

deleteChatPhoto

Use this method to delete a chat photo.

telegram.deleteChatPhoto(chatId) 👉🏼 📑

setChatTitle

Use this method to change the title of a chat.

telegram.setChatTitle(chatId, title) 👉🏼 📑

setChatDescription

Use this method to change the description of a supergroup or a channel.

telegram.setChatDescription(chatId, description) 👉🏼 📑

setChatStickerSet

Use this method to set a new group sticker set for a supergroup.

telegram.setChatStickerSet(chatId, stickerSetName) 👉🏼 📑

pinChatMessage

Use this method to pin a message in a supergroup.

telegram.pinChatMessage(chatId, messageId, [extra])

unpinChatMessage

Use this method to unpin a message in a supergroup chat.

telegram.unpinChatMessage(chatId) 👉🏼 📑

unpinAllChatMessages

Use this method to clear the list of pinned messages in a chat

telegram.unpinAllChatMessages(chatId) 👉🏼 📑

leaveChat

Use this method for your bot to leave a group, supergroup or channel.

telegram.leaveChat(chatId) 👉🏼 📑

deleteWebhook

Removes webhook integration.

telegram.deleteWebhook() 👉🏼 📑

sendAudio

Sends audio.

telegram.sendAudio(chatId, audio, [extra])

sendGame

Sends game.

telegram.sendGame(chatId, gameName, [extra])

sendChatAction

Sends chat action.

telegram.sendChatAction(chatId, action)

sendContact

Sends document.

telegram.sendContact(chatId, phoneNumber, firstName, [extra])

sendDice

Sends dice.

telegram.sendDice(chatId, [extra])

sendDocument

Sends document.

telegram.sendDocument(chatId, doc, [extra])

sendLocation

Sends location.

telegram.sendLocation(chatId, latitude, longitude, [extra])

sendMessage

Sends text message.

telegram.sendMessage(chatId, text, [extra])

sendPhoto

Sends a photo.

telegram.sendPhoto(chatId, photo, [extra])

sendMediaGroup

Sends media album.

telegram.sendMediaGroup(chatId, media, [extra])

sendSticker

Sends sticker.

telegram.sendSticker(chatId, sticker, [extra])

setStickerPositionInSet

Use this method to move a sticker in a set created by the bot to a specific position.

telegram.setStickerPositionInSet(sticker, position)

sendVenue

Sends venue information.

telegram.sendVenue(chatId, latitude, longitude, title, address, [extra])

sendInvoice

Sends invoice.

telegram.sendInvoice(chatId, invoice)

sendVideo

Sends video.

telegram.sendVideo(chatId, video, [extra])

sendAnimation

Sends video.

telegram.sendAnimation(chatId, animation, [extra])

sendVideoNote

Sends round video.

telegram.sendVideoNote(chatId, video, [extra])

sendVoice

Sends voice.

telegram.sendVoice(chatId, voice, [extra])

sendPoll

Sends a poll.

telegram.sendPoll(chatId, question, options, [extra])

setMyCommands

Use this method to change the list of the bot’s commands

telegram.setMyCommands(commands)

sendQuiz

Sends quiz.

telegram.sendQuiz(chatId, question, options, [extra])

stopPoll

Stops anonymous poll.

telegram.stopPoll(chatId, messageId, [extra])

stopMessageLiveLocation

Use this method to stop updating a live location message sent by the bot or via the bot (for inline bots) before live_period expires.

telegram.stopMessageLiveLocation(chatId, messageId, inlineMessageId, [markup]) 👉🏼 📑

uploadStickerFile

Use this method to upload a .png file with a sticker for later use in createNewStickerSet and addStickerToSet methods.

telegram.uploadStickerFile(ownerId, stickerFile) 👉🏼 📑

setWebhook

Specifies an url to receive incoming updates via an outgoing webhook.

telegram.setWebhook(url, [extra]) 👉🏼 📑

unbanChatMember

Use this method to unban a previously kicked user in a supergroup.

telegram.unbanChatMember(chatId, userId) 👉🏼 📑

unbanChatSenderChat

Use this method to unban a previously banned channel chat in a supergroup or channel.

unbanChatSenderChat(chatId, senderChatId, extra) 👉🏼 📑

setPassportDataErrors

Informs a user that some Telegram Passport elements they provided contains errors. The user will not be able to re-submit their Passport to you until the errors are fixed (the contents of the field for which you returned the error must change).

telegram.setPassportDataErrors(errors) 👉🏼 📑

7 - Context

Dimana itu ctx ?

Lihatlah code berikut:

bot.cmd('ping', ctx => ctx.reply('Pong!'));

Keterangan:

• ctx adalah context itu.
• reply adalah method (shorthand) untuk menghandle pesan

Berikut kerangka isi dari ctx.

Context

Context dibuat per request dan berisi beberapa properti:

Shortcuts

Context shortcuts for message update:

Context shortcuts for callback_query update:

Context shortcuts for inline_query update:

Context shortcuts for shipping_query update:

Context shortcuts for pre_checkout_query update:

Example

Check in this code:

• Normal
• Shortcode 1
• Shortcode 2

const bot = new lumpia.init(token)

bot.command('quit', (ctx) => {
  // Explicit usage
  ctx.telegram.leaveChat(ctx.message.chat.id)
})

bot.on('text', (ctx) => {
  // Explicit usage
  ctx.telegram.sendMessage(ctx.message.chat.id, `Echo: ${ctx.message.text}`)
})

bot.on('callback_query', (ctx) => {
  // Explicit usage
  ctx.telegram.answerCbQuery(ctx.callbackQuery.id)
})

bot.on('inline_query', (ctx) => {
  const result = []
  // Explicit usage
  ctx.telegram.answerInlineQuery(ctx.inlineQuery.id, result)
})

const bot = new lumpia.init(token)

bot.command('quit', (ctx) => {
  // Explicit usage
  ctx.tg.leaveChat(ctx.chat.id)
})

bot.on('text', (ctx) => {
  // Explicit usage
  ctx.tg.sendMessage(ctx.chat.id, `Echo: ${ctx.message.text}`)
})

bot.on('callback_query', (ctx) => {
  // Explicit usage
  ctx.tg.answerCbQuery(ctx.callbackQuery.id)
})

bot.on('inline_query', (ctx) => {
  const result = []
  // Explicit usage
  ctx.tg.answerInlineQuery(ctx.inlineQuery.id, result)
})

const bot = new lumpia.init(token)

bot.command('quit', (ctx) => {
  // Using context shortcut
  ctx.leaveChat()
})

bot.on('text', (ctx) => {
  // Using context shortcut
  ctx.reply(`Echo: ${ctx.message.text}`)
})

bot.on('callback_query', (ctx) => {
  // Using context shortcut
  ctx.answerCbQuery()
})

bot.on('inline_query', (ctx) => {
  const result = []
  // Using context shortcut
  ctx.answerInlineQuery(result)
})

Kesinambungan

Adalah konsep jika dimasukkan sebuah trigger, jika trigger ditemukan maka tetep diteruskan ke trigger selanjutnya.

Untuk dapat berkesinambungan, perlu dijalankan fungsi next() pada context.

• Berhenti
• Sinambung

const bot = new lumpia.init(token)

bot.cmd('ping', (ctx) => {
  // User typing: /ping
  ctx.reply('pong!')
})

// tidak akan dieksekusi
bot.cmd('ping', (ctx) => {  
  // User typing: /ping
  ctx.reply('pong 2!');
})

const bot = new lumpia.init(token)

bot.cmd('ping', (ctx, next) => {
  // User typing: /ping
  ctx.reply('pong!');
  next();
})

// perintah tetap dieksekusi
bot.cmd('ping', (ctx) => {  
  // User typing: /ping
  ctx.reply('pong 2!')
})

8 - Update Type

Update Type

Di pergunakan saat deteksi trigger on.

bot.on('message', fn);
bot.on('photo', fn);

// ... etc

Tipe update tersedia adalah sebagai berikut. Keterangan masing-masing tipe ada di dalam referensi sumber asli.

Type

• raw
• message
• edited_message
• channel_post
• edited_channel_post
• inline_query
• chosen_inline_result
• callback_query
• shipping_query
• pre_checkout_query
• poll
• poll_answer
• my_chat_member
• chat_member

Ref: update

Sub Type

• text
• reply_to_message
• reply_markup
• via_bot
• edit_date
• author_signature
• entities
• animation
• audio
• document
• photo
• sticker
• video
• video_note
• voice
• caption
• caption_entities
• media_group_id
• contact
• dice
• game
• poll
• venue
• location
• new_chat_members
• left_chat_member
• new_chat_title
• new_chat_photo
• delete_chat_photo
• group_chat_created
• supergroup_chat_created
• channel_chat_created
• message_auto_delete_timer_changed
• migrate_to_chat_id
• migrate_from_chat_id
• pinned_message
• invoice
• successful_payment
• connected_website
• passport_data
• proximity_alert_triggered
• voice_chat_scheduled
• voice_chat_started
• voice_chat_ended
• voice_chat_participants_invited

Ref: message

Entity Type

• mention @username
• hashtag #hashtag
• cashtag $USD
• bot_command /start@jobs_bot
• url https://telegram.org
• email do-not-reply@telegram.org
• phone_number +1-212-555-0123
• bold bold text
• italic italic text
• underline underlined text
• strikethrough strikethrough text
• code monowidth string
• pre monowidth block
• text_link for clickable text URLs
• text_mention for users without usernames

Ref: Entity

Tips

Informasi bot type update dapat ditemukan pada:

ctx.broadcast dan ctx.updateType

9 - Helper

Inisiasi

Untuk inisiasi awal

const helper = lumpia.helper;

// atau

const Helper = lumpia.helper;

Silakan menggunakan huruf besar atau kecil untuk konstantanya, sesuaikan sendiri dengan kebiasaan masing-masing.

Helper

Koleksi method untuk membantu saat development.

clearHTML

membersihkan text dari tags html (meng-escape), sehingga tidak terjadi error saat berada pada parse_mode HTML.

Format:

clearHTML(text)

let text = 'Bilangan 12 < 23';

let pesan = helper.clearHTML(text);

clearMarkdown

membersihkan text dari tags markdown (meng-escape), sehingga tidak terjadi error saat berada pada parse_mode markdown.

Format:

clearMarkdown(text)

let text = 'Hitungan 2 * 3 adalah 6';

let pesan = helper.clearMarkdown(text);

forEach

seperti forEach pada javascript, namun bisa dipergunakan untuk objek (JSON).

Format:

forEach(object, callback);

callback memiliki 2 parameter:

• contain
• index

var data = [ 'satu', 'dua', 'tiga']; // contoh tipe array
var data = { satu: 1, dua: 2};  // contoh tipe json

helper.forEach(data, (isi, index) => {
    console.log(index, isi);
});

isIn

Memerika apakah suatu nilai terdapat pada sebuah array

Format:

isIn(list, index)

let admin = [ 123, 456 ];
let id = msg.from.id;

if (helper.isIn(admin, id)) {
    console.log('Dia adalah admin!');
}

random

membuat hasil acak untuk bilangan atau array.

Format:

random(list);
random(min, max);

params:

• list bertipe array
• min dan max bertipe integer

let list = ['aku', 'kamu', 'dia'];

helper.random(list) // hasil acakan dari aku, kamu, atau dia
helper.random(0,100) // hasil acakan antara angka 1 - 100

textBlob

membuat text bertipe blob

Format:

textBlob(namaFile, text)

params:

• namaFile tanpa ekstensi, otomatis akan ditambahkan .txt
• text bertipe string

let blob = helper.textBlob('namaFile', 'Hasanudin H Syafaat');

Output

Tipe output pada Google Apps Script dalam mode web app.

Secara umum dapat dipergunakan untuk merespon fungsi pada doPost(e).

Ada 3 yang tersedia:

• outputText(text) menghasilkan keluaran bertipe text
• outputJSON(data) menghasilkan keluaran bertipe JSON, biasanya cocok untuk pembuatan REST API
• outputHTML(html) menghasilkan keluaran bertipe HTML, biasanya cocok untuk bertipe website biasa

nama

alias: name

menghasilkan format nama user, baik plain text ataupun html.

Format:

name(object);

return:

• first
• last
• fullname
• username
• html

 let nama = helper.name(ctx.from);
 
 console.log(nama.fullname);

typeCheck

mengecek tipe suatu variable

Format:

typeCheck(data);

let data = [ 1, 2, 3];

let tipe = helper.typeCheck(data);

console.log(tipe) // result: array
if (tipe === 'array') console.log('Data bertipe Array!');

compactOptions

membersihkan objek dari null / undefined.

Format:

compactOptions(data);

let options = { satu: 1, kosong: null, tidak: undefined };

compactOptions(options);

hasProp

Memeriksa apakah objek tertentu memiliki properti dengan nama tertentu.

Format:

hasProp(object, key);

let obj = { 'foo': 'bar', 'baz': () => {} }

hasProp(obj, 'foo') // true
hasProp(obj, 'baz') // true
hasProp(obj, 'abc') // false

hasPropType

Checks if a given object has a property with a given name.

Furthermore performs a typeof check on the property if it exists

let obj = { 'foo': 'bar', 'baz': () => {} }

hasPropType(obj, 'foo', 'string') // true
hasPropType(obj, 'baz', 'function') // true
hasPropType(obj, 'abc', 'number') // false

Button

bantuan untuk pembuatan keyboard inline, kompabilitas Lib V1/2.

Default untuk hide adalah false.

Sample belum dibikin (lagi M 🤣)

Silakan tinggalkan komentar saja jika ingin membantu melengkapi dokumentasi…