feat: custom bot api server url for telegram

[zaralX]

Description

Adds an optional tg bot API server URL to the telegram integration, for people who cant reach api.telegram.org or run their own telegram bot api.

• New serverUrl field next to the bot token. Empty means https://api.telegram.org, so nothing changes for existing setups.
• Messages go to {serverUrl}/bot{token}/sendMessage. A path prefix works too, a query, fragment, or credentials in the URL are rejected.
• A custom server goes through the same private-address check as ntfy/gotify. Plain http is refused unless KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS is set, because the token is part of the URL. Same rule as the GitLab URL.
• Changing the server URL on an existing integration requires the bot token again, otherwise a saved token could be sent to a new host. Same as the GitLab check from fix(security): close permission and integration gaps #1802.
• Docs: new "Custom Bot API server" section, getUpdates note for custom servers, env var description.

No migration and no new environment variables, the config is already JSON.

Related Issue(s)

Fixes #1722

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update
• Test addition or update

How Has This Been Tested?

• Unit tests
• Integration tests
• Manual testing

Tests cover URL validation, the request URL with and without a custom server, refusing http and private addresses, and the token requirement when the server changes.

Screenshots (if applicable)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I understand and take responsibility for every change, and I wrote this pull request description in my own words
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Additional Notes

Untranslated strings stay as English placeholders, ru-RU is translated.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Support custom Telegram Bot API server URLs

✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Adds optional custom Telegram Bot API servers while preserving official defaults.
• Enforces URL, transport, SSRF, and token re-entry safeguards.
• Extends settings, API contracts, documentation, translations, and security-focused tests.

Diagram

sequenceDiagram
  actor Admin
  participant Web as Settings UI
  participant API as Integration API
  participant Config as URL Validator
  participant Store as Config Store
  participant Events as Event Handler
  participant Outbound as Outbound Guard
  participant Bot as Bot API Server
  Admin->>Web: Enter server and token
  Web->>API: Create or update
  API->>Config: Normalize and validate
  Config-->>API: Validated config
  API->>Store: Persist JSON config
  Events->>Store: Load integration
  Events->>Outbound: Send configured message
  Outbound->>Bot: Guarded sendMessage

Loading

High-Level Assessment

The optional normalized base URL is the appropriate approach because it preserves existing configurations without a migration, supports path-prefixed proxies, and reuses the established outbound destination guard. A full endpoint template or separate integration type would add configuration complexity and increase token-handling risk without meaningful benefit.

Files changed (38) +554 / -62

Enhancement (11) +192 / -12

client.tsRoute messages through optional custom Bot API servers +11/-2

Route messages through optional custom Bot API servers

• Builds sendMessage requests from the configured server URL or the official Telegram default. Custom destinations receive transport validation and the existing public-destination SSRF check.

apps/api/src/plugins/telegram/client.ts

config.tsValidate and normalize Telegram server URLs +42/-0

Validate and normalize Telegram server URLs

• Adds the official API constant and optional serverUrl configuration. Rejects unsupported protocols, credentials, queries, and fragments, trims trailing slashes, and restricts plain HTTP unless private destinations are enabled.

apps/api/src/plugins/telegram/config.ts

events.tsPass configured server URL during event delivery +11/-7

Pass configured server URL during event delivery

• Forwards the integration's optional server URL when posting generated event messages to Telegram.

apps/api/src/plugins/telegram/events.ts

telegram-controller.tsSecure Telegram server URL configuration changes +35/-0

Secure Telegram server URL configuration changes

• Adds serverUrl patch handling and response serialization. Requires the bot token again when changing hosts and validates transport policy before accepting a new destination.

apps/api/src/telegram-integration/controllers/telegram-controller.ts

index.tsApply server safeguards in Telegram API routes +13/-3

Apply server safeguards in Telegram API routes

• Accepts serverUrl during create and update operations and invokes server-change validation. OpenAPI route descriptions now document URL validation and token re-entry failures.

apps/api/src/telegram-integration/index.ts

response.tsExpose Telegram server URL in API responses +4/-0

Expose Telegram server URL in API responses

• Adds a nullable serverUrl field to the Telegram integration response schema, with null representing the official API.

apps/api/src/telegram-integration/response.ts

schema.tsAdd server URL to Telegram request schemas +8/-0

Add server URL to Telegram request schemas

• Adds optional serverUrl creation input and nullable patch input. The update contract documents that changing the server requires resupplying the bot token.

apps/api/src/telegram-integration/schema.ts

telegram-integration-settings.tsxAdd custom server field to Telegram settings +65/-0

Add custom server field to Telegram settings

• Adds server URL form state, validation, normalization, and request mapping. Existing integrations must re-enter their bot token before changing the configured server.

apps/web/src/components/project/telegram-integration-settings.tsx

create-telegram-integration.tsType custom server creation requests +1/-0

Type custom server creation requests

• Adds the optional serverUrl field to Telegram integration creation requests.

apps/web/src/fetchers/telegram-integration/create-telegram-integration.ts

get-telegram-integration.tsType server URL in Telegram responses +1/-0

Type server URL in Telegram responses

• Adds the nullable serverUrl field to the web client's Telegram integration model.

apps/web/src/fetchers/telegram-integration/get-telegram-integration.ts

update-telegram-integration.tsType server URL update requests +1/-0

Type server URL update requests

• Adds optional nullable serverUrl support to Telegram integration update requests.

apps/web/src/fetchers/telegram-integration/update-telegram-integration.ts

Tests (2) +181 / -0

telegram-server-url.test.tsTest Telegram server URL validation and delivery +104/-0

Test Telegram server URL validation and delivery

• Covers URL normalization and rejection rules, official and custom request construction, HTTP restrictions, and private-address blocking.

tests/api/plugins/telegram-server-url.test.ts

telegram-controller.test.tsTest secure Telegram server configuration updates +77/-0

Test secure Telegram server configuration updates

• Covers omitted and cleared server patches, token requirements on destination changes, unrelated updates, and conditional HTTP allowance.

tests/api/telegram-integration/telegram-controller.test.ts

Documentation (5) +43 / -12

ENVIRONMENT_SETUP.mdDocument Telegram private-destination behavior +1/-1

Document Telegram private-destination behavior

• Extends the private-network receiver summary to include custom Telegram Bot API servers under the existing environment flag.

ENVIRONMENT_SETUP.md

environment-variables.mdxExplain Telegram effects of private-destination flag +1/-1

Explain Telegram effects of private-destination flag

• Documents that the existing flag permits private Telegram Bot API servers and plain HTTP for trusted GitLab and Telegram destinations.

apps/docs/core/installation/environment-variables.mdx

outgoing-webhooks.mdxClarify getUpdates for custom Telegram servers +1/-1

Clarify getUpdates for custom Telegram servers

• Directs users of custom Bot API servers to retrieve chat details from the equivalent getUpdates path on their server.

apps/docs/core/integrations/outgoing-webhooks.mdx

telegram.mdxDocument custom Telegram Bot API setup +16/-6

Document custom Telegram Bot API setup

• Adds setup instructions, endpoint construction, HTTPS and private-network requirements, and the token re-entry rule when changing servers.

apps/docs/core/integrations/telegram.mdx

openapi.jsonRegenerate OpenAPI contract for serverUrl +24/-3

Regenerate OpenAPI contract for serverUrl

• Publishes serverUrl across Telegram create, update, and response schemas. Updates endpoint descriptions and validation error documentation.

apps/docs/openapi.json

Other (20) +138 / -38

az-AZ.jsonAdd Azerbaijani Telegram server strings +7/-2

Add Azerbaijani Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/az-AZ.json

de-DE.jsonAdd German Telegram server strings +7/-2

Add German Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/de-DE.json

el-GR.jsonAdd Greek Telegram server strings +7/-2

Add Greek Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/el-GR.json

en-US.jsonAdd English Telegram server copy +6/-1

Add English Telegram server copy

• Adds labels, placeholders, hints, invalid-URL feedback, and token re-entry guidance for the new server field.

i18n/en-US.json

es-ES.jsonAdd Spanish Telegram server strings +7/-2

Add Spanish Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/es-ES.json

fr-FR.jsonAdd French Telegram server strings +7/-2

Add French Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/fr-FR.json

hi-IN.jsonAdd Hindi Telegram server strings +7/-2

Add Hindi Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/hi-IN.json

id-ID.jsonAdd Indonesian Telegram server strings +7/-2

Add Indonesian Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/id-ID.json

it-IT.jsonAdd Italian Telegram server strings +7/-2

Add Italian Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/it-IT.json

ja-JP.jsonAdd Japanese Telegram server strings +7/-2

Add Japanese Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/ja-JP.json

ko-KR.jsonAdd Korean Telegram server strings +7/-2

Add Korean Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/ko-KR.json

mk-MK.jsonAdd Macedonian Telegram server strings +7/-2

Add Macedonian Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/mk-MK.json

nl-NL.jsonAdd Dutch Telegram server strings +7/-2

Add Dutch Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/nl-NL.json

pl-PL.jsonAdd Polish Telegram server strings +7/-2

Add Polish Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/pl-PL.json

pt-BR.jsonAdd Brazilian Portuguese Telegram server strings +7/-2

Add Brazilian Portuguese Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/pt-BR.json

ru-RU.jsonAdd Russian Telegram server translations +6/-1

Add Russian Telegram server translations

• Adds localized labels, guidance, invalid-URL feedback, and token re-entry messaging for custom server configuration.

i18n/ru-RU.json

tr-TR.jsonAdd Turkish Telegram server strings +7/-2

Add Turkish Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/tr-TR.json

uk-UA.jsonAdd Ukrainian Telegram server strings +7/-2

Add Ukrainian Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/uk-UA.json

vi-VN.jsonAdd Vietnamese Telegram server strings +7/-2

Add Vietnamese Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/vi-VN.json

zh-CN.jsonAdd Simplified Chinese Telegram server strings +7/-2

Add Simplified Chinese Telegram server strings

• Adds English fallback labels, guidance, and validation messages for custom Bot API server configuration.

i18n/zh-CN.json

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Generated clients accept rejected URLs ✓ Resolved 📘 Rule violation ≡ Correctness

Description

createTelegramBody.serverUrl and updateTelegramBody.serverUrl use unrestricted z.url() schemas
even though telegramServerUrlSchema rejects non-HTTP protocols, queries, fragments, and
credentials. OpenAPI-generated clients therefore treat inputs such as credential-bearing or
query-bearing URLs as valid until the create or update handler rejects them with a 400 response.

Code

apps/api/src/telegram-integration/schema.ts[R8-10]

+  serverUrl: z.url().optional().openapi({
+    description:
+      "A self-hosted Bot API server. Defaults to https://api.telegram.org.",

Evidence

Compliance rule 9 requires public Zod and OpenAPI contracts to describe implemented behavior
accurately. The request schema advertises a generic URI while the domain validator rejects several
URI forms that satisfy that published schema.

AGENTS.md: Maintain Accurate Zod Validation and OpenAPI Contracts: AGENTS.md: Maintain Accurate Zod Validation and OpenAPI Contracts
apps/api/src/telegram-integration/schema.ts[8-24]
apps/api/src/plugins/telegram/config.ts[37-59]
apps/docs/openapi.json[15516-15520]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The public request schemas advertise any URI as a valid Telegram server URL, while domain validation accepts only HTTP or HTTPS URLs without queries, fragments, or credentials.
## Fix Focus Areas
- apps/api/src/telegram-integration/schema.ts[8-24]
- apps/api/src/plugins/telegram/config.ts[37-59]
- apps/docs/openapi.json[15516-15520]
- apps/docs/openapi.json[15626-15633]
## Recommended Fix
Create a reusable Zod refinement for the same server URL restrictions enforced by the domain schema, apply it to both create and update request schemas, add accurate OpenAPI descriptions for every restriction, and regenerate the committed OpenAPI artifact.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Server settings can regress untested ✓ Resolved 📘 Rule violation ☼ Reliability

Description

TelegramIntegrationSettings adds client-side URL validation and token re-entry branching, but the
added tests exercise only API helpers and controller utilities rather than the component or HTTP
routes. Regressions in form submission, error presentation, route validation, persistence, or
response serialization can therefore pass the new test suite while breaking the custom-server
workflow.

Code

apps/web/src/components/project/telegram-integration-settings.tsx[R264-267]

+        if (
+          !trimmedBotToken &&
+          trimmedServerUrl !== (integration?.serverUrl ?? "")
+        ) {

Evidence

Compliance rule 21 explicitly requires focused component coverage for UI logic and focused API tests
for changed API behavior. The PR adds form branches and route behavior, while its new tests invoke
postToTelegram, configuration helpers, and controller utilities directly without rendering the
component or sending requests through the routes.

AGENTS.md: Provide Tests Appropriate to the Changed Behavior: AGENTS.md: Provide Tests Appropriate to the Changed Behavior
apps/web/src/components/project/telegram-integration-settings.tsx[210-280]
tests/api/plugins/telegram-server-url.test.ts[23-104]
tests/api/telegram-integration/telegram-controller.test.ts[20-76]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The custom Telegram server workflow changes UI submission logic and public API behavior without component coverage or request-level API coverage.
## Fix Focus Areas
- apps/web/src/components/project/telegram-integration-settings.tsx[192-292]
- apps/api/src/telegram-integration/index.ts[165-181]
- apps/api/src/telegram-integration/index.ts[263-270]
- tests/api/telegram-integration/telegram-controller.test.ts[20-76]
## Recommended Fix
Add component tests for URL validation, clearing the server, and requiring the token after a server change; also add authenticated API tests proving create and update requests validate, persist, and return the custom server URL.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Custom servers can reach private hosts 🐞 Bug ⛨ Security

Description

postToTelegram enables publicDestination, but sendOutboundRequest validates a separate DNS
lookup and then calls fetch by hostname without pinning the validated address. A rebinding
hostname can return a public address during validation and a private address during the subsequent
request, reaching an internal service with the bot token embedded in the path.

Code

apps/api/src/plugins/telegram/client.ts[39]

+    { readJson: true, publicDestination: Boolean(serverUrl) },

Evidence

The new Telegram call marks custom URLs as public destinations, but assertPublicDestination only
checks addresses returned by its own lookup. After that check completes, sendOutboundRequest
passes the original hostname to fetch, so the validated addresses are not bound to the network
connection and a second resolution can select a private destination.

apps/api/src/plugins/telegram/client.ts[34-39]
apps/api/src/utils/outbound-request.ts[71-83]
apps/api/src/utils/assert-public-destination.ts[94-113]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Custom Telegram servers are checked with one DNS lookup, but the subsequent token-bearing request resolves the hostname again. A rebinding hostname can therefore pass validation and direct the actual request to a private address.
## Fix Focus Areas
- apps/api/src/plugins/telegram/client.ts[34-39]
- apps/api/src/utils/outbound-request.ts[71-83]
- apps/api/src/utils/assert-public-destination.ts[94-113]
## Recommended Fix
Change the outbound request implementation so the connection is pinned to an address returned and approved by the destination validator while preserving the original hostname for TLS verification and the Host header. Reject the request if no validated address can be used, and add a test where DNS changes from a public address during validation to a private address during connection.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[zaralX]

ready for review