Interfaces Overview

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()

interface = TelegramInterface(agent=agent, bot_token="YOUR_BOT_TOKEN")
await interface.start()
# ...
await interface.stop()

# Starts automatically if not running, blocks until stopped
asyncio.run(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

required

The Definable agent that processes messages.

Any

Platform-specific parameters passed directly (e.g., bot_token, mode, allowed_user_ids). See each interface’s reference for available parameters.

SessionManager

Custom session manager. A default one is created if not provided.

List[InterfaceHook]

List of hooks to attach. Can also be added later with .add_hook().

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:

Parameter	Type	Default	Description
`platform`	`str`	`""`	Platform identifier
`max_session_history`	`int`	`50`	Maximum messages kept in session history
`session_ttl_seconds`	`int`	`3600`	Session expiry time (1 hour)
`max_concurrent_requests`	`int`	`10`	Max simultaneous agent calls
`error_message`	`str`	`"Sorry, something went wrong..."`	Message sent to user on error
`typing_indicator`	`bool`	`True`	Show typing indicator while processing
`max_message_length`	`int`	`4096`	Max characters per outgoing message
`rate_limit_messages_per_minute`	`int`	`30`	Per-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.

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.

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.

Get Started

Basics

Capabilities

Advanced

How It Works

Quick Example

Lifecycle

Starting

Stopping

BaseInterface Constructor

Common Parameters

Adding Hooks

Key Concepts

Sessions

Hooks

Telegram

Discord

Slack

WebSocket

WhatsApp

Email

Call (Voice)

Identity

Multi-Interface

Custom Interfaces

Usage Examples

Telegram Bot

Discord Bot

Slack Bot

Multi-Platform

​How It Works

​Quick Example

​Lifecycle

​Starting

​Stopping

​BaseInterface Constructor

​Common Parameters

​Adding Hooks

​Key Concepts

Sessions

Hooks

Telegram

Discord

Slack

WebSocket

WhatsApp

Email

Call (Voice)

Identity

Multi-Interface

Custom Interfaces

​Usage Examples

Telegram Bot

Discord Bot

Slack Bot

Multi-Platform

How It Works

Quick Example

Lifecycle

Starting

Stopping

BaseInterface Constructor

Common Parameters

Adding Hooks

Key Concepts

Usage Examples