What are channels?

A channel connects an agent to an external messaging platform. Once connected, users message the agent directly on that platform — no custom integration code required. The agent receives the message, runs its tools, and replies in the platform's native format.

Supported platforms:

Quick start

1. Create a channel

Each platform needs its own credentials. Here's Telegram as the simplest example:

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "telegram",
    "config": {
      "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v"
    }
  }'

{
  "id": "ach_f8a2b1c9d0e3f4a5b6c7d8e9",
  "agent_id": "ag_myagent",
  "channel_type": "telegram",
  "webhook_status": "registered",
  "created_at": 1710000000
}

For Telegram, the webhook is registered automatically — your bot is live immediately.

2. Talk to your agent

Open Telegram and message your bot. The agent receives the message, processes it with its full tool set and memory, and replies in Telegram-native formatting.

3. List channels

curl https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY"

{
  "channels": [
    {
      "id": "ach_f8a2b1c9d0e3f4a5b6c7d8e9",
      "agent_id": "ag_myagent",
      "channel_type": "telegram",
      "enabled": true,
      "session_scope": "per_sender",
      "webhook_status": "registered",
      "webhook_error": null,
      "created_at": 1710000000
    }
  ]
}

Platform setup

Slack

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "slack",
    "config": {
      "bot_token": "xoxb-...",
      "signing_secret": "your_signing_secret",
      "app_id": "A01234ABCDE"
    }
  }'

Required config:

Optional config:

Webhook URL (set in your Slack app's Event Subscriptions):

https://{your-site}.ai.ragwalla.com/channels/slack/{app_id}/events

Slack requests are verified using HMAC-SHA256 signature validation.

Discord

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "discord",
    "config": {
      "bot_token": "MTA...",
      "public_key": "your_public_key",
      "application_id": "1234567890"
    }
  }'

Required config:

Webhook URL (set in your Discord app's Interactions Endpoint URL):

https://{your-site}.ai.ragwalla.com/channels/discord/interactions

Telegram

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "telegram",
    "config": {
      "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v"
    }
  }'

Required config:

Optional config:

Telegram webhooks are registered automatically on channel creation. No manual URL configuration needed. A secret token is auto-generated and used for request verification.

If webhook registration fails, retry it:

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels/ach_abc123/webhook/retry \
  -H "Authorization: Bearer $API_KEY"

WhatsApp

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "whatsapp",
    "config": {
      "phone_number_id": "123456789012345",
      "access_token": "EAABc...",
      "app_secret": "your_app_secret",
      "verify_token": "your_chosen_verify_token"
    }
  }'

Required config:

Webhook URL (set in your Meta app's Webhooks configuration):

https://{your-site}.ai.ragwalla.com/channels/whatsapp/{phone_number_id}/webhook

Meta will send a GET request with your verify_token to confirm the webhook. After that, incoming messages arrive via POST.

Microsoft Teams

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "teams",
    "config": {
      "app_id": "your-bot-app-id",
      "app_password": "your-bot-app-password"
    }
  }'

Required config:

Optional config:

Messaging endpoint (set in your Bot Framework registration):

https://{your-site}.ai.ragwalla.com/channels/teams/{app_id}/messages

Gmail

Gmail uses an OAuth flow instead of direct credential configuration.

Step 1: Start the OAuth flow

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels/gmail/oauth/start \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-gcp-client-id",
    "client_secret": "your-gcp-client-secret",
    "email_address": "agent@yourcompany.com",
    "gcp_project_id": "your-gcp-project",
    "pubsub_topic": "projects/your-gcp-project/topics/gmail-notifications"
  }'

{
  "channel_id": "ach_gmail_abc123",
  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "webhook_url": "https://{your-site}.ai.ragwalla.com/channels/gmail/ach_gmail_abc123/webhook?token=...",
  "expires_at": 1710003600
}

Step 2: Authorize in the browser

Open the auth_url in a browser and complete the Google OAuth consent flow. The callback is handled automatically.

Optional config:

Generic webhook

For platforms not listed above, use the generic webhook adapter:

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "webhook",
    "config": {
      "callback_url": "https://your-service.com/agent-replies",
      "secret": "your-hmac-secret",
      "headers": {
        "Authorization": "Bearer your-service-token"
      }
    }
  }'

Send messages to:

POST https://myendpoint.ai.ragwalla.com/channels/webhook/{channelId}

If secret is configured, inbound requests must include an X-Webhook-Signature header with an HMAC-SHA256 signature of the request body.

Session scoping

When you create a channel, session_scope controls how conversations are grouped into threads:

curl -X POST https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "slack",
    "config": { "..." },
    "session_scope": "per_channel"
  }'

per_sender is the right default for most cases — each person has a private, persistent conversation with the agent. Use per_channel when you want a shared conversation visible to everyone in a Slack channel or Teams group.

Resetting conversations

Users can type /new on any platform to clear their conversation and start fresh:

• /new — resets the thread and confirms
• /new what's the weather? — resets the thread and immediately processes the new message

Message formatting

Agent responses are written in Markdown. Each platform adapter converts them to native formatting:

Long responses are automatically chunked to respect each platform's message size limits.

Channel status

Check if a channel's webhook is properly registered:

curl https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels/ach_abc123/status \
  -H "Authorization: Bearer $API_KEY"

{
  "id": "ach_abc123",
  "agent_id": "ag_myagent",
  "channel_type": "telegram",
  "enabled": true,
  "webhook_status": "registered",
  "webhook_error": null,
  "webhook_registered_at": 1710000000
}

Webhook status values:

Deleting a channel

curl -X DELETE https://myendpoint.ai.ragwalla.com/agents/ag_myagent/channels/ach_abc123 \
  -H "Authorization: Bearer $API_KEY"

{ "deleted": true }

For Telegram, the webhook is automatically unregistered. For Gmail, the watch is stopped. Other platforms require you to remove the webhook URL from your app's configuration.

API reference summary