SiteHelper: enquiries, notification queues and statuses
SiteHelper is a Skycode Telegram bot that helps the client describe a task and transfer it to the administrator in a structured form. In this case, it is not the set of buttons that is important, but internal reliability: the enquiry should not depend on a single request to the Telegram API or re-delivery of a webhook.
We divided the process into three parts: collecting data in the dialogue, stable saving of the enquiry and an independent notification queue. Below is the structure of this integration without fictitious indicators and marketing promises.
1. Turn conversations into structured enquiries
The bot consistently collects the selected services, site type, task description, terms of reference, budget range, urgency, contact and referral source. These fields add up to the state of the current dialogue, and before confirmation the user sees the collected information.
After confirmation, a separate request record is created. The terms of reference can be submitted as a document or photograph, and the attachment information is associated with the same enquiry. This format is more convenient than a free message: the manager receives the same structure and understands the context faster.
2. Accept verified webhook updates
The webhook public point checks the Telegram secret header and rejects the request if the configuration is incomplete or the check fails. PHP errors are not shown to the visitor, but are written to a private log outside the public part of the site.
After validating the input data, FastCGI can return an HTTP 200 response to Telegram before further processing is completed. This reduces the risk of an update being redelivered due to a slow external API, but does not replace separate anti-duplicate protection.
3. Prevent duplicate update processing
Each Telegram update has an identifier. SiteHelper tries to write it to the processed updates table with a unique key. If such an ID already exists, the webhook acknowledges the request and stops reprocessing.
A separate unique draft token is used to validate the request itself. Even if the user or network repeats the final operation, the system returns the existing record instead of creating a second one. Old update IDs are periodically cleared to prevent the service table from growing endlessly.
4. Save the enquiry before sending notifications
Requests are stored in a separate SQLite database outside the web directory. The record contains structured fields, source JSON and service dates. There are three states for the workflow: new, in progress, and closed.
First, saving is performed, and only then tasks are generated to notify the administrator. This is the same principle that we discussed in the article about the path of an enquiry from the site to the manager: the external delivery channel should not be the only place where the enquiry exists.
5. Use an outbox to separate acceptance from delivery
SiteHelper does not send an administrative message directly at the time of ticket creation. Instead, it adds a description of the Telegram API method and the necessary parameters to the outbox table. The main notification and, if any, the attached technical task are queued separately.
Each task has a status, number of attempts, next launch time, blocking mark and last error. Thanks to this, temporary unavailability of Telegram does not turn into a loss of enquiry, and the history of the failure can be checked.
6. Process delivery and retries in a worker
The background worker runs on a schedule every minute. It atomically picks up a completed task, transfers it to processing and, after a successful response, marks it as sent. A limited batch is processed per run so that the process does not hold the server indefinitely.
If the delivery fails, the worker increments the counter and schedules a retry with an increasing delay, limited to one hour. After eight unsuccessful attempts, the task gets the failed status. Stuck locks older than five minutes are returned to the queue, so worker aborts do not leave the job in the processing state forever.
7. Let administrators manage enquiries in the bot
The administrator receives a card with the request number, services, task, budget, urgency, contact and source. If the client has attached a technical task, it is delivered as a separate message and is associated with the request number.
A list of recent requests and status counters are available inside the bot. Inline buttons allow you to transfer the request to work, return it to new ones, or close it. The administrative command handler checks the administrator ID on the server, so hiding the buttons in the interface is not enough.
What the architecture provides
As a result, accepting an enquiry, delivering a notification, and working with statuses have become independent stages. A Telegram API failure does not delete saved data, repeating a webhook does not duplicate the operation, and the manager sees a single status of the request. The configuration, database, states and logs are located outside the public directory.
This scheme is suitable not only for a Telegram bot: the same principles apply to site forms, CRM and internal accounts. It is important to determine in advance the source of truth, the rules of repetition, and who is responsible for errors. Describe your scenario in the brief – we will offer an architecture for collecting and processing enquiries for your process.
Why the scheme saves requests
The SiteHelper case shows an important rule: first confirm to save the event, then deliver the notification. If Telegram is temporarily unavailable, the entry remains in the queue and is resent, and the unique identifier protects against duplicates.
Update formats and responses of the message sending method are defined in official Telegram Bot API documentation. Thanks to this, the SiteHelper case can be checked for specific states: accepted, saved, queued, delivered, or requires attention.
The SiteHelper case also shows the value of logging: using the enquiry ID, you can restore the entire notification route.