Webhook Payload Structure for Telegram CRM Events

The operational backbone of any Telegram CRM integration for support teams rests on the reliability and predictability of event-driven data exchange. When a support agent responds to a ticket within a Telegram Topic Group, or when a customer submits a new issue through a Bot Intake Form, the system must transmit that event to external platforms—whether for analytics, task management, or escalation routing. This data transfer is typically accomplished through a Webhook Integration, an HTTP callback mechanism that pushes structured payloads to a predefined endpoint. Understanding the anatomy of these payloads is not merely a technical curiosity; it is a prerequisite for building robust, auditable support workflows that respect Service Level Agreement boundaries and maintain accurate Ticket Status transitions.

Core Event Types and Their Triggering Conditions

A Telegram CRM system generates webhook events based on distinct actions within the support lifecycle. Each event type corresponds to a specific change in state or a user-initiated action, and the payload structure varies accordingly. The most common event categories include ticket creation, message delivery, status transitions, and agent assignment modifications.

Each event type shares a common envelope structure but carries a unique payload body. The envelope ensures that the receiving system can validate authenticity, parse metadata, and route the event to the correct handler.

Envelope Structure: Authentication and Metadata

Every webhook payload from a Telegram CRM system includes a top-level envelope containing fields that identify the source, verify integrity, and provide contextual routing information. This envelope is critical for systems that process events from multiple integrations or that require idempotent handling.

The envelope typically contains the following fields:

• event_id: A universally unique identifier (UUID v4) for the specific event. This identifier is essential for deduplication, as webhook delivery may retry on failure, and the receiving system must ignore repeated events.
• event_type: A string constant that categorizes the payload, such as `ticket.created`, `message.received`, or `status.changed`. This field allows the receiver to dispatch the payload to the appropriate handler without inspecting the full body.
• timestamp: An ISO 8601 UTC timestamp indicating when the event was generated on the CRM server. This timestamp serves as the authoritative reference for SLA calculations and audit trails.
• source: An object containing `platform` (e.g., `telegram_crm`), `integration_id` (a unique identifier for the webhook configuration), and `environment` (e.g., `production`, `staging`). This field helps differentiate events from multiple CRM instances.
• signature: An HMAC-SHA256 hash of the concatenated `event_id`, `event_type`, and `timestamp` using a shared secret key. The receiving system must compute the expected signature and compare it to this value to reject tampered or misrouted payloads.

The signature mechanism is non-negotiable for production deployments. Without it, an attacker could forge events to manipulate Ticket Status, reassign agents, or trigger false escalation alerts. Support teams should verify that their CRM provider enforces signature validation and that the webhook endpoint validates every incoming request.

Ticket Creation Payload: The Initial State

When a customer initiates a new support request—either by sending a direct message to a bot or by posting in a designated Telegram Topic Group—the CRM generates a `ticket.created` event. This payload contains all the information necessary to create a corresponding record in an external system, including customer identity, initial message content, and metadata about the channel.

The payload body for a ticket creation event includes:

• ticket_id: A unique string identifier assigned by the CRM, often formatted as `TKT-XXXXXXXX`. This identifier is the primary key for all subsequent events related to this case.
• customer: An object containing `telegram_user_id` (the numeric Telegram user ID), `username` (if available), `first_name`, `last_name`, and `language_code`. Some payloads also include `contact_phone` or `email` if the customer provided them through a Bot Intake Form.
• channel: An object specifying `type` (e.g., `topic_group`, `direct_message`, `bot_form`) and `chat_id` (the Telegram chat or group identifier). For topic groups, the `topic_id` field indicates the specific thread.
• initial_message: An object with `message_id` (Telegram message identifier), `text` (the content of the first message), `content_type` (e.g., `text`, `photo`, `document`), and `file_url` if the message includes attachments.
• metadata: A free-form object that may include `source_url`, `campaign_id`, `custom_fields`, or any other data passed through the intake form. This field is optional but highly recommended for advanced routing and reporting.
• created_at: An ISO 8601 timestamp identical to the envelope timestamp but included here for convenience when processing the body in isolation.

Support teams integrating with external task management platforms, such as Trello, should map the `ticket_id` to an external card ID and store the `customer.telegram_user_id` for future correspondence. The Telegram CRM Integration with Trello for Task Management guide provides detailed mapping strategies for this specific use case.

Message and Status Transition Payloads

Beyond ticket creation, the most frequent webhook events are message deliveries and status transitions. Message events (`message.received`) carry the content of each reply within a Conversation Thread, enabling external systems to build a complete audit trail or trigger automated responses based on keywords.

The message payload body includes:

• ticket_id: The parent ticket identifier.
• message_id: A unique identifier for this specific message within the CRM.
• sender: An object with `type` (`customer` or `agent`), `telegram_user_id`, `username`, and `agent_id` (if the sender is a support team member). The `agent_id` field is crucial for calculating individual agent performance metrics.
• content: An object with `text`, `content_type`, and optional `file_url` or `file_size`. For messages containing multiple attachments, the `content` object may include an array of file references.
• sent_at: The timestamp when the message was sent in the Telegram chat.
• is_private: A boolean indicating whether the message was visible only to agents (e.g., internal notes) or to the customer. Private messages must be excluded from customer-facing exports.

Status transition events (`status.changed`) are simpler but carry significant operational weight. The payload body includes:

• ticket_id: The affected ticket.
• previous_status: The Ticket Status before the change (e.g., `open`, `pending`, `resolved`).
• new_status: The Ticket Status after the change.
• changed_by: An object identifying the agent or automation rule that performed the transition.
• changed_at: The timestamp of the transition.

These events are the backbone of SLA monitoring. When a ticket transitions to `resolved`, the system should stop the Resolution Time clock. If the transition is from `open` to `in_progress`, the First Response Time timer stops. Any deviation between the expected SLA thresholds and the actual transition timestamps should trigger an Escalation Policy event.

Risk Considerations and Implementation Safeguards

Webhook integrations, while powerful, introduce several risk vectors that support teams must address before relying on them for critical operations. The most common failure modes include network timeouts, payload duplication, and schema drift due to CRM updates.

Network reliability: Webhook delivery is inherently asynchronous and subject to network interruptions. The CRM should implement a retry policy with exponential backoff (e.g., retry after 5 seconds, then 30 seconds, then 5 minutes, up to a maximum of 5 attempts). The receiving endpoint must return a 200 HTTP status code within a reasonable timeout (typically 10 seconds) to acknowledge receipt. If the endpoint returns a non-2xx status or fails to respond, the CRM should queue the event for retry.

Idempotency: Because retries may result in duplicate delivery, the receiving system must track processed `event_id` values in a persistent store (e.g., a database table with a unique constraint on `event_id`). Duplicate events should be silently ignored, not reprocessed.

Schema versioning: CRM providers occasionally update their payload structures—adding new fields, renaming existing ones, or changing data types. The webhook payload should include a `version` field (e.g., `"version": "1.2"`) in the envelope. The receiving system should validate the version against its expected schema and log a warning if an unexpected version is received. Support teams should subscribe to the CRM provider's changelog or deprecation notices to prepare for schema migrations.

Payload size limits: Large attachments, such as high-resolution images or lengthy documents, can bloat the payload size beyond the typical HTTP request limit (often 1 MB for reverse proxies). The CRM should either include a URL to the file (rather than the file content) or split the payload into multiple events. Always verify current platform documentation before implementing SLA or routing rules—features and limits change with product updates. Misconfigured escalation policies can result in missed tickets.

Integration Patterns and Next Steps

The payload structures described above are designed to integrate with a wide range of external systems, from simple notification bots to complex help desk platforms. For teams using Trello, the typical integration pattern involves mapping each `ticket.created` event to a new Trello card, with custom fields for `telegram_user_id`, `Ticket Status`, and `First Response Time`. Message events update the card's comment thread, while status transitions move the card between Trello lists.

For teams building custom dashboards or reporting tools, the envelope metadata (`source.integration_id`) allows for multi-tenant data segregation. Each webhook endpoint can serve multiple CRM instances, and the receiving system can route events to the appropriate tenant workspace based on the `integration_id` field.

Before deploying a webhook integration to production, support teams should:

1. Validate the signature of every incoming request using the shared secret key.
2. Implement idempotent event handling using the `event_id` field.
3. Configure monitoring for webhook delivery failures and endpoint latency.
4. Test with a staging environment that mirrors the production CRM configuration.
5. Document the expected payload schema and version for all consuming applications.

The API Documentation Essentials for Telegram CRM Developers article provides further guidance on authentication, rate limiting, and error handling for these integrations. For a broader view of how webhooks fit into the overall integration landscape, refer to the Integrations and API Connections hub.

Summary

A well-structured webhook payload is the foundation of a reliable, auditable Telegram CRM integration. By adhering to a consistent envelope format with authentication, event type classification, and idempotent identifiers, support teams can build external workflows that accurately reflect the state of their support operations. The payload structure for ticket creation, message delivery, and status transitions provides all the data necessary for SLA monitoring, agent performance tracking, and cross-platform synchronization. However, these benefits come with responsibilities: signature validation, retry handling, and schema versioning are not optional safeguards but essential components of a production-grade integration. Teams that invest in understanding and implementing these patterns will reduce the risk of missed tickets, incorrect escalations, and data loss—ensuring that their webhook integration serves as a reliable conduit for support operations rather than a source of operational friction.