If you run a community, manage project progress, or need to send content to subscribers regularly, doing everything manually is often time-consuming and labor-intensive. The Bot API provided by Potato can hand this kind of repetitive work over to a bot, letting your team focus on more valuable things. This article uses real-world scenarios to walk you through the basics.
What the Bot API Can Do: Three Typical Scenarios
Bots aren't just for auto-replies. The following use cases are common among teams and creators:
- Scheduled pushes and reminders: For example, sending a to-do list to the project group at 9 a.m. every Monday, or sending a private message to remind students 30 minutes before a course starts.
- Data queries and feedback: Members type "/status" in the group and the bot returns the current task completion rate; creators use "/stats" to check yesterday's new subscriber count.
- Content distribution and collection: The bot automatically forwards new articles to multiple channels, or collects links and images submitted by users and organizes them into a table.
Behind all these operations is the same logic: listen for message events and call the API to perform actions. Potato's Bot API is based on HTTPS requests and returns JSON data, so it can be integrated with any language.
Starting from Scratch: Get a Token and Send Your First Message
First, search for @BotFather inside Potato and create a bot. You'll receive a token, for example 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. This token is essentially the bot's password, so don't leak it.
The endpoint for sending messages is https://api.potato.im/bot{token}/sendMessage, and it requires two parameters: chat_id (the target conversation ID) and text (the message content). Test it with curl:
curl -X POST https://api.potato.im/bot/sendMessage -d "chat_id=123456789&text=Hello"
If it returns {"ok":true}, the bot has successfully sent the message. Note that a bot can only send messages to users who have actively talked to it or to groups it belongs to; it cannot randomly message strangers.
Handling User Input: Receiving Updates with Webhooks
To make the bot respond to user messages, there are two approaches: polling (getUpdates) or Webhooks. Polling is suitable for local testing, while Webhooks are suitable for online services. Setting up a Webhook only requires one call:
curl -X POST https://api.potato.im/bot/setWebhook -d "url=https://yourdomain.com/potato-webhook"
After that, every message a user sends to the bot will be pushed to your server as a POST request. By parsing message.text and message.chat.id in the JSON, you can decide what to reply. A common pitfall is that the Webhook must use HTTPS with a valid certificate, otherwise Potato will refuse to push updates.
Rate Limits and Practical Tips
Potato imposes rate limits on bot messages: a single bot can send at most 1 message per second to the same conversation, and no more than 30 messages per second globally. If you exceed this, the API returns a 429 error, and you need to wait retry_after seconds before retrying. When sending in bulk, it's recommended to split users into small groups and leave a 1-second interval between groups to avoid triggering the limit.
In addition, bots cannot read historical messages in a group; they can only receive new messages after the Webhook is set up. If you need to persist data, prepare your own database and store chat_id, user input, and timestamps.
For creators, a very practical automation is to automatically forward new articles from an RSS feed to a Potato channel. Write a scheduled script that checks the feed every 10 minutes and calls sendMessage when it finds a new link. The whole process takes less than 50 lines of code, yet it saves the hassle of manually copying and pasting every day.
For team collaboration, you can build a simple on-call bot: members send "/oncall" to check in, and the bot records the time and calculates response duration. Accumulated over time, this data can help optimize shift scheduling.
If you haven't tried Potato's bot features yet, start with a minimal need, such as sending a daily weather reminder at a fixed time. Once you're familiar with the API, expand step by step. Potato's Bot API documentation on the official website has detailed parameter descriptions, and if you run into problems, you can also ask in the official community.
