Channels (Messaging Integrations)

Channels connect your Universal API agents to messaging platforms — Slack, Discord, Telegram, WhatsApp, SMS, phone calls, and generic webhooks. Once configured, users on those platforms can chat with your agent directly.

How Channels Work

Create a channel — Specify the platform, agent, and platform credentials
Get a webhook URL — Universal API generates a unique inbound webhook
Configure the platform — Point your bot's webhook to the URL
Users chat — Messages flow in, agent responds, replies flow back

User (Slack/Discord/etc.) → Platform Webhook → Universal API → Agent → Response → Platform

Supported Platforms

Platform	Auth Required	Group Support	Features
Slack	`signingSecret` + `botToken`	✅	Threads, mentions, allowlists
Discord	`publicKey` + `botToken`	✅	Threads, mentions, allowlists
Telegram	`botToken`	✅	Auto-registers webhook with Telegram API
WhatsApp	`verifyToken` + `accessToken` + `phoneNumberId`	✅	Meta webhook verification
Twilio Voice	`accountSid` + `authToken` + `phoneNumber`	❌	Inbound + outbound phone calls
Twilio SMS	`accountSid` + `authToken` + `phoneNumber`	❌	Two-way SMS, STOP/HELP compliance, human takeover
Twilio Unified	`accountSid` + `authToken` + `phoneNumber`	❌	One number for both voice AND SMS
Webhook	`secret` (optional)	❌	Generic HTTP webhook with HMAC verification

Quick Start

1. Create a Channel

bash

curl -X POST https://api.universalapi.co/channels \
  -H "Authorization: Bearer uapi_ut_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-slack-bot",
    "platform": "slack",
    "agentId": "YOUR_AGENT_ID",
    "platformConfig": {
      "signingSecret": "your_slack_signing_secret",
      "botToken": "xoxb-your-slack-bot-token"
    }
  }'

The response includes a webhookUrl — configure this in your platform's bot settings.

2. Configure Your Platform

Slack: Go to your Slack App → Event Subscriptions → set the Request URL to the webhookUrl.

Discord: Go to your Discord App → General Information → set the Interactions Endpoint URL.

Telegram: The webhook is auto-registered when you create the channel — no manual setup needed!

WhatsApp: In Meta Business Suite → WhatsApp → Configuration → set the Callback URL.

3. Test It

bash

curl -X POST https://api.universalapi.co/channels/{channelId}/test \
  -H "Authorization: Bearer uapi_ut_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello! Are you working?"}'

Security Features

Platform Signature Verification

Every inbound webhook is verified using the platform's native signature mechanism:

Slack: HMAC-SHA256 with signing secret
Discord: Ed25519 signature verification
Telegram: Secret token header validation
WhatsApp: SHA256 HMAC verification
Webhook: Optional HMAC with shared secret

Sender Allowlists

Restrict which users can interact with your agent:

json

{
  "allowedSenders": ["U12345678", "U87654321"]
}

Group Policies

Control how the agent behaves in group chats:

Policy	Behavior
`disabled`	Ignore all group messages (DMs only)
`allowlist`	Only respond in specified groups
`open`	Respond in all groups

Mention Gating

Set requireMention: true to only respond when the bot is @mentioned in groups.

SMS Agents (Twilio SMS)

The twilio-sms platform turns any text agent into a two-way SMS bot on a Twilio phone number:

bash

curl -X POST https://api.universalapi.co/channels \
  -H "Authorization: Bearer uapi_ut_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-sms",
    "platform": "twilio-sms",
    "agentId": "YOUR_TEXT_AGENT_ID",
    "platformConfig": {
      "accountSid": "ACxxxx",
      "authToken": "your_twilio_auth_token",
      "phoneNumber": "+15551234567"
    }
  }'

Point your Twilio phone number's Messaging webhook to the returned webhookUrl. Inbound texts invoke your agent; the response is sent back as SMS (long replies are automatically split into segments).

Built-in TCPA compliance: STOP, HELP, and START keywords are handled at the platform level — opt-outs are recorded per phone number and the agent is never invoked for opted-out senders.

Channel context injection: The agent receives context like [Channel: SMS | Sender: +1555...] so it knows it's talking over SMS and can keep replies concise.

Human Takeover (Per-Sender Mute)

