# channel-extension

Adopt this skill: https://proskills.md/skills/other/dpro-at-tel-agent-claude-skills-channel-extension

Page: https://proskills.md/skills/other/dpro-at-tel-agent-claude-skills-channel-extension
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude/skills/channel-extension/SKILL.md
size: 8027
upstream: https://github.com/dpro-at/tel-agent/blob/main/.claude/skills/channel-extension/SKILL.md

````text
---
name: channel-extension
description: Use when adding a new messaging channel to Tel-Agent or changing an existing one — a transport under api/channels/, its official extension manifest, its settings card, tests, health and docs. Covers the file checklist, the two inbound shapes (dial-out and the public door), the credential and signature rules that are not negotiable, the declarative setup descriptor the generic card draws from, and the test shape every channel ships with.
---

# Building a channel extension

You are adding a messaging channel to Tel-Agent. A channel is a route a **customer**
uses to reach a business — someone is typing on the other end. If nobody outside the
business is on the other end, it is an integration, not a channel, and it is reached
through the HTTP tool instead (Rule 5 in `CLAUDE.md`). Do not build it here.

**Read first, in this order:** `CLAUDE.md` (the contract), `docs/SPEC.md` §B9 (secrets)
and §B13 (channels), then `api/channels/discord.py` end to end. Discord is the model
every channel copies: a dial-out transport with a supervisor loop, an answering policy,
storage with dedup, and delivery-before-storage. For a channel that receives webhooks,
also read `api/channels/meta_chat.py` and `api/routes/meta_chat_channels.py` — that is
the public door, and its guards are the whole of this product's exposed surface.

Write everything from the platform's **official documentation** and from the shape of
the existing modules. Write it fresh. Never paste code from another product into this
repository, never name another product anywhere in it, and never add a runtime
dependency — `httpx`, `websockets`, `cryptography` and the standard library cover every
platform we ship.

## What a channel consists of

One kind, one transport module, one manifest, one descriptor, one test file. In order:

| # | Path | What goes there |
|---|---|---|
| 1 | `api/channels/<kind>.py` | The transport. Module surface below. |
| 2 | `api/extensions/builtin/<kind>.py` | `MANIFEST` + `register(context)`. Copy the Discord one; change slug, name, description. Category `channels`, origin `official`, scopes `conversations.write`, `messages.read`, `messages.write`, hooks `message.received`, ui_slots `conversation.detail`. |
| 3 | `api/extensions/builtin/__init__.py` | Append the module to `BUILTIN`. |
| 4 | `api/models/conversation.py` | The kind is already in `CHANNEL_KINDS` (one migration added every kind of this wave). If yours is not, add it **and** an Alembic revision that widens the `channel_kind` CHECK constraint — `tests/test_migrations.py` runs it on SQLite and PostgreSQL. |
| 5 | `api/channels/generic.py` | Add the module's import path to `_DECLARED`. The registry imports it on first read; that is what serves its card and its routes. |
| 6 | `api/main.py` | Dial-out channels: append `transport.loop(sessionmaker)` to `background`. Door channels: nothing — the generic public route dispatches by kind. |
| 7 | `tests/test_<kind>_channel.py` | The test file. Shape below. |
| 8 | `web/components/brands/marks.tsx` + `source/<kind>.svg` | The mark, when the platform has a logo. Record the source and licence in `web/components/brands/README.md`. A channel with no owner (SMS, IRC) gets a drawn glyph in `web/components/shell/channel-mark.tsx`. |
| 9 | `web/app/[locale]/settings/settings.tsx` | Add the kind to `GENERIC_CHANNELS`. The card draws itself from the descriptor. |
| 10 | `locales/en/web.json` | The display name under `"channels"`. Other languages follow through the translation pipeline; do not touch thirty-four files. |
| 11 | `docs/SPEC.md` §B13, `README.md` icon row, `docs/brand/channels/` | One row, one icon, one table line. |

## The transport module surface

Every module exposes the same names, so the generic route, the health rollup and the
tests can treat them alike. Signatures are the ones `api/channels/discord.py` has;
keep them.

