Skip to main content
An Interface connects a Definable agent to an external messaging platform — Telegram, Discord, Slack, voice phone calls, Desktop, CLI, 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.agent import Agent
from definable.model import OpenAIChat
from definable.agent.interface import TelegramInterface

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

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

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, bot_token="YOUR_BOT_TOKEN") 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.
​
**kwargs
Any
Platform-specific parameters passed directly (e.g., bot_token, mode, allowed_user_ids). See each interface’s reference for available parameters.
​
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.

​
Common Parameters

All interfaces accept these base parameters as keyword arguments:
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
interface = TelegramInterface(
    agent=agent,
    bot_token="YOUR_BOT_TOKEN",
    max_concurrent_requests=20,
    session_ttl_seconds=7200,
)

​
Adding Hooks

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

interface = (
    TelegramInterface(agent=agent, bot_token="YOUR_BOT_TOKEN")
    .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.

Slack

Deploy to Slack with Socket Mode, Block Kit interactions, and slash commands.

WebSocket

Real-time bidirectional communication via JSON WebSocket protocol.

WhatsApp

Connect to WhatsApp via the Twilio WhatsApp API.

Email

IMAP polling + SMTP sending with thread tracking.

Call (Voice)

Voice calls via Twilio ConversationRelay.

Identity

Map users across platforms to a single canonical identity.

Multi-Interface

Run multiple interfaces concurrently with automatic restart.

Custom Interfaces

Build your own interface for any messaging platform.

​
Usage Examples

Telegram Bot

Step-by-step: agent with tools, memory, and voice notes.

Discord Bot

Step-by-step: agent with tools and persistent memory.

Slack Bot

Step-by-step: agent with tools and slash commands.

Multi-Platform

Serve one agent across Telegram, Discord, and Slack.