genesis 2026.3.21

Async Python library for FreeSWITCH Event Socket Layer (ESL) - Build high-performance telephony applications with asyncio

Genesis

Genesis is a Python library designed to build asynchronous applications that interact with FreeSWITCH through the Event Socket Layer (ESL).

Features

• Asynchronous by Design: Built with asyncio for high-performance, non-blocking I/O.
• Inbound, Outbound, and Consumer Modes: Supports all major ESL modes for comprehensive FreeSWITCH integration.
• Decorator-Based Event Handling: A simple and intuitive way to handle FreeSWITCH events.
• OpenTelemetry Support: Built-in instrumentation for tracing connections and commands.
• Extensible and Customizable: Easily extend and customize the library to fit your needs.

Installation

Install Genesis using pip:

pip install genesis

For better asyncio performance on Unix (Linux and macOS), use the optional uvloop extra: pip install genesis[uvloop]. See the Installation Guide for details.

Quickstart

Inbound Socket Mode

import asyncio
from genesis import Inbound

async def uptime():
    async with Inbound("127.0.0.1", 8021, "ClueCon") as client:
        return await client.send("uptime")

async def main():
    response = await uptime()
    print(response)

asyncio.run(main())

Consumer Mode

import asyncio
from genesis import Consumer

app = Consumer("127.0.0.1", 8021, "ClueCon")

@app.handle("HEARTBEAT")
async def handler(event):
    await asyncio.sleep(0.001)
    print(event)

asyncio.run(app.start())

Outbound Socket Mode

import asyncio
from genesis import Outbound

async def handler(session):
    await session.answer()
    await session.playback('ivr/ivr-welcome')
    await session.hangup()

app = Outbound(handler, "127.0.0.1", 5000)

asyncio.run(app.start())

Documentation

Full documentation is available on the documentation website.

To preview the docs locally, install Hugo and run:

hugo server --source docs --disableFastRender

Running Tests

Install development dependencies with Poetry and execute the test suite using tox:

poetry install
tox

How to Contribute

Contributions are welcome! Whether it's improving documentation, suggesting new features, or fixing bugs, your help is appreciated.

Please read our Contributing Guide and Code of Conduct to get started.

Contributors

Vitor Hugo

RL

Dongwoon Kim

License

This project is licensed under the MIT License - see the LICENSE.md file for details.