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 path | Who | What it does |
|---|---|---|
GET /channels/install | any signed-in user | What 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}/channels | viewer | The agent's channels, with this month's counts. |
POST /projects/{project_id}/agents/{agent_name}/channels | project admin | Connect a channel. See below. |
PATCH /projects/{project_id}/agents/{agent_name}/channels/{channel_id} | project admin | Rename, switch on or off, change limits or settings, or replace secrets. |
DELETE /projects/{project_id}/agents/{agent_name}/channels/{channel_id} | project admin | Remove a channel. |
POST /projects/{project_id}/agents/{agent_name}/channels/{channel_id}/test | project admin | Check the credentials against the vendor. |
GET /projects/{project_id}/agents/{agent_name}/channels/{channel_id}/messages | viewer | The message log: direction, status and run, without the users' text. |
POST /channels/{channel_id}/events | the vendor | The webhook every Teams activity, Slack event and WhatsApp notification goes to. Authenticated by the vendor's signature. |
GET /channels/{channel_id}/events | the vendor | WhatsApp's verify-token handshake. |
Connect a channel
Body of POST /projects/{project_id}/agents/{agent_name}/channels:
| Field | Type | What it is |
|---|---|---|
kind | string | teams, slack or whatsapp. |
name | string | A label, up to 80 characters. |
config | object | The vendor's settings. See below. |
secrets | object | The vendor's secrets. Stored in Vault, never returned. |
enabled | boolean | Default true. |
user_per_minute | integer | Messages per end user per minute, 0 to 600. Default 6. 0 turns the limit off. |
hourly_limit | integer | Runs per hour for the channel. Default 300. |
| Kind | config | secrets |
|---|---|---|
teams | app_id (required), app_tenant_id, allowed_tenant_ids | app_password |
slack | team_id, bot_user_id, reply_in_thread | signing_secret, bot_token |
whatsapp | phone_number_id, api_version, template_name, template_language | app_secret, access_token, verify_token |
The response includes the channel's webhook address, and lists the secrets that are set, never their values.
| Status | When |
|---|---|
400 | The 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. |
403 | The licence doesn't include channels, its channel limit is reached, or you aren't a project admin. |
409 | The agent already has a channel with that name. |
Was this page helpful?