Skip to main content
An Interface connects a Definable agent to an external messaging platform — Telegram, Discord, Signal, or any custom channel. It handles the full lifecycle: receiving messages, managing sessions, resolving user identity, running the agent, and sending responses back.

​
How It Works

Every incoming message flows through a structured pipeline: Concurrency is controlled by a semaphore — multiple messages can be processed in parallel up to max_concurrent_requests. Errors at any step trigger on_error hooks and send a configurable error message to the user.

​
Quick Example

Deploy an agent to Telegram in a few lines: 
import asyncio
from definable.agents import Agent
from definable.models import OpenAIChat
from definable.interfaces import TelegramInterface, TelegramConfig

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    instructions="You are a helpful assistant on Telegram.",
)

config = TelegramConfig(bot_token="YOUR_BOT_TOKEN")
interface = TelegramInterface(agent=agent, config=config)

asyncio.run(interface.serve_forever())
That is all it takes. The interface handles session management, conversation history, media, and concurrent users automatically.

​
Lifecycle

​
Starting

async with TelegramInterface(agent=agent, config=config) as interface:
    await interface.serve_forever()

​
Stopping

The interface shuts down gracefully on KeyboardInterrupt or when stop() is called. All active connections and resources are cleaned up.

​
BaseInterface Constructor

All interfaces accept these parameters:
​
agent
Agent
required
The Definable agent that processes messages.
​
config
InterfaceConfig
required
Configuration for the interface. Use a platform-specific config like TelegramConfig.
​
session_manager
SessionManager
Custom session manager. A default one is created if not provided.
​
hooks
List[InterfaceHook]
List of hooks to attach. Can also be added later with .add_hook().
​
identity_resolver
IdentityResolver
Cross-platform identity resolver. Maps platform user IDs to canonical user IDs for shared memory. See Identity Resolution.

​
InterfaceConfig

Base configuration shared by all interfaces:
ParameterTypeDefaultDescription
platformstr""Platform identifier
max_session_historyint50Maximum messages kept in session history
session_ttl_secondsint3600Session expiry time (1 hour)
max_concurrent_requestsint10Max simultaneous agent calls
error_messagestr"Sorry, something went wrong..."Message sent to user on error
typing_indicatorboolTrueShow typing indicator while processing
max_message_lengthint4096Max characters per outgoing message
rate_limit_messages_per_minuteint30Per-user rate limit
Like AgentConfig, it is immutable. Use with_updates() to create a modified copy: 
custom_config = config.with_updates(max_concurrent_requests=20, session_ttl_seconds=7200)

​
Adding Hooks

Chain hooks with .add_hook(): 
from definable.interfaces import TelegramInterface, LoggingHook, AllowlistHook

interface = (
    TelegramInterface(agent=agent, config=config)
    .add_hook(LoggingHook())
    .add_hook(AllowlistHook(allowed_user_ids={"12345", "67890"}))
)

​
Key Concepts

Sessions

Automatic per-user session management with history, state, and TTL expiry.

Hooks

Intercept messages and responses with composable hook functions.

Telegram

Deploy to Telegram with polling or webhooks, media support, and access control.

Discord

Deploy to Discord with guild/DM support, attachments, and access control.

Signal

Deploy to Signal with auto-managed Docker or bring-your-own container.

Identity

Map users across platforms to a single canonical identity for shared memory.

Multi-Interface

Run multiple interfaces concurrently with automatic restart and graceful shutdown.

Custom Interfaces

Build your own interface for any messaging platform.