```python
KIND = "<kind>"
SETUP = Setup(...)  # the descriptor, see below
INBOUND = "dial_out"  # or "door"

def make_client() -> httpx.AsyncClient: ...  # tests monkeypatch this
async def probe(client, credentials: dict[str, str]) -> str:
    ...
    # "Test connection". Returns the identity the platform reports (bot name, number,
    # account) — the card shows it. Raises ChannelRefused on a bad credential.

async def send_text(client, credentials, target: str, text: str) -> None: ...
def message_text(event, identity) -> str | None: ...  # the answering policy: None = ignore
async def ingest(db, channel, event) -> int | None:
    ...
    # store one inbound line; None when it was a duplicate or not for us

async def respond(sessionmaker, channel_id: int, message_id: int) -> None: ...
def schedule_reply(sessionmaker, channel_id: int, message_id: int) -> None: ...

# optional
def credentials_changed(channel_id: int) -> None:
    ...
    # What the module is told after the operator writes this channel's fields, so it can
    # drop anything it cached on the strength of the old ones — an access token bought
    # with a secret that has just been replaced would otherwise keep working until it
    # expired, which is a rotation that did not take effect. A module that caches nothing
    # declares nothing; `api/routes/generic_channel.py` calls it only when it is there.

def reply_target(conversation) -> str | None:
    ...
    # The address `send_text` needs for this thread, when it is not the conversation's
    # own `external_id` — a room id, a thread key, a mailbox. Declare nothing and
    # `generic.reply_target_of` falls back to `external_id`. It is what the human
    # takeover route delivers to as well, so a channel that answers somewhere other
    # than where the customer wrote from owes this one function and nothing else.

# dial-out only
async def loop(sessionmaker) -> None: ...  # the supervisor, reconciles every 15 s

# door only
async def receive(db, channel, request: Request) -> Response:
    ...
    # verify, dedup, store, schedule, acknowledge. One refusal for every failure.
```

`credentials` is the decrypted JSON of `Channel.credentials_encrypted` — a dict keyed by
the descriptor's field names. Never read it on the inbound hot path for anything other
than a signature check; per-channel state that every message needs lives in
`settings_json`, which is plain.

### Shared helpers — use these, do not copy Discord

`api/channels/generic.py` holds the half of a transport that is the same on every
channel. A declarative channel writes the platform-specific half only: its descriptor,
its signature check, `probe`, `send_text`, `message_text`, `ingest`, and its `receive`
or `loop`. `split_text` is a line delegating to `split_on_words` below. Everything below
is already written.

| Helper | What it does |
|---|---|
| `channels()` | The registry, populated on first read. `module_for(kind)` and `dial_out_modules()` go through it, so no import order can change what an installation has. Never read `CHANNELS` directly. |
| `public_url_for(request, settings)` | The address the platform called, for a signature computed over it. `PUBLIC_BASE_URL` when the installation has one, else the forwarded headers — the one place in this product where those are read, and the reasoning is in the function. The settings card builds its `webhook_url` on the same base, so the two cannot disagree. |
| `conversation_for(db, channel, external_id, title=None)` | This customer's open thread, and whether it was just started. |
| `store_line(db, conversation, role, text, language=None)` | One line into the transcript. |
| `seen_before(conversation, kind, message_id)` | Dedup. A ring of the last 32 platform ids in `state_json[kind]`, because a platform does not retry in order. |
| `announce(db, channel, conversation, message, started)` | The `conversation.started` and `message.received` hooks. |
| `preview(text)` | One line of a customer's words, for a notification. |
| `reply_target_of(module, conversation)` | Where a reply goes: 
````

## File: README.md
upstream: https://github.com/dpro-at/tel-agent/blob/main/README.md

