Laragram Laravel Package

Product Decisions This Supports

• Notification reliability for messaging features. This release directly de-risks any product surface that pings users on Telegram with a profile deep-link (mention alerts, "X replied to you", assignment pings, DM-style handoffs). Previously a single user's privacy setting could make the entire notification silently fail; after v2.3.2 the message still arrives, minus one button. That converts a hard delivery failure into a cosmetic degradation — a meaningful change to the reliability story you can put in a spec or SLO.
• Build vs. buy on Telegram delivery plumbing. The package now owns edge-case handling you would otherwise have to build and maintain yourself: detecting Telegram's opaque 400 error, surgically stripping only the offending tg://user?id=… buttons, cleaning up now-empty rows, logging a warning with the dropped buttons named, and retrying once without duplicating delivery. That is a small but genuinely fiddly piece of logic most teams would get wrong the first time (notably the "nothing is delivered twice" guarantee — a naive retry would double-send).
• Feature scoping: profile buttons are a progressive enhancement, not a requirement. Because ReplyMarkup::isUserLinkButton() and withoutUserLinks() are now public, you can decide at the product level to treat profile deep-links as best-effort. The release note's own guidance — repeat the contact in the message body (username or text mention) if it matters — is a concrete authoring rule you can write into your notification templates and copy guidelines.
• Roadmap input on notification design. This nudges toward a house style: identity-bearing information belongs in the message text, buttons are convenience. That decision affects template design, localization strings, and how you write acceptance criteria for every future notification type.
• Low-cost maintenance hygiene. A patch release with no migration, no config publish, no breaking changes is a composer update. The decision to take it is essentially free, which is worth stating explicitly so it doesn't get stuck in a backlog triage queue.

When to Consider This Package

Adopt or upgrade when:

• You ship Telegram notifications from a Laravel app and any of them use inline keyboards with tg://user?id=… profile links — this is the exact failure mode being fixed, and it is invisible until a user with restrictive privacy settings reports a missing message.
• You want first-class handling of a Telegram API quirk that cannot be pre-validated. The release is explicit that whether a user permits the link cannot be checked before the call, so client-side defensive logic is the only option; the package now does it for you.
• You value a narrow, auditable failure path: on the specific 400 BUTTON_USER_PRIVACY_RESTRICTED response, degrade gracefully; on anything else, rethrow the original exception unchanged. That "only this error, only these buttons, otherwise behave exactly as before" scope is easy to reason about in an incident review.
• You are already on the 2.x line. The upgrade is a composer update with nothing to run, so the cost/benefit is trivially favourable.

Look elsewhere or defer when:

• You do not send Telegram messages, or you send them without inline keyboards — the fix is inert for you, and this release gives you no reason to adopt the package.
• You rely on tg://user?id=… buttons as a hard requirement (e.g. a workflow that only works if the recipient can tap through to a profile). The graceful degradation is still correct behaviour, but you must plan a fallback — put the username or a text mention in the body — rather than assume the button will render.
• You need to know which specific button was refused. Telegram does not report it, so all tg://user?id=… buttons on that message are dropped. If per-button precision matters, this design will not give it to you.
• You are on a pre-2.x major and unwilling to take the larger migration; this patch does not change that calculus.

How to Pitch It (Stakeholders)

To executives: A one-line dependency bump that removes a class of silent notification failures. Previously, if a recipient's Telegram privacy settings blocked profile links, Telegram rejected the entire message — the user got nothing, and we got an exception. Now the message is delivered without the offending button, and the event is logged as a warning we can monitor. No breaking changes, no migration, no engineering project: composer update and ship. The upside is measurable in delivery rate for any notification carrying a profile button; the cost is near zero.

To engineering: Patch release, non-breaking, nothing to run. BotClient now catches 400 BUTTON_USER_PRIVACY_RESTRICTED, strips tg://user?id=… url buttons and any resulting empty rows, logs a warning naming the dropped buttons, and re-sends once. It is safe by construction — the first request was refused, so there is no double delivery. All other tg:// links are untouched, and if there is no such button to drop the original exception propagates exactly as today. Two new public helpers land in Support\ReplyMarkup: isUserLinkButton() and withoutUserLinks(), which are worth unit-testing around and reusable if you build your own keyboard assembly. One caveat to design around: Telegram does not identify the refused button, so every tg://user?id=… button on that message is dropped — if the contact is load-bearing, repeat it in the message text as a username or text mention. Recommended action: upgrade, then add a dashboard counter on these warnings so you can see how often privacy restrictions bite in production and which notification types are affected.