Need a human to step into an SMS conversation? Mute the AI for a specific sender — the agent stops auto-replying to that number while everyone else continues normally:

bash

# Pause AI replies for one phone number
curl -X POST https://api.universalapi.co/channels/{channelId}/mute-sender \
  -H "Authorization: Bearer uapi_ut_your_token" \
  -H "Content-Type: application/json" \
  -d '{"senderId": "+15559876543", "reason": "human handling escalation"}'

# Send a manual message as the business
curl -X POST https://api.universalapi.co/channels/{channelId}/send \
  -H "Authorization: Bearer uapi_ut_your_token" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15559876543", "message": "Hi, this is Sarah from support — I am taking over from here."}'

# Resume AI replies when done
curl -X POST https://api.universalapi.co/channels/{channelId}/unmute-sender \
  -H "Authorization: Bearer uapi_ut_your_token" \
  -H "Content-Type: application/json" \
  -d '{"senderId": "+15559876543"}'

List currently muted senders with GET /channels/{channelId}/muted-senders. Inbound messages from muted senders are still logged — they just don't trigger the agent.

Unified Voice + SMS (Twilio Unified)

The twilio-unified platform puts both a voice agent and a text agent behind one phone number. Callers talk to your bidi (voice) agent in real time; texters chat with your text agent:

bash

curl -X POST https://api.universalapi.co/channels \
  -H "Authorization: Bearer uapi_ut_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "front-desk",
    "platform": "twilio-unified",
    "agentId": "YOUR_TEXT_AGENT_ID",
    "voiceAgentId": "YOUR_VOICE_AGENT_ID",
    "platformConfig": {
      "accountSid": "ACxxxx",
      "authToken": "your_twilio_auth_token",
      "phoneNumber": "+15551234567"
    }
  }'

The response includes two webhook URLs — configure the SMS one under Twilio Messaging and the voice one under Twilio Voice. Unified channels also support outbound calls via POST /channels/{channelId}/call.

Session Strategies

By default, each sender gets their own persistent conversation (per-sender). Configure sessionConfig at channel creation to change how conversations map to sessions:

Strategy	Behavior
`per-sender` (default)	One ongoing conversation per sender — full memory across messages
`sliding-window`	Conversation expires after a configurable idle period, then starts fresh
`single-session`	All messages share one persistent session (e.g. a shared team channel)

json

{
  "sessionConfig": {
    "strategy": "sliding-window",
    "windowMinutes": 60
  }
}

Conversation Continuity

Channels automatically map platform threads/groups/DMs to Universal API conversation IDs. This means:

Multi-turn conversations work naturally
Context is preserved within a thread
Each DM or thread gets its own conversation

Auto-Pause

If a channel encounters 3 consecutive failures, it's automatically paused (status → error) to prevent runaway errors. Reactivate by updating the status:

bash

curl -X PUT https://api.universalapi.co/channels/{channelId} \
  -H "Authorization: Bearer uapi_ut_your_token" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Billing

Channels use normal agent invocation credits — no additional channel charges. Each message that triggers an agent response costs the standard agent credits based on token usage.

Channels API Reference — Full endpoint documentation
Voice Agents — Twilio voice channel setup
Creating Agents — Build the agent your channel connects to

Channels (Messaging Integrations) ​

How Channels Work ​

Supported Platforms ​

Quick Start ​

1. Create a Channel ​

2. Configure Your Platform ​

3. Test It ​

Security Features ​

Platform Signature Verification ​

Sender Allowlists ​

Group Policies ​

Mention Gating ​

SMS Agents (Twilio SMS) ​

Human Takeover (Per-Sender Mute) ​

Unified Voice + SMS (Twilio Unified) ​

Session Strategies ​

Conversation Continuity ​

Auto-Pause ​

Billing ​

Related Resources ​

Channels (Messaging Integrations)

How Channels Work

Supported Platforms

Quick Start

1. Create a Channel

2. Configure Your Platform

3. Test It

Security Features

Platform Signature Verification

Sender Allowlists

Group Policies

Mention Gating

SMS Agents (Twilio SMS)

Human Takeover (Per-Sender Mute)

Unified Voice + SMS (Twilio Unified)

Session Strategies

Conversation Continuity

Auto-Pause

Billing

Related Resources