> For the complete documentation index, see [llms.txt](https://www.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.conserver.io/vcon-adapters.md).

# vCon Adapters

Patterns, templates, and operational guidance for building services that turn foreign conversation data into vCons.

An **adapter** is anything that takes conversation data out of a foreign system, a phone PBX, a softswitch, a contact-center suite, an LLM transcript, a chat platform, a SIPREC stream, and produces a [vCon](https://www.conserver.io/vcons.md) on the other side. Adapters are how the rest of the vCon ecosystem (conservers, MCP servers, analytics, archives) gets fed.

This section is the playbook for building, deploying, and operating one.

## Spec target

Adapters in this section target `draft-ietf-vcon-vcon-core-04`, syntax `"0.4.0"`. The [Spec Compliance Checklist](https://www.conserver.io/vcon-adapters/spec-compliance-checklist.md) holds the full target, with the JSON-body rule and every field rule. Code that cites `0.2.0`, `0.3.0`, `-02` or `-03` is out of date.

## The canonical flow

Every adapter (webhook receiver, polling job, file watcher, batch CLI) boils down to the same four stages:

```
   ┌───────────┐    ┌──────────────┐    ┌────────────────┐    ┌──────────────────┐
   │ Source    │ →  │ Build vCon   │ →  │ Lawful basis / │ →  │ Deliver          │
   │ event     │    │ (lib helpers)│    │ finalize       │    │ (webhook or      │
   │           │    │              │    │                │    │  conserver)      │
   └───────────┘    └──────────────┘    └────────────────┘    └──────────────────┘
```

The work that's actually adapter-specific is the leftmost box: knowing *your* source platform's events, IDs, timestamps, and recording URLs. Everything to the right of that, vCon construction, lawful basis, retries, delivery, is solved. Content signing (JWS) is not built into the template; see [Operational Patterns](https://www.conserver.io/vcon-adapters/operational-patterns.md#content-signing-add-it-yourself). **Don't write it from scratch.**

## Start here: use the template

Every adapter in this ecosystem should start from [**vcon-dev/vcon-adapter-template**](https://github.com/vcon-dev/vcon-adapter-template). It's a GitHub template repo: click "Use this template" or run `gh repo create --template vcon-dev/vcon-adapter-template …`. You get:

* A `vcon_builder.py` thin wrapper over the official `vcon` Python library, with `finalize_vcon()` to close out a vCon and `json_body()` to read an attachment or analysis body back whether it was written as a JSON value or a legacy string
* A lawful-basis builder: `LAWFUL_BASIS*` environment variables or a YAML block build the attachment; leave it unset and the adapter logs a warning and skips the attachment rather than guessing a basis. Never defaulted in code
* A copyable `assert_spec_compliant()` test, run against the vendored JSON schema, so a new adapter inherits the compliance gate
* Two delivery paths: signed webhooks (HMAC-SHA256, `Idempotency-Key`, exponential-backoff retries, dead-letter queue), or conserver-direct delivery (`POST /vcon?ingress_lists=...` with an `x-conserver-api-token` header) for adapters that talk straight to a vcon-server instance
* `/healthz` and Prometheus `/metrics` endpoints out of the box
* YAML config with `${ENV_VAR}` substitution
* Dockerfile, `docker-compose.yml`, and a GitHub Actions workflow that runs lint, type check and tests

→ [Quick Start From Template](https://www.conserver.io/vcon-adapters/quick-start-from-template.md) is a one-page recipe to get a new adapter scaffolded in under five minutes.

## Building a new adapter

Start from the template above, not from an existing adapter repo: several of those predate the template and carry patterns the [checklist](https://www.conserver.io/vcon-adapters/spec-compliance-checklist.md) no longer allows. Configure lawful basis from the first commit (`LAWFUL_BASIS*` env vars or YAML; see the template's `USAGE.md`). The template never defaults a basis; set the one your deployment relies on.

## Reading order

| Page                                                                                                            | When to read it                                                                                          |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [Quick Start From Template](https://www.conserver.io/vcon-adapters/quick-start-from-template.md)                | First adapter, or every new adapter. Five-minute scaffold.                                               |
| [Operational Patterns](https://www.conserver.io/vcon-adapters/operational-patterns.md)                          | Production deployment. Delivery, HMAC signing, retries, DLQ, health, metrics.                            |
| [Spec Compliance Checklist](https://www.conserver.io/vcon-adapters/spec-compliance-checklist.md)                | Code review and PR gate. Print and pin to wall.                                                          |
| [Extensions Cookbook](https://www.conserver.io/vcon-adapters/extensions-cookbook.md)                            | Adding transcripts, consent records, SIP signaling, agent sessions.                                      |
| [vCon Adapter Development Guide](https://www.conserver.io/vcon-adapters/vcon-adapter-development-guide.md)      | Going beyond the template, custom architectures, polling vs. webhook listeners, batch CLI, multi-source. |
| [LLM Guide: Creating vCon Adapters](https://www.conserver.io/vcon-adapters/llm-guide-creating-vcon-adapters.md) | Short digest to paste into a model's context when you want it to generate adapter code.                  |

## Existing adapters in the ecosystem

These live in their own repos under the [vcon-dev GitHub org](https://github.com/vcon-dev).

### Modernized for `-04`

Built on the template, or brought up to its bar: lawful basis, `-04` JSON bodies, and the checklist mostly apply (see the telephony row for the one open gap).

| Repo                                                                             | Source                                                            | Pattern                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`vcon-telephony-adapters`](https://github.com/vcon-dev/vcon-telephony-adapters) | Asterisk, Bandwidth, FreeSWITCH, Telnyx, Twilio                   | Webhook receivers, one monorepo. Webhook signature validation fails closed by default: an adapter refuses to start without its secret unless `ALLOW_UNSIGNED_WEBHOOKS=true` is set explicitly. Lawful basis on every platform. External media (`MEDIA_BACKEND=filesystem` or `s3`) produces fully schema-valid `-04` output with `url` and `content_hash`; the default `MEDIA_BACKEND=embed` path still writes inline audio as `encoding: "base64"`, not yet `base64url`, pending a follow-up release. Dockerfile and a GHCR image published on version tags |
| [`vcon-audio-adapter`](https://github.com/vcon-dev/vcon-audio-adapter)           | Audio files on disk or S3                                         | Directory watcher. Spec-correct `-04` output, lawful basis, `content_hash` on referenced audio                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [`vcon-vac-adapter`](https://github.com/vcon-dev/vcon-vac-adapter)               | AI-agent sessions (Claude Code, Anthropic, OpenAI, OpenTelemetry) | Converts agent session transcripts into vCons with an `agent_trace` analysis under the [Agent Session](https://www.conserver.io/extensions/agent-session.md) extension. Lawful basis; delivers by webhook or straight to a conserver; a daemon mode watches a configured directory of Claude Code session files                                                                                                                                                                                                                                              |

### Architecture references, not compliance references

Written before the template existed and not modernized this round. Useful for their integration patterns; when they disagree with the [checklist](https://www.conserver.io/vcon-adapters/spec-compliance-checklist.md), trust the checklist.

| Repo                                                                                        | Source                  | Pattern               |
| ------------------------------------------------------------------------------------------- | ----------------------- | --------------------- |
| [`signalwire_adapter`](https://github.com/vcon-dev/signalwire_adapter) (archived)           | SignalWire telephony    | Polling job           |
| [`vcon-eleven-labs-adapter`](https://github.com/vcon-dev/vcon-eleven-labs-adapter)          | ElevenLabs voice AI     | Polling + CLI batch   |
| [`sippy-conserver-adapter`](https://github.com/vcon-dev/sippy-conserver-adapter) (archived) | Sippy softswitch (S3)   | S3 bucket monitor     |
| [`ietf2vcon`](https://github.com/vcon-dev/ietf2vcon)                                        | IETF meeting recordings | Batch CLI per-meeting |
| [`matrix_vcon_emitter`](https://github.com/vcon-dev/matrix_vcon_emitter)                    | Matrix chat             | Event stream          |

For per-adapter documentation pages (`vCon Faker`, `vCon Anthropic Chats`, `vCon SIPREC Adapter`, `vCon MCP Adapters`, etc.), see the [Tools](https://www.conserver.io/tools.md) section.

## Related

* [vCon Library (Python)](https://www.conserver.io/vcon-library.md): the official Python library every adapter should use
* [vCon-JS Library](https://www.conserver.io/vcon-js-library.md): TypeScript equivalent for Node-based adapters
* [Extensions](https://www.conserver.io/extensions.md): WTF transcription, lawful basis, SIP signaling, agent session, lifecycle
* [Conserver](https://www.conserver.io/conserver.md): the typical downstream consumer of adapter output


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.conserver.io/vcon-adapters.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
