The Flow Engine

The Flow Engine turns a business owner’s words into reviewed, production-ready WhatsApp customer journeys powered by AWS.

Comment

Flow Engine: Human-first WhatsApp experiences on AWS

Inspiration

Flow Engine is being built for businesses across West Africa, beginning in Nigeria, where WhatsApp is often a primary channel for customer service, commerce, recruitment and everyday business operations.

Business owners can easily explain how an experience should work—“show these options, collect this information, apply these rules and notify the right person”—but converting that intent into reliable messages, branches, forms, integrations and operational controls normally requires developers.

Our first local partner is 234 Jobs Limited, a Nigerian WhatsApp-native work and hiring platform. It represents our first vertical: recruitment and workforce operations. Its real candidate, employer and administrator journeys showed us that AI-generated conversations alone were not enough. Owners need to see every path, understand what information is collected, review assumptions and approve exactly what will happen before anything reaches customers.

234 Jobs is an important proof of the platform in one vertical, but it is not the boundary of the product. We created Flow Engine as a reusable foundation that can support many businesses and industries by combining natural-language authoring, human review, deterministic compilation and an AWS-native WhatsApp runtime.

The AWS-native Flow Engine and owner workspace presented here were created during the hackathon, informed by lessons from an earlier per-tenant prototype and by our work with 234 Jobs in Nigeria.

What it does

Flow Engine lets a non-technical business owner describe the experience customers should have on WhatsApp.

The owner workspace turns that description into:

  • A business brief containing confirmed facts, assumptions and unanswered questions.
  • A visual customer journey showing messages, choices, conditions, actions and branches.
  • Nested WhatsApp Forms for complex, multi-screen data collection.
  • A phone preview driven by the same compiled flow the runtime will execute.
  • Versioned drafts that can be reviewed and approved before activation.
  • Separate owner and administrator controls for authoring, numbers, connections and activation.
  • Connection and delivery evidence for operators.

Owners never need to edit JSON or understand WhatsApp’s underlying API rules. They can inspect what customers will see, revise individual steps and understand where every choice leads.

The runtime supports text, reply buttons, lists, images, media carousels, typed responses, media uploads and both static and server-driven WhatsApp Forms.

In the recruitment and workforce vertical, our local partner 234 Jobs demonstrates how the platform can represent complete candidate, employer and administrator journeys: discovering opportunities, collecting structured information, navigating application paths, reviewing records and coordinating human follow-up.

Flow Engine is designed to expand beyond that first vertical. Each new vertical can provide its own vocabulary, actions, records, rules and botflow while reusing the same authoring, validation, versioning, messaging and execution foundation. This creates a path to serve additional Nigerian and West African businesses across areas such as commerce, logistics, education and training, and other service industries.

How we built it

The system has three deliberately separated layers.

1. Human-first authoring

The owner describes the business in natural language. The assistant uses Amazon Bedrock inference to update a typed experience plan through constrained tools.

The model does not write executable JSON, publish forms or activate customer experiences directly. It can propose steps, choices, questions and saved answers, but deterministic code compiles and validates the result.

The workspace also shows what the assistant understood, including:

  • Confirmed business facts.
  • Assumptions that require review.
  • Open questions.
  • Business roles and responsibilities.
  • Rules and conditions.
  • Information that will be recorded.

This keeps the owner involved throughout the authoring process instead of hiding important decisions behind AI-generated output.

2. Deterministic compilation and review

The experience plan compiles into Flow Engine’s canonical botflow.whatsapp.v2 format and the required WhatsApp Flow documents.

Before a version can be saved, the system checks:

  • Flow schema validity.
  • Missing or unreachable paths.
  • Dead ends and invalid transitions.
  • Unsupported actions or conditions.
  • WhatsApp message, button, list and carousel limits.
  • WhatsApp Flow component and navigation rules.
  • Whether every referenced action is supported by the selected business vertical.

The visual journey map and phone preview are projections of this compiled result, so the owner reviews what the engine will actually run.

Saving, publishing and activation are deliberately separate actions. Owners can preserve and review a version without affecting customers. WhatsApp Forms are published only after approval, and an approved version becomes active only on the selected WhatsApp number.

