Skip to main content
Every inbound message passes through an ordered middleware chain before reaching any agent. Each middleware stage can inspect, enrich, or reject the message. The pipeline runs synchronously — each stage completes before the next begins. The bank controls which middleware runs, in what order, and with what configuration.

​
Pipeline stages

1

CommandsAuthMiddleware

Intercepts slash commands (e.g., /info, /new, /payers). When the ACTIVE_COMMANDS environment variable is set to false, this middleware blocks all command messages and sends a notification to the sender.When commands are enabled, the message passes through to the registered command handlers on the LogicRouter. This allows operators and testers to invoke diagnostic commands during controlled rollouts.
ConfigurationValue
Environment variableACTIVE_COMMANDS
Defaulttrue (commands enabled)
Behavior when disabledBlocks all / prefixed messages, sends “Commands are disabled”
2

PhoneFakerMiddleware

Development-only middleware that allows testers to simulate different sender identities by overriding the phone number associated with a session. Uses a Redis hash to map session IDs to substitute phone numbers.Testers can use /phone +1234567890 to set a specific identity, or /new to generate a random phone number — enabling testing of onboarding flows, blocked states, and CIP-pending scenarios without real sender accounts.
PhoneFakerMiddleware must be disabled in production. It is a development tool for testing different sender identities. In production, the sender’s actual phone number from the channel connector is used.
3

PayhubAuthMiddleware

Authenticates the sender by phone number against the identity service. This middleware:
  1. Validates that a phone number is present on the inbound message
  2. Normalizes the phone number to a standard format
  3. Queries the identity service for the sender’s profile
  4. Injects the sender’s identity (name, compliance status, payment methods, country) into the message metadata
The LogicRouter uses this injected metadata to route the message to the appropriate agent.On service failure (HTTP 404), the middleware sets the unavailable_service flag in metadata but does not block the message. The LogicRouter detects this flag and routes to the service unavailable agent for graceful degradation.
This middleware never blocks message delivery. Authentication failures result in routing to the appropriate fallback agent — not in dropped messages.
4

ContactDecodingMiddleware

Normalizes contact information from the message payload. Standardizes phone numbers and contact data formats before they reach the agent layer.
5

ChatwootMiddleware

Syncs conversations to Chatwoot for human agent visibility and handoff. When enabled, every message and response is mirrored to a Chatwoot inbox, allowing human agents to:
  • Monitor active conversations in real time
  • Take over a conversation when escalation is triggered
  • Review conversation history for quality assurance
ConfigurationEnvironment variable
Enable/disableCHATWOOT_ENABLE_MIDDLEWARE
Chatwoot URLCHATWOOT_URL
Access keyCHATWOOT_ACCESS_KEY
Account IDCHATWOOT_ACCOUNT_ID
Inbox nameCHATWOOT_INBOX_NAME
This middleware is optional and can be disabled entirely without affecting agent behavior.

​
Middleware registration order

Middleware stages execute in registration order. The order in main.py defines the pipeline: 
gateway.register_middleware(commands_auth_middleware)
gateway.register_middleware(phone_faker_middleware)
gateway.register_middleware(payhub_auth_middleware)
gateway.register_middleware(contact_decoding_middleware)
gateway.register_middleware(chatwoot_middleware)
Any middleware can halt the pipeline by returning False. For example, CommandsAuthMiddleware returns False when commands are disabled, preventing the command message from reaching subsequent middleware or the agent.

​
Security considerations

  • Phone normalization: PayhubAuthMiddleware normalizes phone numbers before querying the identity service, preventing identity spoofing through formatting variations.
  • Identity injection: Sender identity is injected into message metadata by the middleware — not provided by the sender. The agent receives pre-authenticated context.
  • Graceful failure: Authentication middleware does not drop messages on failure. Service outages result in routing to the service unavailable agent, maintaining a response to the sender.
  • Development isolation: PhoneFakerMiddleware uses a dedicated Redis hash and is controlled by deployment configuration. It produces no effect in production when disabled.

​
Configuration and control

ControlDescription
Middleware orderingThe bank defines which middleware runs and in what sequence
Command availabilityACTIVE_COMMANDS toggles slash command access
Chatwoot integrationIndependently enabled or disabled via environment variables
Phone fakerDisabled in production; enabled only in development environments
Custom middlewareThe bank can add new middleware stages to the pipeline without modifying existing stages