CodeCast-Duo Telegram Bot API

Content

0. Introduction
1. Installation
2. Telegram API - Usage Guide
   1. Creating an Instance
   2. Configuring TelegramOptions
      1. TelegramOptions Table
      2. OptionsUpdate Sub-Table
      3. OptionsPollingWaitManage Sub-Table
3. API Methods
   1. onMessage Method
   2. onUpdate Method
   3. onText Method
   4. startUpdater Method
   5. stopUpdater Method
4. Event Types
   1. Message Types Table
   2. Update Types Table
5. Examples
6. Advanced Topics
   1. Error types
   2. Error handling
   3. Description TelegramError class
      1. Properties Table TelegramError
7. Polling Wait Manager
   1. Using Polling Wait Manager
   2. Polling Wait Manager Methods

Introduction

Welcome to the CodeCast-Duo Telegram Bot API, an advanced and sophisticated toolset exclusively developed for the CodeCast-Duo organization. This API embodies a comprehensive suite of functionalities, meticulously crafted to cater to the specific requirements of our organizational framework. It is a pivotal asset in streamlining Telegram bot development and management, ensuring that our bots align seamlessly with the operational and strategic objectives of CodeCast-Duo. This documentation serves as a detailed guide, assisting our developers in harnessing the full potential of this bespoke API.

Installation

To install the package, simply run the following command in your project directory:

npm i @codecast-duo/codecast-duo-telegrambot

This command installs the CodeCast-Duo Telegram Bot package, adding it to your project's dependencies.

Telegram API - Usage Guide

Creating an Instance of TelegramAPI

To start using the Telegram API, you need to create an instance of the TelegramAPI class. This is done using the constructor, which takes an object of type TelegramOptions as its argument. This object contains several configurations that determine how your API instance will behave.

Example

const { Telegram, TelegramError } = require('@codecast-duo/codecast-duo-telegrambot');

// Create a new instance of the Telegram bot
const bot = new Telegram({
    telegramToken: "TELEGRAM_TOKEN",
    // Other TelegramOptions fields as needed
});

Configuring TelegramOptions

The TelegramOptions object contains various settings that are crucial for the operation of your Telegram bot. Here are the key options you need to configure:

TelegramOptions Table

| Option | Type | Description | Default Value | |----|:----:|----------------|---| | telegramToken | string | The unique token for your Telegram bot, provided by BotFather. | None (Mandatory) | | telegramApi | string | Optional. The URL of the Telegram API. If not specified, the default URL is used. | 'https://api.telegram.org' | | start | boolean | Optional. Determines whether the bot starts processing messages immediately after instantiation. If false use startUpdaters to start polling updates. | true | | optionUpdate | OptionsUpdate | Optional. Configuration for receiving updates, including offset, allowed updates, and limit on updates. | OptionsUpdate Sub-Table | | optionPollingWaitManager | OptionsPollingWaitManage | Optional. Settings for managing the wait time between polling, including max wait time and timeout action. | OptionsPollingWaitManage Sub-Table |

OptionsUpdate Sub-Table

| Option | Type | Description | Default Value | |----------------|:------:|----------------|----| | offset | number | Optional. Identifier of the first update to be returned. | 0 | | allowed_updates | Array<keyof UpdateTypes> | Optional. List of update types to be received. Specify an empty list to receive all update types except chat_member, message_reaction, and message_reaction_count (default). If not specified, the previous setting will be used. Please note that this parameter doesn't affect updates created before the call to the getUpdates, so unwanted updates may be received for a short period of time. | [] | | limit | number | Optional. Limits the number of updates to be retrieved. | 100 |

OptionsPollingWaitManage Sub-Table

| Option | Type | Description | Default Value | |----------------|:------:|----------------|----| | maxWaitTime | number | Optional. The maximum waiting time (in milliseconds) allowed before considering the polling process as too long and taking action. | 60000 (60 seconds) | | onWait | number | Optional. A callback function that gets executed when the waiting time exceeds maxWaitTime. It allows you to define custom actions or error handling when polling takes too long. | Empty function (() => {}) |

Example

const options = {
    telegramToken: 'YOUR_TELEGRAM_BOT_TOKEN',
    telegramApi: 'https://api.telegram.org',
    start: true,
    optionUpdate: {
        offset: 0,
        allowed_updates: ['message', 'callback_query'],
        limitUpdates: 100
    },
    optionPollingWaitManager: {
        maxWaitTime: 3000,
        onWaitTooLong: () => { /* Handle long wait times */ }
    }
};

API Methods

The onMessag, onUpdate and onText are key methods used in the CodeCast-Duo Telegram Bot API for handling various types of events:

onMessage Method

