ApiClientOptions

^{ref / core / ApiClientOptions}

Options to pass to the API client that eventually connects to the Telegram Bot API server and makes the HTTP requests.

^Source

Properties

apiRoot

apiRoot?: string;

Root URL of the Telegram Bot API server. Default: https://api.telegram.org

^Source

environment

environment?: "prod" | "test";

Specifies whether to use the test environment. Can be either "prod" (default) or "test".

The testing infrastructure is separate from the regular production infrastructure. No chats, accounts, or other data is shared between them. If you set this option to "test", you will need to make your Telegram client connect to the testing data centers of Telegram, register your phone number again, open a new chat with @BotFather, and create a separate bot.

^Source

buildUrl

buildUrl?: (
  root: string,
  token: string,
  method: string,
  env: "prod" | "test",
) => string | URL;

URL builder function for API calls. Can be used to modify which API server should be called.

^Source

timeoutSeconds

timeoutSeconds?: number;

Maximum number of seconds that a request to the Bot API server may take. If a request has not completed before this time has elapsed, grammY aborts the request and errors. Without such a timeout, networking issues may cause your bot to leave open a connection indefinitely, which may effectively make your bot freeze.

You probably do not have to care about this option. In rare cases, you may want to adjust it if you are transferring large files via slow connections to your own Bot API server.

The default number of seconds is 500, which corresponds to 8 minutes and 20 seconds. Note that this is also the value that is hard-coded in the official Bot API server, so you cannot perform any successful requests that exceed this time frame (even if you would allow it in grammY). Setting this option to higher than the default only makes sense with a custom Bot API server.

^Source

canUseWebhookReply

canUseWebhookReply?: (method: string) => boolean;

If the bot is running on webhooks, as soon as the bot receives an update from Telegram, it is possible to make up to one API call in the response to the webhook request. As a benefit, this saves your bot from making up to one HTTP request per update. However, there are a number of drawbacks to using this:

1. You will not be able to handle potential errors of the respective API call. This includes rate limiting errors, so sent messages can be swallowed by the Bot API server and there is no way to detect if a message was actually sent or not.
2. More importantly, you also won’t have access to the response object, so e.g. calling sendMessage will not give you access to the message you sent.
3. Furthermore, it is not possible to cancel the request. The AbortSignal will be disregarded.
4. Note also that the types in grammY do not reflect the consequences of a performed webhook callback! For instance, they indicate that you always receive a response object, so it is your own responsibility to make sure you’re not screwing up while using this minor performance optimization.

With this warning out of the way, here is what you can do with the canUseWebhookReply option: it can be used to pass a function that determines whether to use webhook reply for the given method. It will only be invoked if the payload can be sent as JSON. It will not be invoked again for a given update after it returned true, indicating that the API call should be performed as a webhook send. In other words, subsequent API calls (during the same update) will always perform their own HTTP requests.

^Source

baseFetchConfig

baseFetchConfig?: Omit<NonNullable<Parameters<typeof fetch>[1]>, "method" | "headers" | "body">;

Base configuration for fetch calls. Specify any additional parameters to use when fetching a method of the Telegram Bot API. Default: { compress: true } (Node), {} (Deno)

^Source

sensitiveLogs

sensitiveLogs?: boolean;

When the network connection is unreliable and some API requests fail because of that, grammY will throw errors that tell you exactly which requests failed. However, the error messages do not disclose the fetched URL as it contains your bot’s token. Logging it may lead to token leaks.

If you are sure that no logs are ever posted in Telegram chats, GitHub issues, or otherwise shared, you can set this option to true in order to obtain more detailed logs that may help you debug your bot. The default value is false, meaning that the bot token is not logged.

^Source