3. AWS-native execution

The deployed engine runs in us-east-1 using:

  • AWS End User Messaging Social for WhatsApp messaging and WhatsApp Flow lifecycle operations.
  • Amazon SNS and Amazon SQS for durable inbound event processing.
  • Amazon ECS on AWS Fargate for the application runtime.
  • Amazon RDS for PostgreSQL for tenants, conversations, versions and operational state.
  • Amazon S3 for customer-provided media and saved form data.
  • AWS Secrets Manager for database credentials and encryption material.
  • Amazon CloudWatch for critical-path metrics, logs and alarms.
  • AWS CodeBuild and Amazon ECR for reproducible ARM64 container builds and image scanning.
  • AWS CDK and AWS CloudFormation for infrastructure deployment.

When a customer messages a business number, AWS End User Messaging Social publishes the event to Amazon SNS and Amazon SQS.

The engine identifies the tenant from the receiving number, loads the conversation’s pinned flow version, executes the turn and replies using SendWhatsAppMessage.

This allows multiple businesses and WhatsApp numbers to use one engine while retaining isolated configurations, records, permissions and flow versions. It also lets us add new verticals without rebuilding the core messaging platform for every partner.

Challenges we faced

The hardest work was not generating a conversation—it was making every boundary reliable.

We encountered real differences between documented and observed WhatsApp events, including missing top-level identifiers, duplicate form-completion events and media objects whose final filenames are chosen by AWS End User Messaging Social.

Server-driven WhatsApp Forms introduced additional challenges involving encryption, public-key registration, navigation payloads, validation behavior and safe updates to already-published forms.

We also had to separate the reusable engine from the requirements of its first recruitment and workforce vertical. Business-specific actions now belong to a vertical contract, while the core engine remains product-independent and ready to support additional local partners.

Finally, we learned that technical correctness was not enough. Early owner-workspace versions exposed internal concepts instead of answering the questions owners actually have:

  • What will my customer experience?
  • What assumptions did the assistant make?
  • Where does each choice lead?
  • What information will be saved?
  • What requires a person to follow up?
  • What exactly changes when I go live?

Those questions shaped the human-first review journey.

What we learned

AI works best here as an authoring collaborator, not as the production runtime.

The model can interpret an owner’s intent and propose changes, while a deterministic compiler, validator and execution engine preserve operational safety.

We also learned that WhatsApp Forms must be treated as nested subgraphs. A form can contain its own screens, navigation, validation and completion paths while remaining one step in the larger customer journey.

Operational evidence is equally important. AWS accepting a message is not the same as proving delivery or reading. The workspace therefore distinguishes connection state, send acceptance, delivery reports and read reports without making unsupported claims.

Most importantly, building for West African businesses requires more than translating an existing interface. The workspace must reflect how owners actually describe their operations, how staff divide responsibilities and how WhatsApp functions as part of the business itself. Working with a local partner in one vertical gave us concrete requirements while preserving a platform that can grow into many more.

What we accomplished

The AWS-native engine is deployed in us-east-1. We exercised its complete capability tour through AWS End User Messaging Social on a real phone, including both static and server-driven WhatsApp Forms.

We established 234 Jobs Limited as our first local partner and the first proven vertical for Flow Engine. Its recruitment and workforce requirements helped us validate the separation between the reusable engine and business-specific behavior.

The new owner workspace, visual journey model and human-first review workflow have been implemented and tested locally.

We intentionally kept the existing live 234 Jobs experience untouched while building and validating the new AWS-native platform.

What’s next

Our next step is a controlled pilot with 234 Jobs on a non-production WhatsApp number, followed by business validation before migrating its live experience to the AWS-native Flow Engine.

That pilot will validate the recruitment and workforce vertical without making the platform specific to one company. We then plan to onboard more local partners across additional verticals in Nigeria before expanding across West Africa.

Each business will be able to express its own vocabulary, actions, records and customer journey while sharing the same secure, validated AWS-native authoring and execution platform.

Built With

Share this project:

Updates

Submission history