Telegram CRM Webhook Payload Examples
This glossary defines the key payload structures and data fields exchanged between Telegram and a Customer Relationship Management (CRM) system via webhook integrations. Understanding these payloads is essential for support teams configuring automated ticket creation, agent assignment, and status updates within a Telegram Topic Group environment. Each entry provides a definition of the term, its typical JSON structure, and its role in the support workflow.
Webhook Integration
A webhook integration is an HTTP callback mechanism that enables real-time data exchange between Telegram and a CRM. When a specific event occurs—such as a new message in a Telegram Topic Group—the platform sends a structured JSON payload to a pre-configured CRM endpoint. This allows the CRM to create, update, or close tickets without manual polling. The payload typically includes fields such as `chat_id`, `message_id`, `from`, `text`, and `topic_id`. For support teams, configuring a webhook URL in the CRM settings is the first step toward automating ticket intake from Telegram.
Ticket Status
Ticket status represents the current state of a support request within the CRM workflow. Common statuses include `new`, `open`, `in_progress`, `resolved`, and `closed`. The webhook payload for a status update often contains fields like `ticket_id`, `old_status`, `new_status`, and `updated_by`. When an agent changes the status of a ticket from `in_progress` to `resolved`, the CRM sends a payload to the Telegram webhook, which can then update the topic group with a closure message or trigger an escalation policy.
Agent Assignment
Agent assignment refers to the process of allocating a support ticket to a specific human agent. The webhook payload for assignment typically includes `ticket_id`, `assigned_to` (with `user_id`, `username`, and `full_name`), `assigned_at` (timestamp), and `assignment_reason`. For example, when a routing rule assigns a ticket to an agent based on queue management criteria, the CRM sends a payload that updates the Telegram topic group with the agent’s name and a direct link to the ticket.
Service Level Agreement (SLA)
An SLA policy defines the expected response and resolution times for support tickets. In webhook payloads, SLA data often appears as `sla_policy_name`, `sla_due_time`, `sla_breach_time`, and `sla_status` (e.g., `within_sla`, `breached`). When a ticket approaches its first response time limit, the CRM may send a warning payload to the Telegram topic group. It is important to note that SLA adherence depends on the specific product configuration and individual agent workload; no system guarantees zero missed tickets.
First Response Time (FRT)
First response time measures the duration between ticket creation and the initial reply from an agent. The webhook payload for FRT tracking includes `ticket_id`, `created_at`, `first_reply_at`, `frt_seconds`, and `frt_status`. If the FRT exceeds the configured threshold, the CRM can trigger an escalation policy, sending a payload to the Telegram group that notifies supervisors.
Resolution Time
Resolution time tracks the total duration from ticket creation to closure. The webhook payload for resolution includes `ticket_id`, `created_at`, `resolved_at`, `resolution_seconds`, and `resolution_status`. This metric is critical for evaluating agent performance and queue management efficiency. The CRM may send a payload summarizing the resolution time when the ticket status changes to `closed`.
Queue Management
Queue management involves organizing incoming support requests into a structured work queue. Webhook payloads for queue events include `queue_name`, `ticket_count`, `old_queue`, `new_queue`, and `moved_by`. For instance, when a ticket is reassigned from a general queue to a specialized queue (e.g., Level 2 Support), the CRM sends a payload that updates the Telegram topic group with the new queue assignment.
Escalation Policy
An escalation policy defines rules for increasing the priority of a ticket when SLA thresholds are breached or when a ticket requires specialized attention. The webhook payload for an escalation event includes `ticket_id`, `escalation_level` (e.g., `level_1`, `level_2`), `escalation_reason`, `escalated_by`, and `escalated_to`. This payload can be used to notify a supervisor channel in Telegram or to reassign the ticket to a senior agent.
Bot Intake Form
A bot intake form is a structured message sent by a Telegram bot to collect initial information from a customer before creating a ticket. The webhook payload from the form submission includes `form_id`, `customer_id`, `form_fields` (an array of key-value pairs), `submitted_at`, and `chat_id`. For example, a form may ask the customer to select a category (e.g., “Billing,” “Technical”) and provide a description. The CRM then uses this payload to create a ticket with the appropriate topic group and template.
Canned Response
A canned response is a pre-defined reply template that agents can use to answer common questions. The webhook payload for inserting a canned response into a conversation includes `ticket_id`, `response_id`, `response_text`, `agent_id`, and `inserted_at`. When an agent selects a canned response in the CRM, the system sends a payload to the Telegram webhook, which then posts the reply in the corresponding topic group.
Knowledge Base Integration
Knowledge base integration connects the CRM to a help center or article database, allowing agents to suggest relevant articles during conversations. The webhook payload for a knowledge base suggestion includes `ticket_id`, `article_id`, `article_title`, `article_url`, and `suggested_by`. This payload can be used to automatically post a link to an article in the Telegram topic group, reducing the need for manual typing.
Conversation Thread
A conversation thread is the complete message history for a single support ticket. The webhook payload for fetching or updating a thread includes `ticket_id`, `messages` (an array of message objects with `message_id`, `sender_id`, `text`, `timestamp`), and `total_messages`. When a new message is added to the thread, the CRM sends a payload that updates the Telegram topic group with the latest message.
Telegram Topic Group
A Telegram topic group (also known as a forum group or topic-based chat) is a chat that organizes messages into separate topics, each representing a distinct support ticket. The webhook payload for creating or updating a topic includes `topic_id`, `topic_name`, `chat_id`, `created_at`, and `last_message_at`. When a new ticket is created, the CRM sends a payload that creates a new topic in the Telegram group and assigns it a unique topic ID.
Ticket
A ticket (also referred to as a support ticket, issue, or case) is a formal record of a customer request. The webhook payload for ticket creation includes `ticket_id`, `customer_id`, `customer_name`, `subject`, `description`, `priority`, `status`, `created_at`, and `assigned_agent`. This payload is the core event that triggers all subsequent workflows, including agent assignment, SLA tracking, and queue management.
Agent
An agent is a human support team member who handles tickets. The webhook payload for agent-related events includes `agent_id`, `username`, `full_name`, `role` (e.g., `agent`, `supervisor`), `status` (e.g., `available`, `busy`), and `last_active_at`. When an agent’s status changes (e.g., from `available` to `busy`), the CRM sends a payload that updates queue management systems.
Customer
A customer is the end-user submitting a support request via Telegram. The webhook payload for customer data includes `customer_id`, `telegram_user_id`, `first_name`, `last_name`, `username`, `language_code`, and `joined_at`. This payload is used to create or update the customer’s profile in the CRM, linking all their tickets to a single identity.
Message
A message is an individual text, image, or file sent within a Telegram topic group. The webhook payload for a new message includes `message_id`, `chat_id`, `topic_id`, `from` (sender object with `user_id`, `username`), `text`, `date`, and `reply_to_message`. This payload triggers the CRM to update the conversation thread and, if necessary, create a new ticket or update an existing one.
Timestamp
A timestamp is a Unix epoch time (in seconds) that marks when an event occurred. Webhook payloads frequently include `created_at`, `updated_at`, `resolved_at`, and `breached_at` fields. These timestamps are essential for calculating first response time, resolution time, and SLA adherence.
Priority
Priority indicates the urgency of a ticket, typically ranging from `low` to `critical`. The webhook payload for priority changes includes `ticket_id`, `old_priority`, `new_priority`, `changed_by`, and `changed_at`. When a ticket’s priority is escalated, the CRM sends a payload that updates the Telegram topic group’s color or notification settings.
Routing Rule
A routing rule is a condition that determines how tickets are assigned to agents. The webhook payload for routing rule execution includes `ticket_id`, `rule_name`, `matched_condition`, `assigned_agent`, and `assigned_queue`. For example, a rule might assign all tickets with priority `high` to a specific queue. The payload confirms the assignment and can be used to update the Telegram topic group.
Topic ID
A topic ID is a unique identifier for a specific topic within a Telegram topic group. The webhook payload for topic events includes `topic_id`, `chat_id`, and `topic_name`. This ID is crucial for mapping Telegram conversations to CRM tickets. When a ticket is closed, the CRM sends a payload that may archive or lock the corresponding topic.
Event Type
An event type is a label that identifies the kind of webhook payload (e.g., `ticket.created`, `ticket.updated`, `message.received`, `agent.assigned`). The payload includes an `event` field with a string value. Support teams can use this field to filter incoming webhooks and trigger specific automation workflows.
Payload Validation
Payload validation is the process of verifying the integrity and authenticity of a webhook payload. The CRM typically includes a `signature` or `token` field in the payload, which the receiving system checks against a shared secret. This prevents unauthorized or malicious payloads from being processed.
What to Verify
- Confirm that the webhook URL is correctly configured in both Telegram and the CRM.
- Validate the payload structure against the CRM’s documentation to ensure all required fields are present.
- Test the webhook with a sample event (e.g., a test ticket creation) to verify that the Telegram topic group updates correctly.
- Review the event type field to ensure that only relevant events trigger automation workflows.
- Check the signature or token field for payload validation to prevent unauthorized data injection.
Reader Comments (0)