• onMessage<K extends TelegramTypes.MessageTypesKeys>(event: K, listener: (arg: TelegramTypes.Message[K], message: TelegramTypes.Message) => void): Promise<TelegramTypes.Message>: This method is used to listen for message-related events. It takes an event type and a listener function as arguments. The event type is one of the keys from TelegramTypes.MessageTypesKeys, and the listener function receives the specific message type and the general message object.

onUpdate Method

• onUpdate<K extends TelegramTypes.UpdateTypesKeys>(event: K, listener: (arg: TelegramTypes.Update[K], update: TelegramTypes.Update) => void): Similar to onMessage, this method listens for update-related events. It takes an event type from TelegramTypes.UpdateTypesKeys and a listener function. The listener function is invoked with the specific update type and the general update object.

onText Method

• onText(regexp: RegExp | string, callback: (arg: TelegramTypes.Message) => void): This method is designed to detect and respond to specific text patterns in messages. It takes two parameters:

| Parameter | Description | | --- | --- | | regexp | A RegExp or string pattern that the incoming text message must match. | | callback | A function that is called when a message matching the regexp is received. This function takes a TelegramTypes.Message object as its argument, providing details about the matched message. |

editMessageText Method

• editMessageText(options: TelegramTypes.EditMessageTextType): Promise<TelegramTypes.Message>: This method is used to edit the text of an already sent message. It takes an options object which contains parameters for editing the message text. More details about the parameters that can be passed in options can be found here.

startUpdater Method

• startUpdater(): void: This method is used to start the polling process for updates. It initiates the bot's ability to listen for incoming updates from Telegram. This is particularly useful when your bot is set up to not start automatically, or if you've previously stopped the update polling and need to restart it.

stopUpdater Method

• stopUpdater(): Promise<void>: The stopUpdaters method is used to stop the polling process. This is useful when you want to temporarily halt your bot from listening to incoming updates, without shutting down the entire bot. This can be handy during maintenance, updating bot logic, or handling unexpected behavior.

Event Types

Message Types Table

| Event | Description | Return Type | |---|:-----------:|---| | text | Handles text messages sent in the chat. | string | | animation | Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound). | TelegramTypes.Animation | | audio | Represents an audio file to be treated as music. | TelegramTypes.Audio | | channel_chat_created | Indicates if a channel chat was created. | boolean | | contact | Represents a phone contact. | TelegramTypes.Contact | | delete_chat_photo | Indicates if a chat photo was deleted. | boolean | | dice | Represents an animated emoji that displays a random value. | TelegramTypes.Dice | | document | Represents a general file (as opposed to photos, voice messages, and audio files). | TelegramTypes.Document | | game | Describes a game within the Telegram platform. | TelegramTypes.Game | | group_chat_created | Indicates if a group chat was created. | boolean | | invoice | Represents an invoice for a payment. | TelegramTypes.Invoice | | left_chat_member | Represents a user who left the chat. | TelegramTypes.User | | location | Represents a point on the map. | TelegramTypes.Location | | migrate_from_chat_id | Indicates the chat ID from which a chat was migrated. | number | | migrate_to_chat_id | Indicates the new chat ID to which a chat was migrated. | number | | new_chat_members | Indicates new members added to the chat. | TelegramTypes.User[] | | new_chat_photo | Represents a new chat photo update. | TelegramTypes.PhotoSize[] | | new_chat_title | Reflects an update to the chat's title. | string | | passport_data | Contains information for Telegram Passport data. | TelegramTypes.PassportData | | photo | Refers to photo messages. | TelegramTypes.PhotoSize[] | | pinned_message | Indicates a message that has been pinned in the chat. | TelegramTypes.Message | | poll | Contains information about a poll. | TelegramTypes.Poll | | sticker | Represents a sticker sent in the chat. | TelegramTypes.Sticker | | successful_payment | Indicates a successful payment transaction. | TelegramTypes.SuccessfulPayment | | supergroup_chat_created | Indicates if a supergroup chat was created. | boolean | | video | Represents a video file. | TelegramTypes.Video | | video_note | Represents a video message. | TelegramTypes.VideoNote | | voice | Represents a voice note. | TelegramTypes.Voice | | video_chat_ended | Indicates that a video chat in the chat has ended. | TelegramTypes.VideoChatEnded | | video_chat_participants_invited | Informs about new members invited to a video chat. | TelegramTypes.VideoChatParticipantsInvited | | video_chat_scheduled | Represents a service message about a video chat scheduled in the chat. | TelegramTypes.VideoChatScheduled | | message_auto_delete_timer_changed | Notifies about a change in auto-delete timer settings in a chat. | TelegramTypes.MessageAutoDeleteTimerChanged | | web_app_data | Describes data sent from a Web App to the bot. | TelegramTypes.WebAppData |

