Connect a messaging or voice channel

Channels let users talk to agents through the messaging platforms they already use. Alquimia Platform normalizes inbound messages from each channel into the same execution pipeline, so the agent itself does not need to know whether a message came from WhatsApp or Email. Starting with alquimia-core 0.5.1, agents can also accept and produce audio on WhatsApp, Kapso, and Twilio Media Stream channels; version 0.5.2 adds output_format control and MP3 decoding for TTS output.

Choose the right channel

Channel	Best for
WhatsApp	Mobile customers, field service, rich media
Slack	Internal helpdesks, team collaboration, slash commands
Email	Formal requests, long-form content, ticket-style workflows
Kapso WhatsApp	WhatsApp access without direct Meta integration
Twilio Media Stream	Real-time phone calls and WebRTC voice streams

You can attach multiple channels to the same agent. For example, a support agent might accept WhatsApp from customers and Slack from employees.

What you will configure

Each channel requires three things:

Provider credentials — tokens, webhooks, or API keys stored as secrets, not in the agent spec.
Channel configuration — the adapter that maps provider payloads to Alquimia Platform’s normalized request shape.
Response template — how the agent’s answer is formatted before delivery.

Set up the channel

Register the provider secrets in the agentspace registry.
Create the channel configuration in the agent spec or registry, selecting the adapter for your provider.
Configure the provider webhook to point at the runtime’s channel endpoint. The runtime verifies each inbound request using the provider’s signature or token mechanism.
Send a test message and confirm that the agent receives it, produces a response, and the response is delivered back to the sender.
Check the worklog to verify normalization, identity mapping, and delivery.

Identity and session mapping

Channels map provider-specific sender identifiers to stable Alquimia Platform user_id and session_id values. This preserves conversation history when the same person messages again from the same channel. Make sure the mapping is consistent, especially if you have multiple agents sharing a channel.

Response templates

Templates let you format answers per channel. An email response might include HTML and a signature, while a WhatsApp response should be concise plain text. Templates can reference metadata such as sender name or original message ID, but keep them simple to avoid rendering issues.

Approval handoffs

When a tool requires human approval, the approval request can be routed back through the same channel the user is already on. This keeps the workflow natural and reduces the risk of spoofed approvals.

Add voice to a channel

Voice notes and streaming calls reuse the same channel infrastructure as text messages, but the agent needs an audio adapter to transcribe incoming audio and synthesize outgoing replies.

Install the [leviathan] extra if you use cloud STT/TTS connectors or the self-hosted Triton backends:
Terminal window
```
pip install "alquimia-core[leviathan]"
```
Register STT and TTS secrets in the agentspace registry (for example, STT_PROVIDER_API_KEY and TTS_PROVIDER_API_KEY).

Add the audio field to the agent spec, declaring the connectors and modalities:

{
  "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"]
  }
}

For request/response voice notes, configure a WhatsApp or Kapso channel as usual. Inbound voice notes are transcribed automatically and outbound audio is synthesized when output_modalities includes audio.
For real-time phone calls, add a streaming_channels entry with provider_id: twilio-media-stream and expose the runtime WebSocket endpoint that Twilio can connect to:
```
wss://runtime.example.com/streaming/{assistant_id}/{channel_id}
```
The runtime validates the Twilio Account SID on the start event, enforces per-source session limits, segments turns with energy-based VAD, and streams assistant replies back as μ-law audio. Configure the session limits with the STREAMING_CHANNEL_* runtime settings. See the streaming channel reference for agent-spec field details and the Runtime configuration reference for the environment variables.
Send a test voice message or call and verify the worklog shows the transcript, the agent response, and the synthesized audio delivery.