Skip to main content
Early Access Program

Turn.io Lua Apps are currently part of an early access program and are not yet generally available. If you are interested in building custom applications and would like to participate, please reach out to our support team to discuss your use case.

Building Lua Apps on Turn.io

Welcome to the developer guide for building Lua Apps on the Turn.io platform! This guide will walk you through everything you need to know to create, test, and deploy powerful applications that extend the capabilities of Turn.

What are Turn Lua Apps?​

Turn Lua Apps are self-contained packages of Lua code that run securely within the Turn platform. They allow you to implement custom business logic that can be triggered by platform events, incoming HTTP requests, or directly from a Journey.

With Lua Apps, you can:

  • Integrate with external APIs and third-party systems.
  • Create complex, stateful workflows that go beyond standard Journey capabilities.
  • Build custom backend logic for your messaging services.
  • Handle asynchronous events, like waiting for a payment confirmation webhook.

Getting Started: Your First App​

The fastest way to get started is using our Turn Lua SDK Docker image, which provides a complete development environment with scaffolding, testing, and packaging tools.

Quick Start with Docker SDK​

  1. Set up the Docker alias (one-time setup):

    # Add this to your ~/.bashrc or ~/.zshrc
    alias turn-app='docker run --rm -v $(pwd):/workspace ghcr.io/turnhub/turn-lua-sdk:latest turn-app'

  2. Create a new app:

    turn-app new my_app
    cd my_app

  3. Your project structure will look like this:

    my_app/
    ├── my_app.lua                  # Your main application file
    ├── spec/
    │   └── my_app_spec.lua         # Test file using lester framework
    ├── assets/
    │   ├── manifest.json           # App metadata (required)
    │   ├── README.md               # Documentation shown in Turn UI
    │   ├── journeys/               # Journey markdown files
    │   ├── templates/              # Message template JSON files
    │   ├── flows/                  # WhatsApp Flow JSON files
    │   └── liquid/                 # Liquid templates
    ├── lib/                        # Additional Lua modules
    ├── Makefile                    # Convenient build commands
    ├── README.md                   # Project documentation
    └── .gitignore

  4. Run your tests:

    make test          # Run tests once
    make watch         # Watch mode - auto-run tests on file changes

  5. Package for deployment:

    make build         # Creates my_app-0.0.1.zip

Alternative: Using the Template Directory​

If you prefer not to use Docker, you can still use our traditional template:

  1. Download the Template: Get a copy of the lua_app_template directory from the repository.

  2. Run Tests:

    # From project root - builds Luerl image and runs tests
    make test-lua-app APP=my_app

You are now ready to start developing your app!

Next Steps

Learn about Core Concepts to understand how Lua apps work and how to integrate them with Journeys.