Update Types Table

| Event | Description | Return Type | |----|:---------:|----------------| | message | New incoming message of any kind - text, photo, sticker, etc. | TelegramTypes.Message | | channel_post | New incoming channel post of any kind (text, photo, sticker, etc.). | TelegramTypes.Message | | poll | New poll state. Bots receive only updates about stopped polls and polls sent by the bot. | TelegramTypes.Poll | | callback_query| Incoming callback query from a callback button in an inline keyboard. | TelegramTypes.CallbackQuery | | chat_join_request| A request to join the chat has been sent. | TelegramTypes.ChatJoinRequest |

Examples

Here's a basic guide on how to use the CodeCast-Duo Telegram Bot API in your project:

// Import the required TelegramBot library
const { Telegram, TelegramError } = require('@codecast-duo/codecast-duo-telegrambot');

// Create a new instance of the Telegram bot
const bot = new Telegram({
    telegramToken: "TELEGRAM_TOKEN",
});

// Event listener for incoming text messages
bot.onMessage('text', (parameter, message) => {
    // Define the structure of the inline keyboard markup
    const inlineKeyboardMarkup = {
        reply_markup: {
            inline_keyboard: [
                [{ text: 'Test1', callback_data: 'Callback data test1' }],
                [{ text: 'Test2', callback_data: 'Callback data test2' }]
            ]
        }
    };

    // Send a message back to the chat with the inline keyboard
    bot.sendMessage(message.chat.id, (parameter || 'if parameter empty'), inlineKeyboardMarkup).then((message) => {
        setTimeout(() => {
            bot.editMessageText({
                text: "Test",
                chat_id: message.chat.id,
                message_id: message.message_id,
                reply_markup: {
                    inline_keyboard: [
                        [{ text: 'TestNew1', callback_data: 'Callback data testNew1' }],
                        [{ text: 'TestNew2', callback_data: 'Callback data testNew2' }]
                    ]
                }
            })
        }, 1000);
    }).catch(
        (error) => {
            // Handle errors specifically related to Telegram
            if (error instanceof TelegramError) {
                console.log(error.message);
            } else {
                // Handle any other generic errors
                console.log("is default error");
            }
        }
    )
});

// Event listener for callback queries (e.g., when an inline button is pressed)
bot.onUpdate('callback_query', (callback, update) => {
    // Respond to the callback query
    bot.sendMessage(callback.from.id, (callback.data || 'if callback.data empty'));
    console.log(callback.data);
});

// Check the bot's information (e.g., username)
bot.getMe().then(user => {
    // Log success if user data is retrieved
    if (user) {
        console.log("connected");
    }
});

// Global error event listener
bot.on('error', (error) => {
    // Log any errors encountered
    console.error(error);
});

// Specific error event listener for network-related errors
bot.on('error-NetworkError', (error) => {
    // Log network errors separately
    console.error(error);
});

// Event listener for text commands (e.g., "/echo some text")
bot.onText(/\/echo (.+)/, (message) => {
    // Log the text following the echo command
    console.log(message.text);
});

Advanced Topics

Error types

Below is a table describing the different types of errors (TelegramErrorTypes) that can occur when interacting with the Telegram API, along with a brief description of each error type:

| Error Type | Description | |------------------------------|-------------| | NetworkError | Occurs when there is a problem with the network connection, such as a failure to reach the Telegram servers. | | ApiError | This error is thrown when there is an issue with the API request, such as invalid parameters or authentication issues. | | TimeoutError | Occurs when a request to the Telegram API takes too long to respond, exceeding the predefined timeout limit. | | InternalServerError | Indicates a problem on the Telegram server side, such as a server malfunction or maintenance. | | ParsingError | This error is encountered when there is an issue in parsing the response from the Telegram API. | | UnhandledPromiseRejection| Occurs when a Promise in the code is rejected but not properly handled with a catch block. | | UnknownError | Used as a catch-all for any errors that do not fit into the other predefined categories. |

Error handling

In your Telegram bot implementation, you can set up error handling in two primary ways:

1. Catch All Errors: Use bot.on('error', (error) => {}); to handle all types of errors. This is a general error handler that will catch any error thrown by the bot, regardless of its type. It's useful for logging or handling errors in a generic way.

   bot.on('error', (error) => {
       console.error('An error occurred:', error);
       // Additional error handling logic can go here
   });

