Building
How to connect a Telegram bot to an external API
By the Botable team
A bot calls an external API from the server side, with the key held in an environment variable, results cached so repeated requests do not hit the provider, and a clear message to the user when the provider is unavailable.
The short version
Connecting a Telegram bot to an external API is straightforward and has three failure modes worth designing against before writing any of it. Credentials belong on the server, in an environment variable — a key that reaches a chat message is a key that has been published, and screenshots travel. Caching is not an optimisation but a requirement: without it, a bot with a hundred users asking for the same weather calls the provider a hundred times, and free tiers are measured in requests per minute. Caching one response for a short window turns that into a single call. And every external call fails eventually, so the bot needs a timeout and a plain message saying the provider is unavailable. Silence is the worst outcome, because the user cannot distinguish a broken provider from a broken bot and will report the wrong thing.
Step by step
Where do API keys go?
In an environment variable or a secrets manager, read at startup and used only server-side. Never in the code, never in a message, never in a log line — logs get pasted into support threads more often than anyone expects.
Why is caching mandatory rather than optional?
Because identical requests multiply by your user count. Cache by the parameters of the request for a window that suits the data — a minute for prices, an hour for weather, a day for reference data. One cached response serving fifty users is the difference between a free tier that works and one that is exhausted by lunchtime.
How should a failing API be handled?
Time out fast, retry once at most for a transient error, and then tell the user plainly that the data source is unavailable and to try shortly. Serving a stale cached value with a note about its age is often better than an error — an old price with a timestamp beats no price.
What about APIs that push instead of being polled?
Expose an endpoint the provider posts to and have the bot relay it, which is instant and costs nothing while idle. Verify a shared secret on every incoming request, because a public endpoint that relays into your chat is an open pipe otherwise.
What catches people out
- One uncached lookup per user multiplies your request count by your audience
- A silent failure is indistinguishable from a broken bot; always say something
- Log lines containing keys end up in support threads — redact before you log
Questions
Can a bot call an API that needs OAuth?
Yes, but the user has to authorise it, which means a web step outside the chat and somewhere to store the resulting token per user. That is a materially bigger build than a shared API key and worth scoping deliberately.
What if the API is slow?
Acknowledge immediately — a short "fetching…" that you then edit with the result — so the user is not staring at nothing. A reply that takes eight seconds with no acknowledgement reads as a failure.
Want a bot that does this?
Describe it in plain language and Botable writes the code, gives the bot its own database, deploys it and keeps it running. Everything on this page is handled for you — the token, the webhook, the storage, the hosting.