Webex Assistant — Aida Voice Control

:::warning 2026 platform change Cisco has retired the legacy Assistant Skills developer portal (hostname no longer resolves). New deployments should not rely on Ok Webex, tell Aida … or encrypted /parse registration. Voice control now uses Webex AI Studio HTTP Actions and/or device macros calling the Aida Platform — with natural phrases like Ok Webex, toggle the lights. See engineering spec. :::

The Aida voice layer brings building control and intelligent assistance to Cisco Webex Board, Desk, Room, and Room Kit devices. Aida executes the same actions as tapping buttons on the Aida Platform Controls panel — or answers broader questions about the building using the same AI assistant available in the Aida Platform.

Overview

Webex devices already support touch-based building control through the Webex Workspace Integration. Aida adds voice on top of that integration:

• Hands-free room control — lights, shades, and more without touching the screen
• Same automation path — voice triggers the same controller commands as panel taps
• Room-aware — the device you speak from determines which room and controller respond
• Conversational AI (Phase 2) — energy questions, comfort requests, and compound commands

How users speak (2026)

Legacy invocation (Ok Webex, tell Aida to …) required a deprecated Cisco skill registration. Modern patterns:

Ok Webex, toggle the lights
Ok Webex, open the shades
Ok Webex, ask Aida to dim the lights    ← "Aida" as training phrase, not router

Train intents in Webex AI Studio (where licensed) or use a device macro that calls the Aida Platform. Brand Aida via welcome message and example phrases — not via a separate skill invocation name.

Relationship to Workspace Integration

:::important Not a second Aida integration The voice skill extends your existing Webex Workspace Integration. You do not create a new integration in the Aida Platform or upload a second manifest for voice. Devices, controllers, panels, and automation all come from the workspace integration you already configured. :::

Cisco treats touch control and voice as two different integration types. You need both enabled for the full experience:

	Workspace Integration	Aida Voice Skill
What it does	Touch panels, webhooks, device xAPI	Voice commands via Webex Assistant
Required for voice?	Yes — foundation	Add-on after workspace integration works
Configured in Aida	Site → Webex Integration (manifest, devices, panels)	Same site — shared device/controller data
Enabled in Control Hub	Workspaces → Integrations	Workspace → Assistant Skills
Path to controller	Panel tap → webhook → MQTT	Voice → Aida API → same MQTT

Workspace Integration (required)     Assistant Skill (voice add-on)
        │                                      │
        ├─ Devices discovered                  ├─ "Ok Webex, tell Aida …"
        ├─ Controller assigned               ├─ Enable Aida in Control Hub
        ├─ Panel deployed                      └─ Uses same room/controller mapping
        └─ Touch controls work

What customers do vs what Aida does

Who	Workspace Integration	Voice skill
Customer Webex admin	Upload manifest, activate integration	Enable Aida under Assistant Skills
Customer Aida admin	Client ID/secret, devices, panels, controllers	Nothing extra in Aida UI (Phase 1)
Aida (vendor)	Platform webhook + xAPI handlers	Host /parse endpoint; register skill in Cisco Developer Portal per deployment model

Voice without workspace integration will fail — there is no device-to-controller mapping. Touch without the voice skill still works normally.

Multi-organization deployments

If you are an Aida customer with your own Webex organization, your admin enables the Aida skill in your Control Hub after workspace integration is complete. Aida may register the skill in the Cisco Developer Portal on your behalf or guide your team through a one-time registration that points to Aida's shared skill endpoint. You do not need a separate Aida Platform site or manifest for voice.

Benefits

For room occupants

Benefit	Description
Hands-free control	Adjust lights and shades while presenting, on a call, or away from the touchscreen
Natural language	Say what you want instead of navigating panel widgets
Spoken confirmation	Aida replies on the room speakers and shows a short message on screen
No extra apps	Works on the Webex device already in the room — no phone app required
Intelligent answers	Ask about energy, comfort, or building status and get spoken responses (Phase 2)

For facility and IT teams

