Integration types
Channels
Where people reach an agent: web widget vs web chat endpoint, WhatsApp, Telegram, email, and what Teams, Slack, SMS and voice need from you.
A channel is where people reach an agent — a web widget, WhatsApp, email, Telegram, Teams, Slack, SMS or the Workspace.
القناة هي حيث يصل الناس إلى الوكيل: ودجت ويب، واتساب، البريد الإلكتروني، تيليجرام، تيمز، سلاك، الرسائل النصية أو مساحة العمل.
Channels are the human side of integration. Each channel adapter maps identity, formatting and human handoff for its medium, then opens the same kind of run an operator would open in the Workspace — so the agent, its tools, its approvals and its trail are identical whatever the entry point. The web widget uses a publishable embed key with an origin allow-list and optional signed identity; provider channels use the provider's official API and show an awaiting first event state until the first message arrives.
القنوات هي الجانب البشري من التكامل. يربط كل محوّل قناة الهوية والتنسيق وتسليم العمل للبشر بحسب الوسيط، ثم يفتح النوع نفسه من التشغيل الذي يفتحه المشغّل في مساحة العمل — فيبقى الوكيل وأدواته وموافقاته وسجلّه متطابقًا أيًّا كانت نقطة الدخول. يستخدم ودجت الويب مفتاح تضمين قابلًا للنشر مع قائمة أصول مسموحة وهوية موقّعة اختيارية؛ وتستخدم قنوات المزوّدين واجهة المزوّد الرسمية وتُظهر حالة بانتظار أول حدث حتى تصل أول رسالة.
Channel kinds
The status column is deliberate. Available now means you can connect it today with nothing but the console. Available with your provider credentials means the adapter is present and works once you supply the provider account (your Slack app, your Azure Bot registration, your SMS or telephony provider) — without them the channel is honestly unavailable. Unofficial means a path the provider does not sanction; it is labelled, not hidden.
| Channel | Status | Notes | platform |
|---|---|---|---|
| Web widget ودجت الويب | Available now | Backed by an embed key (hive_pk_…, origin allow-list, identity JWT). The recommended web path. | web |
| Web chat endpoint (Inbox) نقطة محادثة ويب (صندوق الوارد) | Available now | Legacy channels.platform='web'; routes to Inbox with human handoff. Kept. | web |
| WhatsApp واتساب | Available now | Meta Cloud API (official). Frame the agent as a business-process agent, not a general-purpose assistant. | whatsapp |
| WhatsApp — personal number (QR) واتساب — رقم شخصي (QR) | Unofficial | The QR/personal path is labelled Unofficial: it is not covered by Meta’s business terms and can be cut off without notice. | whatsapp |
| Telegram تيليجرام | Available now | Bot API. | telegram |
| Email البريد الإلكتروني | Available now | IMAP/SMTP mailbox or webhook transport. | email |
| Slack سلاك | Available with your provider credentials | Adapter present; needs provider credentials (your Slack app). Without them the channel is honest-unavailable. | slack |
| Microsoft Teams مايكروسوفت تيمز | Available with your provider credentials | Adapter present; needs provider credentials (your Azure Bot registration). | teams |
| SMS الرسائل النصية | Available with your provider credentials | Adapter present; needs provider credentials (your SMS provider account). | sms |
| Voice الصوت | Available with your provider credentials | Adapter present; needs provider credentials (your telephony provider). | voice |
| Workspace مساحة العمل | Available now | Built-in channel for staff; no configuration. | workspace |
Next (roadmap): Teams, Slack, SMS and Voice without customer-provided provider credentials — a hosted provider account owned by Agentic Workforce ME. Until then those four rows read “available with your provider credentials” everywhere: console, website, this portal.
Web: the widget or the chat endpoint
Two web channels exist and they are not the same thing. The web widget is the recommended path for a public site or an app: a publishable embed key (hive_pk_…) bound to one agent, an origin allow-list, optional signed identity, and a browser talking to /v1/embed/* with nothing secret in the page. The web chat endpoint is the earlier platform='web' channel: conversations land in the console Inbox, where a person can take over. Both open the same kind of run.
| Aspect | Web widget | Web chat endpoint (Inbox) |
|---|---|---|
| Use it when | You are embedding an agent in a site or app you control and want the governed, keyed, origin-restricted path. | Your operators must be able to take over a web conversation in Inbox today. |
| Credential in the browser | Publishable embed key only; identity, if any, is a JWT your server signs. | The channel’s public_key, sent as the X-Hive-Public-Key header (or ?public_key= on the SSE stream); a mismatch is a 401, and CORS echoes config.allowed_origins. |
| Human handoff | Not yet — a widget → Inbox handoff bridge is Next (roadmap). | Yes, in Inbox. |
| Where to start | Widget quickstart · Security model | POST /v1/channels with platform: web returns public_key + web_endpoint; messages go to POST /channels/:token/web/messages, replies stream over SSE. |
The same run, whatever the door
- Identity. Each adapter maps the medium’s identity (a phone number, an email address, a chat user id, a signed widget identity) onto the conversation’s end user, so memory and permissions follow the person, not the medium.
- Formatting and handoff. The adapter renders the agent’s output for its medium and, where the medium supports it, routes a handoff to a person in Inbox.
- One run model. A message on any channel opens the same kind of run an operator opens in the Workspace: the same published agent, the same granted tools, the same approval policies, the same run steps and audit trail.
- Awaiting first event. A provider channel that is configured but has not yet received its first callback shows Awaiting first event (
awaiting_first_event) rather than a false green; the badge flips on the first inbound message.POST /v1/channels/:id/testruns the readiness check before that.
API mapping
Every /v1/channels path takes an API key plus X-Tenant-Id and needs the admin role — listing, creating, changing and testing alike (an API key acts as admin; a console session needs it explicitly). The public message endpoints under /channels/:token/… take no API key: the channel’s public_key in the X-Hive-Public-Key header instead.
| Resource | Path | Notes |
|---|---|---|
| Channel · kind Web widget | /v1/embed-keys | Publishable key bound to one agent + origin allow-list; the widget talks to /v1/embed/*. |
| Channel (WhatsApp, Telegram, email, web chat endpoint, Teams, Slack, SMS, voice) | /v1/channels | Provider credentials are write-only (secret); POST /v1/channels/:id/test runs the readiness check; provider callbacks arrive at /channels/:token/webhook. |
The embed surface (/v1/embed/*, the widget’s own API) is fully documented under REST API and JavaScript API. Channel provider secrets are write-only: they are stored encrypted, never returned, and used only by the adapter.