Channels API Reference

All channel endpoints require authentication via Bearer token.

Create Channel

POST /channels

Request Body:

Field	Type	Required	Description
name	string	✅	Channel name (e.g., my-slack-bot)
platform	string	✅	slack, discord, telegram, whatsapp, twilio-voice, or webhook
agentId	string	✅	Agent UUID to handle messages
platformConfig	object	✅	Platform-specific credentials (see below)
allowedSenders	string[]	No	Platform user IDs allowed to interact
groupPolicy	string	No	disabled (default), allowlist, or open
allowedGroups	string[]	No	Group IDs (when groupPolicy is allowlist)
requireMention	boolean	No	Only respond when @mentioned in groups

Platform Config by Platform

Slack:

{ "signingSecret": "abc123...", "botToken": "xoxb-..." }

Discord:

{ "publicKey": "abc123...", "botToken": "MTIz..." }

Telegram:

{ "botToken": "123456:ABC-DEF..." }

WhatsApp:

{ "verifyToken": "my-verify-token", "accessToken": "EAAx...", "phoneNumberId": "123456789" }

Twilio Voice:

{ "accountSid": "ACxxx...", "authToken": "xxx...", "phoneNumber": "+12125551234" }

Webhook (Generic):

{ "secret": "optional-hmac-secret" }

Response:

{
  "data": {
    "channelId": "ch-xxx",
    "name": "my-slack-bot",
    "platform": "slack",
    "agentId": "agent-xxx",
    "status": "active",
    "webhookUrl": "https://api.universalapi.co/channels/inbound/ch-xxx/slack",
    "createdAt": "2026-04-17T..."
  }
}

List Channels

GET /channels

Returns all channels for the authenticated user.

Get Channel

GET /channels/{channelId}

Returns full details including platform config (sensitive values masked).

Update Channel

PUT /channels/{channelId}

Only include fields you want to change.

Field	Type	Description
name	string	New name
agentId	string	New agent UUID
status	string	active or paused
platformConfig	object	Updated credentials
allowedSenders	string[]	Updated sender allowlist
groupPolicy	string	Updated group policy
allowedGroups	string[]	Updated allowed groups
requireMention	boolean	Updated mention requirement

Setting status to active resets the failure counter.

Delete Channel

DELETE /channels/{channelId}

Permanently deletes the channel. For Telegram channels, also deregisters the webhook with the Telegram API.

Test Channel

POST /channels/{channelId}/test

Request Body:

{ "message": "Hello! This is a test message." }

Sends a test prompt to the connected agent and returns the response. Useful for verifying the integration works.

Make Outbound Call (Twilio Voice Only)

POST /channels/{channelId}/call

Request Body:

{ "to": "+12125559876" }

Initiates an outbound phone call from the channel's Twilio phone number to the target number. The recipient is connected to the voice agent when they answer.

Phone number must be in E.164 format (e.g., +12125551234).

Mute / Unmute Sender (Human Takeover)

Pause AI auto-replies for a specific sender so a human operator can take over the conversation.

Mute a Sender

POST /channels/{channelId}/mute-sender

Request Body:

{
  "senderId": "+12125551234",
  "reason": "Customer escalation"
}

When a sender is muted, inbound messages from them are still received (202 Accepted) but the AI agent is not invoked. This allows a human to respond manually via the Send Message endpoint.

Unmute a Sender

POST /channels/{channelId}/unmute-sender

Request Body:

{ "senderId": "+12125551234" }

Resumes AI auto-replies for the sender.

List Muted Senders

GET /channels/{channelId}/muted-senders

Returns all currently muted senders with metadata (when they were muted, by whom, and reason).

Send Manual Message

Send a message through the channel without invoking the AI agent. Useful during human takeover when a sender is muted.

POST /channels/{channelId}/send

Request Body:

{
  "to": "+12125551234",
  "message": "Hi, this is Sarah from our team. I'm taking over this conversation."
}

Currently supported for twilio-sms and twilio-unified channels. The message is sent via the Twilio REST API using the channel's configured credentials.

Inbound Webhooks

These endpoints receive messages from platforms. They are called by the platforms themselves — no user auth required (verified via platform signatures).

POST /channels/inbound/{channelId}/{platform}

For WhatsApp webhook verification:

GET /channels/inbound/{channelId}/whatsapp

Error Handling

Status	Description
400	Missing required fields or invalid platform
401	Invalid or missing Bearer token
403	Channel belongs to another user
404	Channel not found
429	Rate limit exceeded