Architecture Challenges in an Omnichannel Messaging Platform

Introduction

Building an omnichannel messaging platform goes far beyond simply sending and receiving messages.

When a company centralizes channels such as WhatsApp, Facebook Messenger, Instagram, WebChat, Telegram, proprietary APIs, and messaging brokers into a single solution, significant challenges arise related to scalability, availability, security, and data consistency.

A well-planned architecture is essential to guarantee a good experience for the end user.

Furthermore, it must be able to withstand adverse scenarios such as:

• Usage spikes
• Processing bottlenecks
• External integration failures
• Large volumes of simultaneous messages
• Network instability
• Malicious attacks

A messaging platform needs to be resilient, scalable, and observable in order to keep operating even when part of the infrastructure is failing.

Architecture Overview

A modern omnichannel messaging architecture typically has several specialized layers.

Conectores Externos
        ↓
Webhook
        ↓
Backend
        ↓
Fila
        ↓
Consumer
        ↓
Processor
        ↓
Workflow Engine
        ↓
Banco de Dados

Backend
        ↓
WebSocket
        ↓
Frontend

Each layer has specific responsibilities and its own challenges.

Webhooks

Webhooks represent the platform's entry point.

It is through them that messages coming from the various connected channels arrive.

Main challenges

Receiving messages from multiple sources

An omnichannel platform can receive events from:

• WhatsApp Business API
• Facebook Messenger
• Instagram
• WebChat
• Telegram
• Brokers
• Proprietary APIs

Each integration has different formats and behaviors.

The platform must normalize this information into a single internal model.

Responding quickly

Most providers work with aggressive timeouts.

Example:

Webhook → Timeout de 5 segundos

If the full processing happens before responding, there is a risk of:

• Timeout
• Retransmission
• Duplicate messages
• Delivery failures

That's why the webhook must:

1. Validate the message
2. Persist or enqueue it
3. Respond immediately

Validating authenticity

Every incoming request must have its origin validated.

Examples:

• HMAC SHA256
• JWT
• Digital signatures
• Shared tokens

This prevents malicious agents from sending fake messages to the platform.

Returning errors correctly

Avoid generic responses such as:

500 Internal Server Error

Whenever possible:

400 Bad Request

for an invalid payload.

401 Unauthorized

for an invalid signature.

403 Forbidden

for unauthorized access.

This makes monitoring and troubleshooting easier.

Backend

The backend is responsible for exposing the APIs used by the frontend and coordinating the platform's operations.

Main challenges

High availability

Even during high message volumes, the backend must remain available for:

• Browsing conversations
• Manually sending messages
• Managing contacts
• Settings

A congested queue must not make the administrative system unavailable.

Security

All communication must use:

• HTTPS
• JWT
• Refresh Tokens
• Permission control
• Auditing

Ensuring that each user only accesses authorized data.

Consistent responses

In case of error, the backend must provide clear information.

Example:

{
  "error": "validation_error",
  "field": "phone",
  "message": "Número inválido"
}

Allowing the frontend to properly guide the user.

Frontend

The frontend is the point of contact between the platform and its operators.

Main challenges

Performance

The system must be fast and responsive.

Even companies with thousands of simultaneous conversations need to maintain a smooth experience.

Guiding the user

In unexpected situations, the system must clearly inform:

• What happened
• What the user should do
• Whether it's possible to try again

Example:

Falha ao enviar mensagem.
Clique para tentar novamente.

Displaying status

The operator needs to know:

• Message sent
• Message delivered
• Message read
• Message failed

As well as the exact time of each event.

Real-time updates

The user should not have to rely on:

F5
Atualizar página

All updates must happen automatically through WebSockets.

WebSocket

WebSockets are responsible for real-time communication.

Main challenges

Resilient connections

The system must support:

• Automatic reconnections
• Network drops
• Connection changes
• Token refresh

Without harming the operator's experience.

Correct event distribution

Not every user should receive every event.

Example:

Mensagem Empresa A

Must not reach:

Usuário Empresa B

Correct routing is essential.

Permission control

Every event must validate:

• Company
• User
• Profile
• Permissions

Before being distributed.

Consumer

The consumer processes messages received from the queues.

Main challenges

Identifying the origin

When consuming a message it must be possible to determine:

• Channel
• Company
• Conversation
• Customer

Ensuring traceability.

Routing to the correct tenant

A WhatsApp message from one company can never be processed in the context of another company.

Isolation between tenants is mandatory.

Dead Letter Queue

Problematic messages must not block the main queue.

Recommended flow:

Fila Principal
      ↓
Falha
      ↓
Dead Letter Queue

Circuit Breaker

If an external provider is unavailable:

Facebook indisponível

it must not impact:

WhatsApp
Instagram
WebChat

Prefetch control

The number of messages processed simultaneously must respect the available resources.

Example:

CPU disponível
Memória disponível
Número de workers

Enabling horizontal scalability.

Processor

The processor is responsible for sending messages to external channels.

Main challenges

Building the request

Each channel has its own requirements.

Example:

WhatsApp:

{
  "to": "...",
  "type": "text"
}

Facebook:

{
  "recipient": "...",
  "message": {}
}

The processor needs to transform the internal model into the format expected by each provider.

Credential management

Each company can have:

• Tokens
• Keys
• Certificates

Different for each integration.

Scalability

Just like the consumer, the processor must:

• Work with queues
• Use configurable prefetch
• Scale horizontally

According to message volume.

Workflow Engine

The workflow layer is responsible for the platform's automations.

Main challenges

Building automated flows

Examples:

• Chatbots
• Automated service
• Queue distribution
• External integrations

Low latency

The user expects near-instant responses.

Slow flows harm the service experience.

Avoiding excessive queries

A common mistake is performing multiple database queries at every step of the flow.

This causes:

• Higher latency
• Higher cost
• Lower scalability

Whenever possible, one should use:

• Cache
• In-memory context
• Preloaded data

Traceability

It is essential to log:

• Which block was executed
• Which condition was evaluated
• Which path was followed

Enabling auditing and diagnostics.

Non-blocking external calls

When running external integrations:

ERP
CRM
Gateway de Pagamento
API de Consulta

the workflow must not block the entire queue while waiting for a response.

An approach based on Promises and asynchronous processing reduces bottlenecks.

Scalability

Just like consumers and processors, workflows must allow:

• Concurrency control
• Configurable prefetch
• Horizontal scalability

According to demand.