https://github.com/grom-dev/bot-api-spec
📦 Telegram Bot API specification as a JavaScript package.
https://github.com/grom-dev/bot-api-spec
telegram telegram-bot-api typescript
Last synced: 4 months ago
JSON representation
📦 Telegram Bot API specification as a JavaScript package.
- Host: GitHub
- URL: https://github.com/grom-dev/bot-api-spec
- Owner: grom-dev
- License: mit
- Created: 2025-09-27T07:46:47.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-02-11T04:32:12.000Z (4 months ago)
- Last Synced: 2026-02-11T09:49:31.091Z (4 months ago)
- Topics: telegram, telegram-bot-api, typescript
- Language: TypeScript
- Homepage:
- Size: 656 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[][bot-api]
[](https://www.npmjs.com/package/@grom.js/bot-api-spec)
[](https://jsr.io/@grom/bot-api-spec)
[Telegram Bot API][bot-api] specification as a collection of JavaScript objects in a [custom format](#format).
## Motivation
Automatically generate tools, libraries, MCP servers, custom documentations, etc.
## Installation
```sh
# Using npm
npm install @grom.js/bot-api-spec
# Using JSR
deno add jsr:@grom/bot-api-spec
```
## Usage
Root module exports two objects: `types` and `methods`, containing definitions of all Bot API types and methods respectively.
```ts
import { types, methods } from '@grom.js/bot-api-spec' // '@grom/bot-api-spec' for JSR
console.log(types)
// {
// Update: {
// name: 'Update',
// description: { markdown: '...' },
// fields: [
// {
// name: 'update_id',
// type: { type: 'int32' },
// description: { markdown: '...' },
// required: true,
// },
// ...
// ],
// },
// ...
// }
console.log(methods)
// {
// getUpdates: {
// name: 'getUpdates',
// description: { markdown: '...' },
// parameters: [
// {
// name: 'offset',
// type: { type: 'int32' },
// description: { markdown: '...' },
// required: false,
// },
// ...
// ],
// returnType: {
// type: 'array',
// of: {
// type: 'api-type',
// name: 'Update',
// },
// },
// },
// ...
// }
```
## Format
Refer to the [./src/format.ts](./src/format.ts) module for reference.
You can also import types in your code:
```ts
import type { ValueType } from '@grom.js/bot-api-spec/format' // '@grom/bot-api-spec/format' for JSR
function generateCode(valueType: ValueType): string {
if (valueType.type === 'str') {
return 'string'
}
// ...
}
```
### Value Types
We define custom value types to represent types of the fields and parameters, to allow generating more flexible and user-friendly code.
Below are the rules how we map type of a field/parameter to the `ValueType`:
- _Type_ is _String_ — `{ type: 'str' }`
- _Type_ is _Integer_ — `{ type: 'int32' }`
- _Type_ is _Integer_ and _Description_ says "...may have more than 32 significant bits...but it has at most 52 significant bits..." — `{ type: 'int53' }`
- _Type_ is _Boolean_ — `{ type: 'bool' }`
- _Type_ is _True_ — `{ type: 'bool', literal: true }`
- _Type_ is _Float_ — `{ type: 'float' }`
- _Type_ is _InputFile_ — `{ type: 'input-file' }`
- _Type_ is _X_, where X is any API type — `{ type: 'api-type', name: X }`
- _Type_ is _Array of X_ — `{ type: 'array', of: X }`
- _Type_ is _X or Y or ..._ — `{ type: 'union', types: [X, Y, ...] }`
### Descriptions
All definitions of types, methods, fields, and parameters include their descriptions.
Descriptions are copied verbatim from the official [Bot API documentation][bot-api], with the following modifications:
- Description HTML is parsed and converted to Markdown.
- The "_Optional._" prefix is omitted from field descriptions. Instead, the `required` property is set to `false` for such fields.
- "JSON-serialized..." portions are omitted from field/parameter descriptions.
- "...may have more than 32 significant bits...but it has at most 52 significant bits..." portions are omitted from _Integer_ field/parameter descriptions. Instead, the `type` is set to `int53` for such fields/parameters (as per [TDLib](https://core.telegram.org/tdlib/docs/td__api_8h.html#a6f57ab89c6371535f0fb7fec2d770126)).
[bot-api]: https://core.telegram.org/bots/api