2. Catch Specific Types of Errors: Use bot.on('error-TelegramErrorTypes', (error) => {}); to handle specific types of errors. This allows for more granular error handling based on the error type. For example, you can have different handlers for NetworkError, ApiError, etc.

   // Handling NetworkError specifically
   bot.on('error-NetworkError', (error) => {
       console.error('Network Error:', error);
       // Specific handling for network errors
   });
   
   // Handling ApiError specifically
   bot.on('error-ApiError', (error) => {
       console.error('API Error:', error);
       // Specific handling for API errors
   });
   
   // ... similarly for other error types

3. Catch from onMessage(), onUpdate(), onText (): In the context of Telegram bot development using the described library, methods like onMessage, onUpdate, and onText typically return a Promise. The resolution of these promises is usually void, meaning they do not return any value upon successful completion. However, in case of an error, these methods can throw an exception, which is caught in the catch block.

When you use these methods, it's a good practice to handle potential errors that might occur during their execution. This error handling is usually done by attaching a catch block to the promise. The error caught is typically an instance of the TelegramError class, which provides details about what went wrong.

Here's how you might structure your code to include error handling with these methods:

// Handling incoming text messages
 bot.onMessage('text', (parameter, message) => {
     // Logic to handle the message
     // ...
 }).catch(error => {
     if (error instanceof TelegramError) {
         console.error('TelegramError occurred:', error.message);
     } else {
         console.error('Unknown error occurred:', error);
     }
 });

Description TelegramError

The TelegramError class provides a structured way to handle errors encountered during Telegram bot operations. It encapsulates details about the error, including its type and, if available, a specific error code. This class can handle different types of errors, such as network issues or API-related problems, and can be instantiated with detailed information about the underlying error.

Properties Table TelegramError

| Parameter | Type | Description | |----|----|----| | error_code | string | undefined | An optional code that provides additional information about the error. This is typically specific to the type of error encountered. | | type | TelegramErrorTypes | The type of the error, categorized as one of the predefined TelegramErrorTypes, such as NetworkError, ApiError, etc. | | message | string | Inherited from the base Error class, this property contains a message describing the error. | | stack | string | undefined | Also inherited from the base Error class, this property provides a stack trace at the point where the error was instantiated, if available. |

Polling Wait Manager

The "Polling Wait Manager" is a crucial component utilized for the efficient management of the polling process in applications that communicate with a remote server through polling. Polling involves sending periodic requests to a server to retrieve updates or data. The Polling Wait Manager plays a pivotal role in ensuring the effective control of this polling process and handling pauses in the operation of an application.

Using Polling Wait Manager

The Polling Wait Manager proves to be invaluable in applications that depend on polling to receive updates or data from a remote server. It serves to guarantee the efficient and optimal management of polling, dynamically turning it off when not required. This not only conserves valuable resources but also prevents excessive server load.

TelegramAPI Class and Polling Wait Manager

The TelegramAPI class offers a seamless integration with the Polling Wait Manager, empowering you to take charge of the polling process. Here is an overview of the available methods along with their descriptions:

Polling Wait Manager Methods

• getPollingWaitManager(): PollingWaitManager | undefined: The getPollingWaitManager method provides the means to fetch the current Polling Wait Manager object or returns undefined if it hasn't been initialized.

• setPollingWaitManager(name: string, func: () => boolean): void: With the setPollingWaitManager method, you can effortlessly create or modify a function within the Polling Wait Manager. This function requires the name of the function and a callback function that should return a boolean value. If the Polling Wait Manager doesn't exist, this method will create it dynamically.

• removePollingWaitManager(name: string): void The removePollingWaitManager method allows you to selectively remove a function from the Polling Wait Manager by specifying its name. This function deletion process is seamless and effective.

These methods are instrumental in efficiently managing the polling process within your application by defining conditions under which polling should continue or cease. They serve as invaluable tools for optimizing the operation of applications reliant on polling to receive updates or data.

Examples 1: Initializing and Using Polling Wait Manager

Here's a basic guide on how to use the CodeCast-Duo Telegram Bot API in your project:

const { Telegram } = require('@codecast-duo/codecast-duo-telegrambot');

const bot = new Telegram({
    telegramToken: "TELEGRAM_TOKEN",
});

const pollingWaitManager = bot.getPollingWaitManager();

let continuePolling= false;

function shouldContinuePolling() {
    return continuePolling;
}

setTimeout(() => {
        continuePolling = true;
    }, 30000);

bot.setPollingWaitManager("exampleFunction", shouldContinuePolling);

In this example, we initialize the TelegramAPI instance, retrieve the Polling Wait Manager, define a function (shouldContinuePolling) that determines whether polling should continue, set this function in the Polling Wait Manager.

Examples 2: Removing a Polling Function

bot.removePollingWaitManager("exampleFunction");

In this example, we remove a polling function named "exampleFunction" from the Polling Wait Manager. This function will no longer be used to determine whether polling should continue.