Benefit	Description
No duplicate automation	Voice reuses the same Aida Controller logic as panel buttons — one ruleset, multiple input methods
Room-scoped by device	Each Webex endpoint controls its assigned room; no manual room selection in voice commands
Central management	Panels, controller assignment, and integration stay in the Aida Platform Webex UI
Auditable	Voice-triggered actions flow through the same MQTT event path as touch events
Extensible	Start with lights and shades; expand to LLM-powered building queries and multi-step commands

Compared to touch-only control

	Touch panel	Voice skill
Input	Tap widgets on screen	Speak to Webex Assistant
Controller path	Webhook → MQTT → Controller	Same MQTT → Controller path
Aida setup	Webex Integration per site	Same integration — no second site setup
Cisco setup	Integrations (manifest)	Also Assistant Skills (enable Aida)
Best for	Precise slider adjustments, visual feedback	Quick commands, hands-busy scenarios

How it works

High-level flow

Room identification

The skill does not require users to say which site or room they are in. Webex includes the device ID of the endpoint where the user spoke. Aida maps that device to:

• The Aida Controller assigned in the Webex integration UI
• The site linked to that device's integration
• The control panel deployed on that device

As long as the Webex device is discovered, has a controller assigned, and has the Aida panel installed, voice commands apply to that room automatically.

Event equivalence

Voice control is designed to be functionally identical to tapping the panel:

1. User speaks a command (e.g. "toggle lights")
2. Aida translates it to the same widget event a panel tap would produce
3. The event is delivered to the assigned controller over MQTT
4. The controller runs the same automation as for a physical button press

This means existing controller configuration does not need a separate voice ruleset.

Phased capabilities

Phase	What users get
Phase 1	Fast voice commands for lights and shades on the default Aida control panel
Phase 2	Full Aida AI assistant — energy usage, comfort, maintenance questions, and compound requests ("close the shades and dim the lights to thirty percent")
Phase 3+	Custom panels per device, richer on-screen feedback, and admin tooling

Voice Action API (2026 — primary path)

New deployments use a plain JSON endpoint instead of the legacy encrypted /parse skill:

POST /api/webex/voice/action

{
  "deviceId": "<webex-device-id from Aida integration UI>",
  "text": "toggle the lights",
  "source": "ai-studio"
}

Response:

{
  "success": true,
  "message": "Toggling lights.",
  "deviceId": "...",
  "workspaceName": "Main Conference Room"
}

Authentication: Authorization: Bearer {WEBEX_VOICE_ACTION_TOKEN} or X-Voice-Action-Token header.

Platform env vars:

Variable	Purpose
WEBEX_VOICE_ACTION_ENABLED=true	Enable the endpoint
WEBEX_VOICE_ACTION_TOKEN	Shared secret for callers
WEBEX_VOICE_ACTION_DEV_MODE=1	Skip auth (local dev only)

Enable LLM path for open-ended questions (requires ANTHROPIC_API_KEY):

Variable	Purpose
WEBEX_VOICE_LLM_ENABLED=true	Route questions/compound requests through assistant LLM

Integration samples: backend/api/webex/assistant-skill/samples/ (AI Studio template + RoomOS macro).

:::note Room Ok Webex gap RoomOS does not expose assistant transcripts to macros, and the legacy skill portal is retired. Touch panel control works today. Voice ingress requires AI Studio (CC customers with injected deviceId), a device macro calling this API, or a future Cisco room-voice hook. :::

Supported voice commands (Phase 1)

These commands map to the Aida Platform Controls panel (aidaPlatformControls):

Say something like…	Action
"Toggle the lights" / "Turn the lights on" / "Turn the lights off"	Light on/off toggle
"Set the lights to fifty percent" / "Dim the lights"	Light brightness slider
"Open the shades" / "Close the shades"	Shade position
"Shades one third" / "Shades two thirds"	Shade preset position
"Show controls" / "Open Aida panel"	Opens the touch panel on screen

:::tip Natural phrasing You do not need exact wording. Aida matches common variations of these intents. For example, "it's too bright" may map to closing shades or dimming lights in Phase 2. :::

AI assistant on the room display (Phase 2)

Beyond panel commands, the skill connects to the same multi-agent Aida assistant used in the platform web UI and public API:

Agent	Example voice questions
Energy Savings	"How much energy did we use this week?"
Comfort Control	"It's too cold in here"
Site Asset	"Which lights are on in this building?"
Predictive Maintenance	"Does anything need maintenance?"

Responses are spoken on the room speakers (speak) with more detail shown on the device screen (reply). When a spoken request requires a physical change, the assistant triggers the same room control events as the fast path.

Prerequisites

Voice is Step 6 of Webex setup — not a standalone integration. Complete steps 1–5 in Webex Workspace Integration first.

Before enabling the Aida voice skill:

1. Webex Workspace Integration active for your Aida site — see Webex Workspace Integration
2. Touch controls verified — panel buttons successfully control the room (webhook → MQTT → controller)
3. Webex devices discovered and controllers assigned in the integration UI
4. Aida Platform Controls panel deployed to target devices
5. Webex Assistant supported on the device (Board, Desk, Room, Room Kit series)

Additional for voice only:

6. Aida Assistant skill registered and enabled in Control Hub → Assistant Skills
7. Assistant Skills Developer Portal allowed in Control Hub (if your org restricts integrations)

Setup overview

Voice setup assumes workspace integration is already complete and working.

Step 6 — Enable voice (after workspace integration)

Recommended (2026): Voice Action API

1. Set WEBEX_VOICE_ACTION_ENABLED and WEBEX_VOICE_ACTION_TOKEN on the Aida Platform
2. Deploy ingress for your environment:
   • AI Studio HTTP action — see assistant-skill/samples/ai-studio-action-template.md (requires CC + deviceId injection)
   • RoomOS macro — see assistant-skill/samples/aidaVoiceBridge.js (HTTP POST with per-device deviceId)
3. Verify with curl or macro: POST /api/webex/voice/action with { deviceId, text }

Legacy only (pre-registered skills)

1. Configure WEBEX_ASSISTANT_SKILL_* on the Aida Platform
2. Enable Aida under Control Hub → Assistant Skills (if org still has skill registered)

:::warning Developer portal retired The Assistant Skills Developer Portal no longer resolves. Do not plan new registrations on /parse. :::

For customer Aida administrators

• No separate Aida integration — continue managing devices, panels, and controllers in the existing Webex Integration UI
• Touch panel remains the supported room control path until voice ingress is configured

Example experience

Scenario: A presenter in a conference room wants to lower the shades without interrupting a Webex meeting.

1. User says: "Ok Webex, tell Aida to close the shades"
2. Webex Assistant confirms: "Closing the shades."
3. The room shades move via the assigned Aida Controller
4. The action is logged through the same event path as a panel tap

Scenario (Phase 2): A facilities manager wants a quick energy summary during a walkthrough.

1. User says: "Ok Webex, ask Aida how much energy this building used last week"
2. Aida queries the Energy Savings agent
3. Assistant speaks a short summary and shows details on the Board screen

Troubleshooting

Issue	What to check
"This room is not set up with Aida yet"	Device not discovered in Webex integration — refresh devices and assign a controller
"No controller is assigned to this room"	Assign an Aida Controller to the device in Panel/Device Management
Skill not recognized	Say "tell Aida" or "ask Aida to"; confirm Aida is Enabled under Control Hub → Assistant Skills (not Integrations)
Command works on panel but not voice	Workspace integration OK — check Assistant Skill enabled separately in Control Hub
Wrong room responds	Voice always targets the device you spoke to — verify controller assignment for that device

For integration-level issues (webhooks, panels, MQTT), see the troubleshooting section in Webex Workspace Integration.

Platform note

Cisco has placed Webex Assistant Skills in maintenance mode. New feature development on the Cisco side is limited, but existing skills continue to work on supported devices. Aida's voice layer is built on this stable skills framework and the Aida Platform's own assistant and integration services.

Next steps

• Webex Workspace Integration — Set up devices, panels, and controller assignment (required first)
• AI Assistant — Learn about the Aida assistant agents used in Phase 2
• Device Control — Understand lighting, shades, and HVAC control capabilities

---

Ready to add voice to your rooms? Start with the Webex Workspace Integration guide, then ask your Aida administrator to enable the Aida Assistant skill in Control Hub.