API Overview
Bot API is an HTTPS interface for bot developers. Your server receives user interactions, performs business logic, and returns content to private chats, groups, or channels through the API.
- Suitable for notification, customer service, query and automation tools
- Supports messages, commands, buttons and inline interactions
- Robot credentials should only be saved on the controlled server
- Users must first initiate a session or add a robot
Access preparation
1. Create a robot
Set the name, username and introduction according to Potato's current robot creation process, and obtain the authorization token.
2. Prepare HTTPS service
Deploy a stable server to receive updates, verify parameters, perform tasks and send responses. Development, test and production environments should be isolated.
3. Management Configuration
Tokens, callback keys and environment parameters are injected through key management or environment configuration and are prohibited from being submitted to the code repository.
// Concept example: actual fields and methods are subject to official documents. const update = verifyIncomingRequest(request) const command = parseCommand(update.message) const result = await runBusinessLogic(command) await potatoBot.sendMessage(update.chatId, result)
Processing updates
Treat each update as an event that may be duplicated, delayed, or arrive out of order. Use update IDs to deduplicate, set up queues for time-consuming tasks, and retry safely after timeouts.
- First verify the source, format and necessary fields.
- Quickly confirm requests and hand over time-consuming operations to background tasks.
- Log event identifiers, results, and errors, but avoid logging sensitive text.
- Set reasonable traffic limits for the same user, group and interface.
Common capabilities
| Capabilities | Typical uses | Implementation points |
|---|---|---|
Send message | Notifications, replies, result output | Handling format, length and delivery failure |
Commands | /start, /help and business commands | Parameter verification and permission check |
Callback button | Set, turn pages, confirm operations | Avoid duplicate submissions and respond promptly |
Inline Query | Search and send content across sessions | Fast return, caching and result paging |
Group Events | Members, permissions and service messages | Abide by group privacy mode |
Errors and Retries
Distinguish between parameter errors, permission errors, current limiting, temporary network failures and server errors. Only use exponential backoff with jitter for recoverable problems and set a maximum number of times.
Security requirements
- Tokens will be rotated immediately after leakage and abnormal calls will be checked.
- Conduct secondary authentication for management commands, payments or high-risk actions.
- Save only the data required to complete the service and set a deletion cycle.
- Validate and filter user input, URLs, files, and rich text.
- Enable HTTPS, throttling, log alerts, and availability monitoring for the interface.