Laravel Usms Laravel Package

Product Decisions This Supports

• Branded sender ID onboarding: Any feature that provisions a branded SMS sender (transactional reminders, notices, notifications) now needs a product flow that collects a brand description alongside the name. This is a product requirement, not just an API change.
• Onboarding UX and validation: The description must explain the brand's website, Facebook/Instagram page or application, and how the name will be used, capped at 500 characters. This directly informs form copy, helper text, character limits, and review states in admin or self-serve onboarding.
• Error-to-copy mapping: Two new rejection codes (DESCRIPTION_REQUIRED 60, DESCRIPTION_TOO_LONG 61) should map to actionable user-facing messages rather than generic failures. This supports better recovery rates during brand creation.
• Build vs buy: The package is a thin Laravel wrapper over uBill's brand and SMS APIs. Using it avoids maintaining direct HTTP integration, auth, and response mapping, but ties the roadmap to uBill's contract changes.
• Upgrade and dependency planning: v3 is a breaking change forced by the provider: createBrandName($brandName) becomes createBrandName($brandName, $description). The v2 signature can no longer succeed against the live API, so this is a scheduled upgrade item, not an optional enhancement.
• Compliance and approval success: Capturing a meaningful description up front reduces rejected brand applications and repeat submissions, which affects time-to-first-message for new customers.
• Multi-tenant and agency scenarios: Where each tenant or client creates its own brand, description capture and storage becomes per-tenant data with its own validation and audit needs.

When to Consider This Package

Consider adoption when:

• The application is Laravel/PHP and already uses, or plans to use, uBill as its SMS provider.
• You need programmatic brand name creation (for example, self-serve onboarding or per-tenant sender provisioning) rather than manual setup in a provider dashboard.
• You want framework-native integration — facade, exceptions, typed rejection codes — instead of a hand-rolled uBill client.
• Your product can collect and store a brand description at creation time, including the 500-character limit and the required usage explanation.
• You accept provider lock-in and a release cadence driven by uBill's API changes.

Look elsewhere when:

• You are not on uBill, or you need a provider-agnostic SMS abstraction across multiple vendors.
• You need capabilities beyond what this wrapper exposes, or you require an officially supported vendor SDK with a stability guarantee.
• Your onboarding cannot reliably collect a description, since brand creation will now fail without one.
• You cannot absorb breaking changes on the provider's timetable — this release demonstrates that v2 call sites break when uBill changes its rules.
• SMS is peripheral and a managed platform with UI-based brand management is sufficient.

How to Pitch It (Stakeholders)

For executives: This is a small but mandatory upgrade. uBill, our SMS provider, now refuses to create a brand name without a description, so v3 makes that argument required. The engineering change is one parameter plus handling two new rejection cases. The product change is a description field with a 500-character limit in brand onboarding. Doing this promptly keeps branded messaging provisioning working; staying on v2 means brand creation calls fail.

For engineering: The only signature change is createBrandName($brandName, $description). Update all call sites, add the field to persistence, and handle DESCRIPTION_REQUIRED (60) and DESCRIPTION_TOO_LONG (61) as distinct USmsRejectedException cases. No other API changes are reported. Effort is low, but the upgrade is time-sensitive because the v2 call shape cannot succeed.

For product: Add a required description to the brand creation flow, with guidance to include the website, social page or application, and intended use of the brand name. Validate length client-side and surface the two rejection reasons as specific, recoverable messages. This should improve first-attempt approval rates and reduce support load from failed submissions.

Risk to note: The package's release cadence follows uBill's contract changes. Budget for periodic dependency reviews, and avoid spreading direct createBrandName calls across the codebase so future signature changes remain a contained update.