Webhook connectors
Channel Hub
Connect messaging channels to a ViksaAI project so external users can run your deployed agents from WhatsApp, Telegram, Teams, or Instagram.
What is Channel Hub?#
Channel Hub is the Volt area for Tier 1 webhook connectors. Unlike Slack (which uses a dedicated runtime pod per project), webhook channels share ingress in volt-engine-service. Each customer registers their own bot or Meta app; Viksa routes inbound messages to the correct project by a unique routing key (Microsoft App ID, WhatsApp phone number ID, Telegram tenant key, etc.).
Available channels#
WhatsAppWhatsApp Business Cloud API — message your agents from any phone.TelegramTelegram Bot API — DMs via secure webhook.Microsoft TeamsAzure Bot + Bot Framework — Teams and Web Chat.Instagram DMInstagram Messaging API — direct messages to your business account.Slack (runtime pod)Socket Mode runtime — separate install flow from webhook channels.
Setup flow (all webhook channels)#
- Open your project → Volt → Channel Hub → choose a channel.
- Create the bot or Meta app on the provider side (see per-channel guides).
- Paste credentials → Validate → Connect.
- Configure Access — allow all users (*) or add per-user grants with channel-specific identities.
- Deploy at least one enabled agent in builder-service, then test from an allowed identity.
Webhook endpoints#
Your platform operator exposes these URLs on volt-engine-service (replace the host if self-hosted):
| Channel | Callback URL |
|---|---|
| WhatsApp / Instagram | https://api.viksaai.com/v1/webhooks/meta |
| Telegram | https://api.viksaai.com/v1/webhooks/telegram/{tenant_key} |
| Microsoft Teams | https://api.viksaai.com/v1/webhooks/teams |
Message flow#
- User sends a message on the channel.
- The platform posts a webhook to volt-engine-service at /v1/webhooks/*.
- Engine resolves account, org, and project from the global routing index (App ID, phone number ID, tenant key, etc.).
- Access is checked via channel_grants_v1 and optional Viksa project membership.
- The same Think→Act→Observe pipeline loads your project agent catalog and runs agents.
- The reply is sent back through the channel API (Graph, Telegram Bot API, Bot Framework, etc.).
Pilot scope#
Current Tier 1 connector capabilities:
- Plain text inbound messages and text replies
- Per-project connection via Channel Hub (validate → connect → access grants)
- Unified access model (channel_grants_v1): allow all users (*) or per-user grants
- Conversation history (last 20 turns) per thread
- Same agent brain as Slack — without a per-project Slack pod
- Encrypted credentials at rest; secrets never stored in webhook queue payloads
Not yet supported in the pilot:
- Media (images, audio, video, documents)
- WhatsApp template / proactive messages outside the 24-hour session window
- Telegram bot commands (/start, slash commands) — send plain text instead
- Instagram/WhatsApp story mentions and reactions
- CSV import/export of access grants
Use cases#
- Customer support — let approved users query ops agents from WhatsApp or Telegram
- Field teams — run checklists and remediation agents from mobile messaging apps
- Internal IT — Teams bot for on-call runbooks and platform health agents
- Social DM triage — Instagram business inbox routed to your agent catalog