Channels

Channels are adapters that connect an agent to an external messaging platform. When a message arrives on a channel, the adapter normalizes it into the standard inference request format and dispatches it through the same execution pipeline as a direct API call. When the agent responds, the adapter routes the answer back to the originating platform.

Supported channels

Alquimia Platform ships adapters for:

Channel	Best for
WhatsApp	Customer support, field service, mobile-first users
Kapso WhatsApp	WhatsApp access managed through the Kapso platform
Slack	Internal helpdesks, slash commands, team collaboration
Email	Ticket-style workflows, formal approvals, document intake
Twilio Media Stream	Real-time phone calls and WebRTC voice streams

A single agent can have multiple channels. For example, a support agent might accept WhatsApp messages from customers and Slack messages from employees, using the same configuration and memory.

How channels work

External platform
       │
       ▼
Webhook / poll endpoint
       │
       ▼
Channel adapter ──► normalized inference request
       │
       ▼
Execution pipeline
       │
       ▼
Channel adapter ◄── final response
       │
       ▼
External platform

The adapter handles three concerns:

Ingestion — parse the provider-specific payload and extract the message, sender, attachments, and metadata.
Authentication — verify the request using the provider’s mechanism, such as a verify token or HMAC signature.
Response — format and deliver the agent’s answer back to the sender.

Normalization

Every channel produces the same internal request shape. This means:

An agent does not need to know whether a message came from WhatsApp or Email.
Tools and memory behave the same regardless of channel.
Adding a new channel does not require changing the agent’s core logic.

Sender identifiers are mapped to stable user and session identifiers so conversation history persists across messages from the same source.

Channel-bound approvals

For tools that require human approval, the runtime can route the approval request back through the same channel the original message arrived on. This keeps the approval experience in the user’s native messaging app instead of forcing them to visit a separate web interface.

The flow works like this:

A user sends a message on WhatsApp.
The agent calls a tool that requires approval.
The runtime asks the tool provider for the approval message text.
The approval message is sent back to the user on WhatsApp.
The user replies with approval or rejection.
The runtime resumes the agent execution and sends the final answer.

Voice and audio messages

Starting with alquimia-core 0.5.1, agents can accept and produce audio on supported channels. Version 0.5.2 adds output_format control (wav or mp3) for TTS connectors, MP3 decoding via miniaudio, and updated OpenAI TTS defaults (gpt-4o-mini-tts model and alloy voice). WhatsApp and Kapso voice notes are ingested as audio blobs, transcribed by a speech-to-text (STT) connector, and fed into the same inference pipeline as text messages. When the agent’s output modality includes audio, a text-to-speech (TTS) connector synthesizes the reply and the channel delivers it back as a voice message.

Audio behavior is declared with the top-level audio field on the agent spec:

{
  "audio": {
    "stt": { "provider_id": "deepgram", "api_key": { "$secretRef": "STT_PROVIDER_API_KEY" } },
    "tts": {
      "provider_id": "openai/tts",
      "model": "gpt-4o-mini-tts",
      "voice": "alloy",
      "output_format": "mp3",
      "api_key": { "$secretRef": "TTS_PROVIDER_API_KEY" }
    },
    "input_modalities": ["text", "audio"],
    "output_modalities": ["text", "audio"]
  }
}

If audio is omitted, the agent is text-only and existing channel behavior is unchanged.

Streaming audio channels

Request/response channels such as WhatsApp and Email handle discrete messages. Streaming channels keep a bidirectional audio session open for the lifetime of a phone or WebRTC call. The concrete transport (for example, twilio-media-stream) decodes its wire format into PCM AudioFrame instances and delegates VAD-based turn segmentation and per-utterance inference to the shared helpers in alquimia.core.streaming_channel.

Streaming channels are configured separately from request/response channels in streaming_channels:

{
  "streaming_channels": [
    {
      "provider_id": "twilio-media-stream",
      "channel_id": "twilio-phone",
      "account_sid": { "$secretRef": "TWILIO_ACCOUNT_SID" },
      "auth_token": { "$secretRef": "TWILIO_AUTH_TOKEN" }
    }
  ]
}

Response templates

Each channel can define a template for formatting the agent’s response before delivery. For example, an email channel might render the answer as HTML, while a WhatsApp channel sends plain text. Templates use Jinja2 and can access platform-specific metadata such as sender name or message ID.

Choosing channels

Need	Recommended channel
Mobile users, rich media	WhatsApp
Voice notes on WhatsApp	WhatsApp or Kapso WhatsApp
Internal team workflows	Slack
Formal requests, attachments, long-form content	Email
WhatsApp without direct Meta integration	Kapso WhatsApp
Real-time phone or WebRTC voice	Twilio Media Stream