Skip to main content

Channels

These routes connect an agent to Microsoft Teams, Slack or WhatsApp. The console routes take a Keycloak access token: viewers can read, project admins can change. Every change is an audit event.

Method and pathWhoWhat it does
GET /channels/installany signed-in userWhat this install allows: each vendor's settings and secrets, the hosts it needs and which are missing, the webhook base address, the secret store, and the licence's channel limits.
GET /projects/{project_id}/agents/{agent_name}/channelsviewerThe agent's channels, with this month's counts.
POST /projects/{project_id}/agents/{agent_name}/channelsproject adminConnect a channel. See below.
PATCH /projects/{project_id}/agents/{agent_name}/channels/{channel_id}project adminRename, switch on or off, change limits or settings, or replace secrets.
DELETE /projects/{project_id}/agents/{agent_name}/channels/{channel_id}project adminRemove a channel.
POST /projects/{project_id}/agents/{agent_name}/channels/{channel_id}/testproject adminCheck the credentials against the vendor.
GET /projects/{project_id}/agents/{agent_name}/channels/{channel_id}/messagesviewerThe message log: direction, status and run, without the users' text.
POST /channels/{channel_id}/eventsthe vendorThe webhook every Teams activity, Slack event and WhatsApp notification goes to. Authenticated by the vendor's signature.
GET /channels/{channel_id}/eventsthe vendorWhatsApp's verify-token handshake.

Connect a channel​

Body of POST /projects/{project_id}/agents/{agent_name}/channels:

FieldTypeWhat it is
kindstringteams, slack or whatsapp.
namestringA label, up to 80 characters.
configobjectThe vendor's settings. See below.
secretsobjectThe vendor's secrets. Stored in Vault, never returned.
enabledbooleanDefault true.
user_per_minuteintegerMessages per end user per minute, 0 to 600. Default 6. 0 turns the limit off.
hourly_limitintegerRuns per hour for the channel. Default 300.
Kindconfigsecrets
teamsapp_id (required), app_tenant_id, allowed_tenant_idsapp_password
slackteam_id, bot_user_id, reply_in_threadsigning_secret, bot_token
whatsappphone_number_id, api_version, template_name, template_languageapp_secret, access_token, verify_token

The response includes the channel's webhook address, and lists the secrets that are set, never their values.

StatusWhen
400The vendor's hosts aren't in channels.outboundHosts (the message names the setting and the hosts), a required setting or secret is missing, or the kind is unknown.
403The licence doesn't include channels, its channel limit is reached, or you aren't a project admin.
409The agent already has a channel with that name.
Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →