Ellipse Gradient for Header

Integrate Telegram with Martini

Integrate Telegram with Martini using the HTTPS-based Telegram Bot API, inbound webhooks, or controlled polling. Martini can transform Telegram updates into enterprise workflows for notifications, service-desk intake, interactive approvals, and document or media processing while keeping bot credentials protected and operational behavior maintainable.

Integration PointSupported by TelegramCommon use casesHow Martini supports it
Reporting and analytics extractionYes, for selected API dataExtract bot updates, message metadata, chat information, callback activity, or operational outcomes for service reporting and workflow monitoring. Treat the result as event-oriented data rather than a complete Telegram history.Martini can call Telegram Bot API methods over HTTPS, transform returned JSON, and load selected operational data into reporting or analytics systems. The Bot API is not documented as a general reporting or complete chat-history extraction API.
Bulk and batch operationsYes, with limitsSend order updates, incident alerts, shipment notifications, approval reminders, or scheduled operational reports. Store chat_id values with the relevant customer, employee, team, or operational group.Martini can orchestrate repeated Bot API calls for notifications, media handling, or other supported actions. Use queues, throttling, retry-after handling, and failure monitoring because Telegram may return HTTP 429 responses.
Incremental export APIsYes, for bot updatesPoll for commands, messages, callbacks, and other enabled update types when webhook delivery is not suitable. Persist offsets and coordinate consumers to avoid duplicate or competing consumption.Martini can use getUpdates to retrieve pending bot updates and advance the offset from the last successfully processed update_id. This is incremental event consumption, not a documented general-purpose export of complete chat history.
WebhooksYesBuild event-driven service-desk intake, customer requests, approval callbacks, notification responses, and media-processing workflows. Webhooks are generally the preferred production model when secure inbound HTTPS is available.Martini can expose a REST service that receives Telegram Update objects over HTTPS after setWebhook is configured. The service should validate the configured secret header, route events, and implement idempotent processing.
REST APIsYesSend or edit messages, send media, answer callback queries, manage bot configuration, retrieve updates, and support commands, keyboards, invoices, and payment-related workflows.Martini can invoke Telegram Bot API methods over HTTPS using protected bot-token configuration and JSON or form-based request payloads. Responses are JSON objects containing success information and either a result or error description.

Exposes data and business events

Telegram Webhooks

Telegram sends bot events as JSON-serialized Update objects. Updates can represent new or edited messages, channel posts, callback queries, chat-member changes, inline queries, and payment-related events.

How This works in Martini

Expose a Martini REST service over HTTPS and configure Telegram with setWebhook. Validate the secret header, identify the update type, route the event to the appropriate workflow, and return a successful response only after the update has been accepted for processing.

Example Martini workflow

Receive webhook
Validate secret
Route update
Process event

Telegram Polling

Telegram's getUpdates method provides a pull-based mechanism for retrieving pending bot updates. Polling requires offset management and cannot run while an outgoing webhook is configured for the same bot.

How This works in Martini

Run a scheduled or continuously managed Martini workflow that calls getUpdates, processes returned Update objects, and persists the last successfully handled update_id plus one as the next offset. Coordinate consumers when multiple service instances are possible.

Example Martini workflow

Schedule polling
Call getUpdates
Process updates
Advance offset

Telegram Interactions

Telegram inline keyboards and callback queries support interactive approvals, confirmations, routing choices, and status actions. A callback query includes a query identifier, user information, and callback data.

How This works in Martini

Send a Telegram message with an inline keyboard, receive the resulting CallbackQuery through the webhook or polling flow, validate the user and correlation identifier, perform the business action, and call answerCallbackQuery promptly.

Example Martini workflow

Send keyboard
Receive callback
Validate request
Update system
Answer callback

Common Integration Patterns

Pattern 1

When to use this pattern

Use this pattern when enterprise systems need to notify Telegram users, groups, or channels about order status, incidents, shipments, approvals, or scheduled operational information.

Data Flow
ERP or CRM
Martini
Telegram
Example Mapping
Telegram FieldCanonical FieldTarget Field
textnotificationTextMessage.text
chat_idrecipientChatChat.id
document or photoattachmentMessage.document or Message.photo
Martini Implementation

Martini receives an event from an ERP, CRM, monitoring system, or internal application, maps the business fields into a Telegram Bot API request, and calls sendMessage, sendPhoto, sendDocument, or another suitable method. Use protected bot credentials, resolve and validate chat_id values, and apply throttling and retry handling for high-volume notifications.

Martini features used:
  • REST services
  • HTTPS API calls
  • Data mapper
  • Workflow orchestration
  • Throttling

Pattern 2

When to use this pattern

Use this pattern when Telegram acts as an inbound service desk, customer request channel, or operational intake interface.

Data Flow
Telegram
Martini
CRM or ticketing system
Example Mapping
Telegram FieldCanonical FieldTarget Field
from.idexternalUserIdRequester.externalId
chat.idconversationIdCase.externalConversationId
message.textrequestTextCase.description
Martini Implementation

Expose a Martini REST service as the Telegram webhook endpoint, validate the secret header, parse the Update and Message objects, and route commands or message content into a CRM, ticketing system, or workflow application. Return a confirmation through the Bot API after the downstream case or request has been created or updated.

Martini features used:
  • REST services
  • Webhook routing
  • Data mapper
  • Workflow orchestration
  • Error handling

Pattern 3

When to use this pattern

Use this pattern for approvals, confirmations, routing choices, and status actions that require a user response from Telegram.

Data Flow
Enterprise approval system
Martini
Telegram
Martini
Example Mapping
Telegram FieldCanonical FieldTarget Field
callback_dataapprovalIdApproval.id
callback_datadecisionApproval.status
from.idapproverIdApproval.approverExternalId
Martini Implementation

Martini sends an approval request with an inline keyboard and a short, non-sensitive correlation identifier in callback_data. When Telegram returns a CallbackQuery, Martini validates the user and correlation identifier, updates the source approval system, edits or follows up on the original message, and calls answerCallbackQuery promptly.

Martini features used:
  • REST services
  • Inline keyboard payloads
  • Data mapper
  • Conditional routing
  • Idempotent processing

Pattern 4

When to use this pattern

Use this pattern when users submit documents, images, audio, or voice messages that must be archived, scanned, extracted, or processed by enterprise systems.

Data Flow
Telegram
Martini
Document or archive system
Example Mapping
Telegram FieldCanonical FieldTarget Field
message.document.file_idsourceFileIdDocument.externalFileId
message.chat.idsourceChatIdDocument.sourceChatId
message.message_idsourceMessageIdDocument.sourceMessageId
Martini Implementation

Martini receives a media-bearing Message, extracts the Telegram file identifier, calls getFile, and downloads the returned path. The workflow validates the content and size, optionally scans or transforms it, sends it to an archive, OCR service, document-management system, or business application, and reports the result back to Telegram.

Martini features used:
  • REST services
  • HTTPS API calls
  • Data mapper
  • File handling
  • Workflow orchestration

How to build a Telegram integration in Martini

Objective

Establish the Telegram integration boundary and select the Bot API delivery model. Prefer webhooks for event-driven production workflows when Martini can expose a secure HTTPS endpoint, and use polling for simpler or controlled deployments.

Instructions in Martini

  • Create or identify the Telegram bot with @BotFather.
  • Store the bot token as protected Martini configuration.
  • Define the Telegram chats, update types, and business actions required.
  • Choose webhook delivery or getUpdates polling; do not configure both for one bot.

Objective

Provide a secure inbound entry point for Telegram Update objects and prevent unauthorised or malformed webhook requests from entering business workflows.

Instructions in Martini

  • Create a Martini REST service with a publicly reachable HTTPS endpoint.
  • Configure Telegram setWebhook with the endpoint and a secret token.
  • Validate X-Telegram-Bot-Api-Secret-Token before parsing the request.
  • Return a successful response only after accepting the update for processing.

Objective

Normalize Telegram's event-oriented payloads into a predictable internal structure so downstream services can process each interaction consistently.

Instructions in Martini

  • Parse the Update envelope and identify its event type.
  • Extract User, Chat, Message, File, or CallbackQuery fields as applicable.
  • Preserve update_id and message identifiers for tracing and deduplication.
  • Route commands, messages, callbacks, media, and payment-related events to separate workflow paths.

Objective

Execute the required Telegram action or enterprise-side operation while keeping authentication, authorization, and message content under explicit workflow control.

Instructions in Martini

  • Map canonical business fields to Telegram Bot API request fields.
  • Call sendMessage, sendPhoto, sendDocument, getFile, answerCallbackQuery, or another documented method over HTTPS.
  • Use protected bot-token configuration and avoid placing sensitive data in callback_data or messages.
  • Validate chat permissions and user context before sensitive operations.

Objective

Make the integration reliable in production by addressing duplicate delivery, Telegram rate limits, transient failures, identifier handling, and operational visibility.

Instructions in Martini

  • Persist processed update IDs or equivalent state.
  • Apply throttling and queueing for bulk notifications.
  • Handle HTTP 429 responses, retry-after values, network failures, invalid chat IDs, permission errors, and media failures.
  • Monitor failed or repeatedly unprocessed updates and protect tokens from logs.

Common Data Objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
UpdateTrigger workflows from messages, callbacks, member changes, channel posts, or payment events.CRM, ticketing systems, workflow applications, databasesMartini receives Update objects through a webhook or getUpdates polling flow, uses update_id for tracing and deduplication, and routes by the contained event type.
UserAssociate Telegram interactions with customers, employees, requesters, or approvers.CRM, identity directories, customer databasesMartini maps user identifiers and profile fields into enterprise records while preserving Telegram identifiers with 64-bit-safe handling.
ChatRoute notifications to users, groups, supergroups, or channels.CRM, notification registries, operational databasesMartini uses chat identifiers, type, title, username, and permission-related fields to select destinations and validate access.
MessageHandle commands, customer-service intake, alerts, approvals, and operational notifications.CRM, service desk, ERP, workflow applicationsMartini parses message text, entities, sender and chat references, replies, forwarded information, media identifiers, and reply markup for downstream workflows.
FileProcess documents, images, audio, and voice messages received by a bot.Document management systems, archives, OCR services, databasesMartini extracts the file identifier, calls getFile, downloads the returned path, validates the content, and passes it to a downstream service or repository.
CallbackQueryImplement approve, reject, confirm, menu selection, and status-update actions.ERP, approval systems, CRM, workflow applicationsMartini validates callback data and the originating user or transaction, performs the requested action, and calls answerCallbackQuery without exposing sensitive data in the callback payload.

Authentication and security considerations

Bot token authentication

Telegram Bot API requests are authenticated with a bot token generated by @BotFather. Store the token as a protected Martini credential and do not expose it in logs, URLs returned to users, workflow payloads, or error messages. The Bot API does not document OAuth 2.0, JWT authentication, separate API keys, or configurable permission scopes for bot requests.

Webhook validation

When configuring a webhook with Telegram's setWebhook method, configure a secret token and validate the X-Telegram-Bot-Api-Secret-Token header in the Martini REST service before processing updates. This header is an additional validation mechanism and does not replace HTTPS.

Permissions and access

Telegram access depends on the bot identity, chat membership, administrator permissions, privacy mode, enabled update types, and whether a user has initiated a conversation with the bot. Validate the requesting user and chat before performing sensitive actions, especially for callback-driven approvals.

MTProto credentials

MTProto integrations require an application api_id and api_hash, and user-account authorization can involve phone verification, two-factor authentication, QR-code login, passkeys, and client session state. Prefer the Bot API unless user-account capabilities are specifically required.

Operation considerations

Webhook operation

  • Expose a publicly reachable HTTPS Martini REST service.
  • Validate the X-Telegram-Bot-Api-Secret-Token header before processing updates.
  • Make processing idempotent using update_id because Telegram can retry unsuccessful deliveries.
  • Use allowed_updates to limit delivery to the event types required by the integration.
  • Return a 2xx response only after the update has been accepted for processing.

Polling operation

  • Persist the last successfully processed update_id and advance the offset only after successful processing.
  • Prevent uncoordinated Martini instances from consuming the same bot updates.
  • Handle network timeouts, retries, and repeatedly failing updates.
  • Do not configure getUpdates while an outgoing webhook is active for the same bot.

Throughput and retries

Telegram may return HTTP 429 responses when messaging limits are exceeded. Use Martini throttling, queues, retry-after handling, and failure monitoring for broadcast or notification workflows.

Data and media

Handle user IDs, chat IDs, message IDs, and callback identifiers as external values, using 64-bit-safe numeric handling. For media, call getFile using the supplied file identifier, respect documented limits, validate content types, apply malware scanning where appropriate, and remove temporary files after successful processing.

Conversation constraints

Bots cannot initiate private conversations with users who have not contacted them. Group and channel access depends on membership, administrator rights, privacy mode, and Telegram permissions.

Why use Martini

Connect Telegram to enterprise workflows

Martini provides a structured way to connect Telegram's Bot API with enterprise applications, REST services, databases, files, and workflow processes. Teams can combine inbound Telegram updates with outbound HTTPS API calls, data transformation, conditional routing, scheduling, and asynchronous execution.

Support event-driven and scheduled designs

Use a Martini REST service for Telegram webhooks or build a controlled polling workflow with getUpdates. Both approaches can route messages, callbacks, media events, and operational notifications into maintainable services and workflows.

Extend processing when needed

When message parsing, callback validation, throttling, or other logic requires more flexibility, Martini supports custom JVM-compatible logic such as Groovy alongside its low-code development model.

Improve operational control

Protect bot credentials, transform Telegram objects into canonical enterprise data, implement idempotent processing, and manage retries and rate limits as part of the integration design. This supports Telegram notifications, service-desk intake, interactive approvals, and document-processing workflows without treating Telegram as a general-purpose historical data export.

Frequently asked questions

How does Martini authenticate with Telegram?

Telegram Bot API integrations use a bot token generated by @BotFather. Store it as protected Martini configuration and keep it out of logs, returned URLs, and workflow payloads.

Does Telegram support OAuth 2.0 for bot integrations?

The Bot API documentation describes bot-token authentication rather than OAuth 2.0, JWTs, API-key headers, or granular Bot API scopes. Access is governed by the bot identity, chat membership, Telegram permissions, and privacy settings.

Should Martini use Telegram webhooks or polling?

Use webhooks when Martini can expose a secure, publicly reachable HTTPS endpoint for event-driven processing. Use getUpdates polling for simpler or controlled deployments where inbound HTTPS delivery is unavailable. The two modes cannot be used simultaneously for one bot.

Can a Telegram bot message any user?

No. A user generally must first contact or start the bot, or add it to a group, before the bot can interact with that user.

Can a bot read every message in a group?

Not by default. Privacy mode limits the messages a bot receives in groups. Broader access depends on privacy settings, membership, and administrator status.

How should duplicate Telegram webhook events be handled?

Use update_id as an idempotency key. Persist processed identifiers or equivalent processing state before performing non-idempotent downstream actions, because Telegram can retry unsuccessful webhook deliveries.

Can Martini synchronize complete Telegram chat history?

The Bot API is event- and action-oriented and is not documented as a general bulk export or complete chat-history synchronization API. Full client-level history access belongs to MTProto and requires user authorization and more complex session and update management.

Can Telegram support interactive workflows?

Yes. Inline keyboards and callback queries can support approvals, confirmations, routing, menu selection, and status updates. Martini should validate callback data against the requesting user and business transaction and answer callback queries promptly.

When should MTProto be used instead of the Bot API?

Use MTProto only when client capabilities or user-account operations unavailable through the Bot API are required. MTProto introduces application credentials, user authorization, encrypted sessions, update sequencing, and gap recovery.

How should Martini handle Telegram rate limits?

Bulk notification workflows should use throttling, queueing, retry-after handling, and failure monitoring. Telegram can return HTTP 429 responses when practical messaging limits are exceeded.

Related Martini documentation

APIs

Workflows

Security

Services

Deployment

Build Telegram workflows with Martini

Connect Telegram bot interactions to enterprise applications through Martini's REST services, HTTPS API calls, workflow orchestration, data transformation, and protected configuration. Use webhooks or polling for inbound updates, and design idempotent, throttled workflows for reliable production processing.

EXPLORE MARTINI
BOOK A DEMO