```text
<div align="center">

<img src="logo.png" alt="Tel-Agent" height="130">

# AI phone assistant

**Connect any phone line to any AI model. Self-hosted, bring your own keys.**

<!-- Two rows of marks. The first is the channels that ship today (call and
     landline are two drawings of the one phone channel); the second is the wave-2
     channels being added now, tracked in the issues labelled "channel". The rows are
     about recognition, not arithmetic. -->
<p>
  <img src="docs/brand/channels/call.svg" alt="Call" title="Call" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/landline.svg" alt="Landline" title="Landline" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/web-chat.svg" alt="Web chat" title="Web chat" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/sms.svg" alt="SMS" title="SMS" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/email.svg" alt="Email" title="Email" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/whatsapp.svg" alt="WhatsApp" title="WhatsApp" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/telegram.svg" alt="Telegram" title="Telegram" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/messenger.svg" alt="Messenger" title="Messenger" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/instagram.svg" alt="Instagram" title="Instagram" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/discord.svg" alt="Discord" title="Discord" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/slack.png" alt="Slack" title="Slack" height="26">
</p>
<p>
  <img src="docs/brand/channels/teams.svg" alt="Microsoft Teams" title="Microsoft Teams" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/signal.svg" alt="Signal" title="Signal" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/viber.svg" alt="Viber" title="Viber" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/google-chat.svg" alt="Google Chat" title="Google Chat" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/mattermost.svg" alt="Mattermost" title="Mattermost" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/matrix.svg" alt="Matrix" title="Matrix" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/irc.svg" alt="IRC" title="IRC" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/line.svg" alt="LINE" title="LINE" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/wechat.svg" alt="WeChat" title="WeChat" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/wecom.svg" alt="WeCom" title="WeCom" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/qq.svg" alt="QQ" title="QQ" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/dingtalk.svg" alt="DingTalk" title="DingTalk" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/feishu.svg" alt="Feishu / Lark" title="Feishu / Lark" height="26">
  &nbsp;&nbsp;
  <img src="docs/brand/channels/imessage.svg" alt="iMessage" title="iMessage" height="26">
</p>

<p>Connect them over MCP — and get full control.</p>

<!-- Thirteen logos, one file per theme. Seven of them are single-colour marks, so the
     strip is built twice rather than recoloured live. See docs/brand/models/README.md. -->
<p>
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/brand/models/models-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/brand/models/models-light.svg">
  <img src="docs/brand/models/models-light.svg" alt="Works with OpenAI, Claude, Gemini, Mistral, Ollama, Perplexity, Copilot, Manus, DeepSeek, Grok, Qwen, Groq and OpenRouter" height="28">
</picture>
</p>

<!-- Two files, one seal. The wreath is single-colour artwork on a transparent
     background, so it needs dark ink on GitHub's light theme and white ink on the
     dark one; <picture> is what lets a README ship both. -->
<p>
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/brand/awards/product-of-the-day-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/brand/awards/product-of-the-day-light.svg">
  <img src="docs/brand/awards/product-of-the-day-light.svg" alt="Product of the day - 1st" height="74">
</picture>
</p>

<p>
  <img src="docs/brand/compliance/gdpr-dsgvo.png" alt="DSGVO & GDPR compliant" height="34">
  <img src="docs/brand/compliance/eu-ai-act.png" alt="EU AI Act compliant" height="34">
</p>

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
[![Status: alpha](https://img.shields.io/badge/status-alpha-blue.svg)](#project-status)
[![Release](https://img.shields.io/github/v/release/Dpro-at/Tel-Agent?label=release)](https://github.com/Dpro-at/Tel-Agent/releases/latest)

[tel-agent.com](https://tel-agent.com) · maintained by [Dpro GmbH](https://dpro.at), Vienna

</div>

---

## What it is

Tel-Agent is an open-source gateway that sits between a phone line and an AI agent.

A call arrives over SIP. Tel-Agent checks the caller against your routing rules and
either passes it through to a human, blocks it, or hands it to an AI agent. The agent
speaks with the caller in real time, can invoke tools — transfer the call, take a
message, check a calendar, call any HTTP endpoint — and every call is recorded,
transcribed, and searchable.

It runs on your own hardware, on your own LAN, with your own API keys.

The same agent handles phone calls and answers
on **web chat, SMS, email, WhatsApp, Telegram, Messenger, Instagram, Discord and
Slack** — connected with your own credentials from each platform, never a shared
application of ours. The official channel scope now covers **24 channels including the phone**, with additional channels built on the extension contract. A channel is a route a
customer uses to reach you; a system you run your own business on is an integration,
and those are reached through webhooks and the HTTP tool.

## What it is not

- **Not a PBX replacement.** It connects to your existing PBX (3CX, Asterisk, FreePBX)
  as an extension.
- **Not a workflow automation platform.** Webhooks and a generic HTTP tool reach n8n
  and Home Assistant, which do that job better. A *channel* is where the conversation
  happens; an *integration* is a system the agent acts on. We own the first and reach
  the second through the HTTP tool.
- **Not a CRM.**
- **Not analog-capable.** Bridge an analog line with an ATA; Tel-Agent only speaks SIP.

## Why it exists

Well-funded closed products already do "AI receptionist for business". What does not
exist is a good **open, self-hosted** one — where you own the recordings, choose the
models, and decide which callers ever reach the AI at all.

---

## Project status

**Alpha. Native installers and container images are available today.** Choose a platform on the [download page](https://tel-agent.com/download), or get the packages from the
[releases page](https://github.com/Dpro-at/Tel-Agent/releases/latest): a Windows
installer, macOS packages for Apple Silicon and Intel, DEB and RPM packages for Linux,
and a `docker-compose.release.yml` that pulls the published images. The installers are
unsigned while code signing is not yet configured, so the operating system will ask
once before it runs.

**What works now.** A conversation is answered end to end: the reply streams token by
token, can be interrupted mid-sentence, is stored, and raises a notification so a person
knows someone wrote in. The phone implementation includes streaming speech recognition and synthesis, interruption handling, caller-ID routing, and stored call transcripts through the SIP/LiveKit transport. Twilio integration handles SMS with customer-owned credentials. The core messaging channels are wired — web chat, WhatsApp, Telegram,
Messenger, Instagram, Discord, Slack, email and SMS — and the dashboard serves them
from a real API: sign-in and the account flows, home, the conversation archive, the
notification tray, contacts, assistants, knowledge, the catalogue, apps, numbers,
routing rul
```
