Decoupling Business Messaging: A Deep Dive into the X‑Pigeon Platform Architecture

Problem Background

Rapid growth of online services makes instant‑messaging tools such as Enterprise WeChat and Feishu critical for user interaction. Three systemic issues emerged when each service embedded its own message‑sending code:

Strong coupling between business logic and messaging logic, so a failure in the messaging layer can halt the entire workflow.

Duplicated message‑sending utilities across services, making updates error‑prone and costly.

Intermittent message loss: HTTPS calls to external platforms often report success while the end user receives nothing, complicating troubleshooting.

Design Goals

Provide a centralized platform (named X‑Pigeon) that decouples message creation from delivery, manages the full message lifecycle, enforces platform‑specific rate limits, and offers reusable templates to reduce integration effort.

Message Decoupling Model

Messages are expressed as a composition of three configurable elements:

Scenario : business context that triggers the message.

Robot : the sending bot or application (e.g., a Feishu bot, an Enterprise WeChat robot).

Template : the concrete payload format (text, markdown, card, etc.).

By configuring these three parts, developers obtain a complete Message object without writing duplicate code.

Unified Message Lifecycle

All messages, regardless of target platform, share the same state machine:

Initialization

Sending

Success

Retrying

Failure

Each message receives a globally unique identifier, enabling operators to query its current state at any time.

Rate‑Limiting Strategy

External platform limits are the root cause of many dropped messages. The platform enforces the following quotas (as documented by the providers):

Feishu: 50 requests / sec per app; 1,000 messages / min per app; 100 webhook messages / min for group bots; 5 messages / sec per user or group.

Enterprise WeChat: 20 messages / min per robot; 30 messages / min per user (additional stricter limit for user‑level sending).

Two rate‑limiting algorithms are implemented behind custom annotations, allowing a per‑platform switch:

Simple counter : increments a counter within a fixed time window.

Token‑bucket : refills tokens at a configured rate, permitting burst traffic while respecting the average quota.

Queue‑build‑up scenario

Enterprise WeChat limits each user to 30 messages / min. If scenario A generates 210 messages at once, the platform needs at least 7 minutes to flush them (210 ÷ 30 = 7). During this interval, a message from scenario B must wait behind the entire A queue, causing noticeable latency under peak load.

To mitigate the bottleneck, the system partitions the message queue by scenario . Consumers poll each partition independently instead of draining one queue completely before processing the next. This reduces cross‑scenario blocking. For very high volumes, the recommendation is to provision multiple robots so that each robot operates under its own quota.

Service‑Level Throttling via SCF

The X‑Pigeon service is exposed through Serverless Cloud Functions (SCF). SCF provides built‑in interface throttling, which can be configured to limit API calls at the entry point. This approach simplifies implementation, reduces operational complexity, and guarantees stable behavior under high concurrency.

Message Templates

To accelerate integration, X‑Pigeon supplies a library of ready‑made templates for common notification types. Developers only need to fill required parameters and invoke the API. Below is a representative Feishu template payload (JSON) that produces a fully formatted card message:

{
  "msg_type": "interactive",
  "card": {
    "config": {"wide_screen_mode": true},
    "header": {"title": {"tag": "plain_text", "content": "Order Alert"}},
    "elements": [
      {"tag": "div", "text": {"tag": "lark_md", "content": "*User*: **{{user}}**"}},
      {"tag": "div", "text": {"tag": "lark_md", "content": "*Amount*: **{{amount}}**"}}
    ]
  }
}

Only the placeholders (e.g., {{user}}, {{amount}}) need to be replaced at runtime.

Conclusion

The X‑Pigeon platform centralizes message management, enforces platform‑specific rate limits, and provides reusable templates, thereby improving delivery reliability and reducing maintenance overhead. Planned enhancements include transactional messaging, priority ordering, and night‑time delivery suppression.