diff --git a/quill/channels/_category_.json b/quill/channels/_category_.json new file mode 100644 index 0000000000..1bb20beb0d --- /dev/null +++ b/quill/channels/_category_.json @@ -0,0 +1,4 @@ +{ + "position": 3, + "label": "Channels" +} diff --git a/quill/channels/assets/discord-bot_add-channel-menu.png b/quill/channels/assets/discord-bot_add-channel-menu.png new file mode 100644 index 0000000000..ed71b9ced1 Binary files /dev/null and b/quill/channels/assets/discord-bot_add-channel-menu.png differ diff --git a/quill/channels/assets/discord-bot_bot-connected.png b/quill/channels/assets/discord-bot_bot-connected.png new file mode 100644 index 0000000000..53e327e2dd Binary files /dev/null and b/quill/channels/assets/discord-bot_bot-connected.png differ diff --git a/quill/channels/assets/discord-bot_bot-token.png b/quill/channels/assets/discord-bot_bot-token.png new file mode 100644 index 0000000000..7a1ae25e70 Binary files /dev/null and b/quill/channels/assets/discord-bot_bot-token.png differ diff --git a/quill/channels/assets/discord-bot_channel-box.png b/quill/channels/assets/discord-bot_channel-box.png new file mode 100644 index 0000000000..fddbe6f2c0 Binary files /dev/null and b/quill/channels/assets/discord-bot_channel-box.png differ diff --git a/quill/channels/assets/discord-bot_channel-created.png b/quill/channels/assets/discord-bot_channel-created.png new file mode 100644 index 0000000000..593dc485e7 Binary files /dev/null and b/quill/channels/assets/discord-bot_channel-created.png differ diff --git a/quill/channels/assets/discord-bot_channel-details.png b/quill/channels/assets/discord-bot_channel-details.png new file mode 100644 index 0000000000..a181b2e8d6 Binary files /dev/null and b/quill/channels/assets/discord-bot_channel-details.png differ diff --git a/quill/channels/assets/discord-bot_channel-menu.png b/quill/channels/assets/discord-bot_channel-menu.png new file mode 100644 index 0000000000..6e206b41bb Binary files /dev/null and b/quill/channels/assets/discord-bot_channel-menu.png differ diff --git a/quill/channels/assets/discord-bot_conversation.png b/quill/channels/assets/discord-bot_conversation.png new file mode 100644 index 0000000000..6dc21adb09 Binary files /dev/null and b/quill/channels/assets/discord-bot_conversation.png differ diff --git a/quill/channels/assets/discord-bot_new-channel.png b/quill/channels/assets/discord-bot_new-channel.png new file mode 100644 index 0000000000..60a4ec9c20 Binary files /dev/null and b/quill/channels/assets/discord-bot_new-channel.png differ diff --git a/quill/channels/assets/discord-bot_orders-answer.png b/quill/channels/assets/discord-bot_orders-answer.png new file mode 100644 index 0000000000..9fdb19ac6a Binary files /dev/null and b/quill/channels/assets/discord-bot_orders-answer.png differ diff --git a/quill/channels/assets/discord-bot_parameter-mapping.png b/quill/channels/assets/discord-bot_parameter-mapping.png new file mode 100644 index 0000000000..f0550e8e3c Binary files /dev/null and b/quill/channels/assets/discord-bot_parameter-mapping.png differ diff --git a/quill/channels/assets/discord-bot_parameters.png b/quill/channels/assets/discord-bot_parameters.png new file mode 100644 index 0000000000..050a905fd6 Binary files /dev/null and b/quill/channels/assets/discord-bot_parameters.png differ diff --git a/quill/channels/assets/discord-bot_rotate-token.png b/quill/channels/assets/discord-bot_rotate-token.png new file mode 100644 index 0000000000..942837effe Binary files /dev/null and b/quill/channels/assets/discord-bot_rotate-token.png differ diff --git a/quill/channels/assets/discord-bot_token-rejected.png b/quill/channels/assets/discord-bot_token-rejected.png new file mode 100644 index 0000000000..2f7f9f64c5 Binary files /dev/null and b/quill/channels/assets/discord-bot_token-rejected.png differ diff --git a/quill/channels/assets/slack-bot_add-channel-menu.png b/quill/channels/assets/slack-bot_add-channel-menu.png new file mode 100644 index 0000000000..d53115901c Binary files /dev/null and b/quill/channels/assets/slack-bot_add-channel-menu.png differ diff --git a/quill/channels/assets/slack-bot_app-credentials.png b/quill/channels/assets/slack-bot_app-credentials.png new file mode 100644 index 0000000000..efc2be812f Binary files /dev/null and b/quill/channels/assets/slack-bot_app-credentials.png differ diff --git a/quill/channels/assets/slack-bot_bot-connected.png b/quill/channels/assets/slack-bot_bot-connected.png new file mode 100644 index 0000000000..3ee6d669cd Binary files /dev/null and b/quill/channels/assets/slack-bot_bot-connected.png differ diff --git a/quill/channels/assets/slack-bot_bot-token.png b/quill/channels/assets/slack-bot_bot-token.png new file mode 100644 index 0000000000..99a1189c3c Binary files /dev/null and b/quill/channels/assets/slack-bot_bot-token.png differ diff --git a/quill/channels/assets/slack-bot_channel-box.png b/quill/channels/assets/slack-bot_channel-box.png new file mode 100644 index 0000000000..4762cf351d Binary files /dev/null and b/quill/channels/assets/slack-bot_channel-box.png differ diff --git a/quill/channels/assets/slack-bot_channel-created.png b/quill/channels/assets/slack-bot_channel-created.png new file mode 100644 index 0000000000..469edd34f0 Binary files /dev/null and b/quill/channels/assets/slack-bot_channel-created.png differ diff --git a/quill/channels/assets/slack-bot_channel-details.png b/quill/channels/assets/slack-bot_channel-details.png new file mode 100644 index 0000000000..5e4372834b Binary files /dev/null and b/quill/channels/assets/slack-bot_channel-details.png differ diff --git a/quill/channels/assets/slack-bot_channel-menu.png b/quill/channels/assets/slack-bot_channel-menu.png new file mode 100644 index 0000000000..1e80c0f8e5 Binary files /dev/null and b/quill/channels/assets/slack-bot_channel-menu.png differ diff --git a/quill/channels/assets/slack-bot_conversation.png b/quill/channels/assets/slack-bot_conversation.png new file mode 100644 index 0000000000..795dfc6bdd Binary files /dev/null and b/quill/channels/assets/slack-bot_conversation.png differ diff --git a/quill/channels/assets/slack-bot_create-app.png b/quill/channels/assets/slack-bot_create-app.png new file mode 100644 index 0000000000..319b8ca0b1 Binary files /dev/null and b/quill/channels/assets/slack-bot_create-app.png differ diff --git a/quill/channels/assets/slack-bot_event-subscriptions.png b/quill/channels/assets/slack-bot_event-subscriptions.png new file mode 100644 index 0000000000..79420bbd4d Binary files /dev/null and b/quill/channels/assets/slack-bot_event-subscriptions.png differ diff --git a/quill/channels/assets/slack-bot_manifest.png b/quill/channels/assets/slack-bot_manifest.png new file mode 100644 index 0000000000..0bfe337ea8 Binary files /dev/null and b/quill/channels/assets/slack-bot_manifest.png differ diff --git a/quill/channels/assets/slack-bot_new-channel.png b/quill/channels/assets/slack-bot_new-channel.png new file mode 100644 index 0000000000..8364c64230 Binary files /dev/null and b/quill/channels/assets/slack-bot_new-channel.png differ diff --git a/quill/channels/assets/slack-bot_orders-answer.png b/quill/channels/assets/slack-bot_orders-answer.png new file mode 100644 index 0000000000..edb84cdf65 Binary files /dev/null and b/quill/channels/assets/slack-bot_orders-answer.png differ diff --git a/quill/channels/assets/slack-bot_parameter-mapping.png b/quill/channels/assets/slack-bot_parameter-mapping.png new file mode 100644 index 0000000000..16e88f33ca Binary files /dev/null and b/quill/channels/assets/slack-bot_parameter-mapping.png differ diff --git a/quill/channels/assets/slack-bot_parameters.png b/quill/channels/assets/slack-bot_parameters.png new file mode 100644 index 0000000000..3560f17d5c Binary files /dev/null and b/quill/channels/assets/slack-bot_parameters.png differ diff --git a/quill/channels/assets/slack-bot_paste-manifest.png b/quill/channels/assets/slack-bot_paste-manifest.png new file mode 100644 index 0000000000..6ca3de0063 Binary files /dev/null and b/quill/channels/assets/slack-bot_paste-manifest.png differ diff --git a/quill/channels/assets/slack-bot_rotate-credentials.png b/quill/channels/assets/slack-bot_rotate-credentials.png new file mode 100644 index 0000000000..afde3f19c6 Binary files /dev/null and b/quill/channels/assets/slack-bot_rotate-credentials.png differ diff --git a/quill/channels/assets/slack-bot_signature-failed.png b/quill/channels/assets/slack-bot_signature-failed.png new file mode 100644 index 0000000000..255a704c6f Binary files /dev/null and b/quill/channels/assets/slack-bot_signature-failed.png differ diff --git a/quill/channels/assets/slack-bot_signing-secret.png b/quill/channels/assets/slack-bot_signing-secret.png new file mode 100644 index 0000000000..2699bad8f5 Binary files /dev/null and b/quill/channels/assets/slack-bot_signing-secret.png differ diff --git a/quill/channels/assets/slack-bot_token-rejected.png b/quill/channels/assets/slack-bot_token-rejected.png new file mode 100644 index 0000000000..2044bce50b Binary files /dev/null and b/quill/channels/assets/slack-bot_token-rejected.png differ diff --git a/quill/channels/assets/slack-bot_url-not-responding.png b/quill/channels/assets/slack-bot_url-not-responding.png new file mode 100644 index 0000000000..3288cee8f8 Binary files /dev/null and b/quill/channels/assets/slack-bot_url-not-responding.png differ diff --git a/quill/channels/assets/snagit/discord-bot_add-channel-menu.snagx b/quill/channels/assets/snagit/discord-bot_add-channel-menu.snagx new file mode 100644 index 0000000000..812ada22f1 Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_add-channel-menu.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_bot-connected.snagx b/quill/channels/assets/snagit/discord-bot_bot-connected.snagx new file mode 100644 index 0000000000..388480ad36 Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_bot-connected.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_channel-created.snagx b/quill/channels/assets/snagit/discord-bot_channel-created.snagx new file mode 100644 index 0000000000..36dd9ecbc9 Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_channel-created.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_channel-details.snagx b/quill/channels/assets/snagit/discord-bot_channel-details.snagx new file mode 100644 index 0000000000..cf53008c68 Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_channel-details.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_channel-menu.snagx b/quill/channels/assets/snagit/discord-bot_channel-menu.snagx new file mode 100644 index 0000000000..dd611d5dec Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_channel-menu.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_new-channel.snagx b/quill/channels/assets/snagit/discord-bot_new-channel.snagx new file mode 100644 index 0000000000..dbbe082ffc Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_new-channel.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_orders-answer.snagx b/quill/channels/assets/snagit/discord-bot_orders-answer.snagx new file mode 100644 index 0000000000..4c1f0453a1 Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_orders-answer.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_parameter-mapping.snagx b/quill/channels/assets/snagit/discord-bot_parameter-mapping.snagx new file mode 100644 index 0000000000..600f173481 Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_parameter-mapping.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_parameters.snagx b/quill/channels/assets/snagit/discord-bot_parameters.snagx new file mode 100644 index 0000000000..d3cd9ae19d Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_parameters.snagx differ diff --git a/quill/channels/assets/snagit/discord-bot_rotate-token.snagx b/quill/channels/assets/snagit/discord-bot_rotate-token.snagx new file mode 100644 index 0000000000..88c98cab97 Binary files /dev/null and b/quill/channels/assets/snagit/discord-bot_rotate-token.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_add-channel-menu.snagx b/quill/channels/assets/snagit/slack-bot_add-channel-menu.snagx new file mode 100644 index 0000000000..4b64239bfb Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_add-channel-menu.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_app-credentials.snagx b/quill/channels/assets/snagit/slack-bot_app-credentials.snagx new file mode 100644 index 0000000000..6c559b5bd2 Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_app-credentials.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_bot-connected.snagx b/quill/channels/assets/snagit/slack-bot_bot-connected.snagx new file mode 100644 index 0000000000..2a941863e3 Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_bot-connected.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_bot-token.snagx b/quill/channels/assets/snagit/slack-bot_bot-token.snagx new file mode 100644 index 0000000000..a9826da5bd Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_bot-token.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_channel-box.snagx b/quill/channels/assets/snagit/slack-bot_channel-box.snagx new file mode 100644 index 0000000000..3cad8e0a4b Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_channel-box.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_channel-created.snagx b/quill/channels/assets/snagit/slack-bot_channel-created.snagx new file mode 100644 index 0000000000..a68f520f41 Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_channel-created.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_channel-details.snagx b/quill/channels/assets/snagit/slack-bot_channel-details.snagx new file mode 100644 index 0000000000..f9cd72bcc2 Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_channel-details.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_channel-menu.snagx b/quill/channels/assets/snagit/slack-bot_channel-menu.snagx new file mode 100644 index 0000000000..c56ef3fa4e Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_channel-menu.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_create-app.snagx b/quill/channels/assets/snagit/slack-bot_create-app.snagx new file mode 100644 index 0000000000..e874a45c38 Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_create-app.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_event-subscriptions.snagx b/quill/channels/assets/snagit/slack-bot_event-subscriptions.snagx new file mode 100644 index 0000000000..46e2159b83 Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_event-subscriptions.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_manifest.snagx b/quill/channels/assets/snagit/slack-bot_manifest.snagx new file mode 100644 index 0000000000..6a5c96e79a Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_manifest.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_new-channel.snagx b/quill/channels/assets/snagit/slack-bot_new-channel.snagx new file mode 100644 index 0000000000..9d4a60496c Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_new-channel.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_parameter-mapping.snagx b/quill/channels/assets/snagit/slack-bot_parameter-mapping.snagx new file mode 100644 index 0000000000..c1163f705d Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_parameter-mapping.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_parameters.snagx b/quill/channels/assets/snagit/slack-bot_parameters.snagx new file mode 100644 index 0000000000..bea5097a2f Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_parameters.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_paste-manifest.snagx b/quill/channels/assets/snagit/slack-bot_paste-manifest.snagx new file mode 100644 index 0000000000..797da779cc Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_paste-manifest.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_rotate-credentials.snagx b/quill/channels/assets/snagit/slack-bot_rotate-credentials.snagx new file mode 100644 index 0000000000..f5e90993ca Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_rotate-credentials.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_signing-secret.snagx b/quill/channels/assets/snagit/slack-bot_signing-secret.snagx new file mode 100644 index 0000000000..4d1fc8baab Binary files /dev/null and b/quill/channels/assets/snagit/slack-bot_signing-secret.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_add-channel-menu.snagx b/quill/channels/assets/snagit/telegram-bot_add-channel-menu.snagx new file mode 100644 index 0000000000..7f6d4f2ca7 Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_add-channel-menu.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_bot-messages.snagx b/quill/channels/assets/snagit/telegram-bot_bot-messages.snagx new file mode 100644 index 0000000000..c593a47e60 Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_bot-messages.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_channel-created.snagx b/quill/channels/assets/snagit/telegram-bot_channel-created.snagx new file mode 100644 index 0000000000..a9a1346d79 Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_channel-created.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_channel-details.snagx b/quill/channels/assets/snagit/telegram-bot_channel-details.snagx new file mode 100644 index 0000000000..99c837d576 Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_channel-details.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_channel-menu.snagx b/quill/channels/assets/snagit/telegram-bot_channel-menu.snagx new file mode 100644 index 0000000000..6a7aab5605 Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_channel-menu.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_new-channel.snagx b/quill/channels/assets/snagit/telegram-bot_new-channel.snagx new file mode 100644 index 0000000000..3932878a47 Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_new-channel.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_parameter-mapping.snagx b/quill/channels/assets/snagit/telegram-bot_parameter-mapping.snagx new file mode 100644 index 0000000000..aedda0f03b Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_parameter-mapping.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_parameters.snagx b/quill/channels/assets/snagit/telegram-bot_parameters.snagx new file mode 100644 index 0000000000..1c627d71d0 Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_parameters.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_rotate-token.snagx b/quill/channels/assets/snagit/telegram-bot_rotate-token.snagx new file mode 100644 index 0000000000..4812418935 Binary files /dev/null and b/quill/channels/assets/snagit/telegram-bot_rotate-token.snagx differ diff --git a/quill/channels/assets/telegram-bot_add-channel-menu.png b/quill/channels/assets/telegram-bot_add-channel-menu.png new file mode 100644 index 0000000000..bb8cdabe26 Binary files /dev/null and b/quill/channels/assets/telegram-bot_add-channel-menu.png differ diff --git a/quill/channels/assets/telegram-bot_bot-messages.png b/quill/channels/assets/telegram-bot_bot-messages.png new file mode 100644 index 0000000000..9a05f5232e Binary files /dev/null and b/quill/channels/assets/telegram-bot_bot-messages.png differ diff --git a/quill/channels/assets/telegram-bot_botfather-newbot.png b/quill/channels/assets/telegram-bot_botfather-newbot.png new file mode 100644 index 0000000000..7ef4809a73 Binary files /dev/null and b/quill/channels/assets/telegram-bot_botfather-newbot.png differ diff --git a/quill/channels/assets/telegram-bot_channel-box.png b/quill/channels/assets/telegram-bot_channel-box.png new file mode 100644 index 0000000000..6576da7b15 Binary files /dev/null and b/quill/channels/assets/telegram-bot_channel-box.png differ diff --git a/quill/channels/assets/telegram-bot_channel-created.png b/quill/channels/assets/telegram-bot_channel-created.png new file mode 100644 index 0000000000..59e21b8abf Binary files /dev/null and b/quill/channels/assets/telegram-bot_channel-created.png differ diff --git a/quill/channels/assets/telegram-bot_channel-details.png b/quill/channels/assets/telegram-bot_channel-details.png new file mode 100644 index 0000000000..b36305bff1 Binary files /dev/null and b/quill/channels/assets/telegram-bot_channel-details.png differ diff --git a/quill/channels/assets/telegram-bot_channel-menu.png b/quill/channels/assets/telegram-bot_channel-menu.png new file mode 100644 index 0000000000..bfb8284f4e Binary files /dev/null and b/quill/channels/assets/telegram-bot_channel-menu.png differ diff --git a/quill/channels/assets/telegram-bot_clear.png b/quill/channels/assets/telegram-bot_clear.png new file mode 100644 index 0000000000..f8f954a9d1 Binary files /dev/null and b/quill/channels/assets/telegram-bot_clear.png differ diff --git a/quill/channels/assets/telegram-bot_conversation.png b/quill/channels/assets/telegram-bot_conversation.png new file mode 100644 index 0000000000..4c10a5c2e4 Binary files /dev/null and b/quill/channels/assets/telegram-bot_conversation.png differ diff --git a/quill/channels/assets/telegram-bot_new-channel.png b/quill/channels/assets/telegram-bot_new-channel.png new file mode 100644 index 0000000000..32bca36ea9 Binary files /dev/null and b/quill/channels/assets/telegram-bot_new-channel.png differ diff --git a/quill/channels/assets/telegram-bot_orders-answer.png b/quill/channels/assets/telegram-bot_orders-answer.png new file mode 100644 index 0000000000..23e772edf9 Binary files /dev/null and b/quill/channels/assets/telegram-bot_orders-answer.png differ diff --git a/quill/channels/assets/telegram-bot_parameter-mapping.png b/quill/channels/assets/telegram-bot_parameter-mapping.png new file mode 100644 index 0000000000..0ec195782c Binary files /dev/null and b/quill/channels/assets/telegram-bot_parameter-mapping.png differ diff --git a/quill/channels/assets/telegram-bot_parameters.png b/quill/channels/assets/telegram-bot_parameters.png new file mode 100644 index 0000000000..c3f430d554 Binary files /dev/null and b/quill/channels/assets/telegram-bot_parameters.png differ diff --git a/quill/channels/assets/telegram-bot_phone-flow.png b/quill/channels/assets/telegram-bot_phone-flow.png new file mode 100644 index 0000000000..798d73c4d3 Binary files /dev/null and b/quill/channels/assets/telegram-bot_phone-flow.png differ diff --git a/quill/channels/assets/telegram-bot_rotate-token.png b/quill/channels/assets/telegram-bot_rotate-token.png new file mode 100644 index 0000000000..c48d6f5029 Binary files /dev/null and b/quill/channels/assets/telegram-bot_rotate-token.png differ diff --git a/quill/channels/assets/telegram-bot_share-phone-request.png b/quill/channels/assets/telegram-bot_share-phone-request.png new file mode 100644 index 0000000000..2a5bdaa2b5 Binary files /dev/null and b/quill/channels/assets/telegram-bot_share-phone-request.png differ diff --git a/quill/channels/discord-bot.mdx b/quill/channels/discord-bot.mdx new file mode 100644 index 0000000000..6c7a4d99e6 --- /dev/null +++ b/quill/channels/discord-bot.mdx @@ -0,0 +1,588 @@ +--- +title: "Channels: Discord bot" +sidebar_label: Discord bot +sidebar_position: 3 +description: "A Discord bot channel for a Quill app: creating the bot in the Discord Developer Portal, connecting it to the app and inviting it to your server, what its users meet in a direct message with the bot, binding agent parameters, managing the channel, and the limitations of a Discord bot." +--- + +import Admonition from '@theme/Admonition'; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + +# Channels: Discord bot + + +* A Quill **Discord bot** channel lets your users converse with an [agent](../overview.mdx#ai-agent) + of your app in a direct message with a bot on Discord. + Users can message the bot from any Discord client, and the agent will answer from the app's internal database. + +* The bot is created in the **Discord Developer Portal**, as part of a Discord application, free of charge. + The Discord Developer Portal also issues the **bot token**, a credential that Quill needs to operate the bot. + Quill opens the connection to Discord and receives the users' messages through this connection, so the deployment needs no + public address or open inbound port. + +* The channel is added from Quill's management dashboard, using one short form that asks you to select one of the agents you + created and provide the bot token and an optional channel name. + * If the selected agent has parameters, the form also asks you to settle each parameter's value. + You can either provide a fixed value, or take the value from the Discord user the bot is chatting with: the user's Discord + ID or username. + * Once the channel is added, the bot has to be invited to a Discord server your users are in. + A **server** is a space that Discord users join to chat with each other; a user can message a bot only if the user and + the bot are both members of the same server. + +* In this article: + * [Prerequisites](#prerequisites) + * [Creating a bot in the Discord Developer Portal](#creating-a-bot-in-the-discord-developer-portal) + * [Connecting the bot to your app](#connecting-the-bot-to-your-app) + * [Opening the Add channel menu](#opening-the-add-channel-menu) + * [Filling in the channel form](#filling-in-the-channel-form) + * [Finishing the connection on Discord](#finishing-the-connection-on-discord) + * [Checking the new channel](#checking-the-new-channel) + * [Chatting with the bot](#chatting-with-the-bot) + * [Starting a conversation](#starting-a-conversation) + * [Messages the bot does not answer](#messages-the-bot-does-not-answer) + * [Binding agent parameters](#binding-agent-parameters) + * [Choosing a source for each parameter](#choosing-a-source-for-each-parameter) + * [Binding a parameter to a constant value](#binding-a-parameter-to-a-constant-value) + * [Managing the channel](#managing-the-channel) + * [Pausing and deleting the channel](#pausing-and-deleting-the-channel) + * [Rotating the bot token](#rotating-the-bot-token) + * [The tabs of the details view](#the-tabs-of-the-details-view) + * [Discord bot limitations](#discord-bot-limitations) + * [Troubleshooting](#troubleshooting) + + + + + +Before adding a Discord bot channel, make sure you have: + +* **An agent in your app.** + The channel is added for one of the app's agents, and this agent will answer the users who message the bot. + To add an agent, see [Getting started: Adding an AI agent](../getting-started/adding-an-ai-agent.mdx). +* **A Discord account.** + The bot is created in the Discord Developer Portal, while you are signed in with your + [Discord account](https://discord.com/register). + Once the channel is added, you can try the bot out from the same account. +* **A Discord server your users are in.** + Once the channel is added, you invite the bot to this server using a link that Quill provides, since a user can message a bot + only if the user and the bot are both members of the same server. + If you have no server yet, you can [create one](https://support.discord.com/hc/en-us/articles/204849977) in any Discord client, + free of charge. +* **Access to Discord from the machine running Quill.** + The only connections the bot needs are the ones Quill opens to Discord, at `discord.com` and `gateway.discord.gg`. + The users' messages travel to Quill over these connections too, so a deployment that cannot be reached from the internet, like + one running on your machine, can still operate a bot. + + + + + +To create the bot, open the [Discord Developer Portal](https://discord.com/developers/applications), sign in with your Discord +account, and click **New Application**. +Discord asks for a **name** for the application, e.g., `Northwind Traders Catalog`, and creates the application together with a bot +of the same name. +This name is the bot's username on Discord, shown in the users' chats with the bot, and Quill names the channel after the username +(unless you name the channel yourself). + +Then open the application's **Bot** page, listed in the Discord Developer Portal's sidebar under **Overview**, and click +**Reset Token**: the page shows the **bot token** once. +Copy the token: you will need to hand it to Quill in the next section, +[Connecting the bot to your app](#connecting-the-bot-to-your-app). + +![The Bot page after Reset Token](./assets/discord-bot_bot-token.png) + +Nothing else on the Bot page needs changing. The bot reads only the direct messages sent to it, so the toggles under +**Privileged Gateway Intents** stay off, and no box under **Bot Permissions** needs ticking. + + + +The bot token is a secret: anyone holding it can control the bot, read the messages users send to it, and answer in the bot's name. +If the token ever leaks, click **Reset Token** on the Bot page and enter the new token in the channel as described in +[Rotating the bot token](#rotating-the-bot-token). + + + + + + + +To connect the bot to the app, add a **Discord** channel for one of the app's agents. + +* The channel is added in a short form that asks you to provide the bot token issued by the Discord Developer Portal, and to + select the agent that will answer the users. +* Once the channel is added, Quill connects to Discord as the bot. + Then invite the bot to your server, so your users can message it. + + + +### Opening the Add channel menu + +In Quill's management dashboard, open the app from **My apps**. The app's **Overview** holds a **Channels** section: click the +section's **Add channel** button to open the menu of channel types, and select **Discord**. + +![The Add channel menu](./assets/discord-bot_add-channel-menu.png) + + + +The [Add agent wizard](../getting-started/adding-an-ai-agent.mdx#saving-the-agent) ends on an **Add a channel** stage that shows +the same Channels section, so a bot can also be connected right after its agent is created. +The form then has no **Agent** field: the channel is added for the agent the wizard just created. + + + + + + + +### Filling in the channel form + +Selecting **Discord** opens the **New Discord channel** form. + +![New Discord channel](./assets/discord-bot_new-channel.png) + +1. **No Discord app yet?** + Click to expand a reminder of the two Discord Developer Portal steps described in + [Creating a bot in the Discord Developer Portal](#creating-a-bot-in-the-discord-developer-portal). +2. **Agent** + Select the agent that will answer the bot's users. The list holds the app's agents. + + + + When the form is opened from the [Add agent wizard](../getting-started/adding-an-ai-agent.mdx#saving-the-agent), the channel is + added for the newly created agent and this field is absent. + + + +3. **Bot token** + Paste the token you copied from the Bot page. The field shows the token as dots; click the eye icon to reveal it. + Quill validates the token with Discord when the channel is added, and never displays it again afterwards. +4. **Channel name** (optional) + If you leave this field empty, Quill will name the channel after the bot's username, e.g., `Northwind Traders Catalog`. +5. **Connect bot** + Click to add the channel. If Discord rejects the token, or the bot is already connected to another channel, the form will + report the error and no channel will be added. + + + +When the selected agent has parameters, a **Parameters** section appears below the channel name, described in +[Binding agent parameters](#binding-agent-parameters). + + + + + + + +### Finishing the connection on Discord + +Once the channel is added, the form is replaced by a sheet that shows the state of the bot's connection and the two steps that +remain on the Discord side: + +![The channel added](./assets/discord-bot_bot-connected.png) + +1. **Northwind Traders Catalog** + The bot the channel is connected to, and the state of the connection: + * **Token valid**: Discord accepted the bot token. + * **Gateway connected**: Quill's connection to Discord, over which the users' messages arrive, is open. + * **Waiting for the first message...**: no user has messaged the bot yet. +2. **Invite the bot to a server** + The invite link for the bot. + Copy the link and open it in a browser: Discord asks you to select the server under **Add to server** and to authorize the + bot, and then adds the bot to the server as a member. + Your users have to be members of this server to message the bot. +3. **Open a direct message** + The way a user reaches the bot. + To converse with the bot, a user opens a direct message with it: on the server, the user clicks the bot's name, in the member + list or in a message, and then **Message** on the bot's profile card. + The direct message is private: the other members of the server do not see it. +4. **Done** + Click to close the sheet. + The connection state and the invite link remain available in the channel's [Connect](#the-connect-tab) tab. + + + + + +### Checking the new channel + +The new channel appears in the **Channels** section: + +![The new channel](./assets/discord-bot_channel-created.png) + +1. **Channel name** + The channel's name, with the bot's username beneath it. + In this example the name was left empty, so the channel is named after the username. +2. **Status** + **Active**: the channel is enabled; **Disabled**: the channel is paused. + Pausing and resuming a channel is described in + [Dashboard: Channels view](../dashboard/channels-view.mdx#pausing-and-resuming-a-channel). +3. **Active links** + Embed links belong to web widget channels; a Discord bot channel has none, so the column shows a dash. + + + + + + + +Once the bot is invited to your Discord server, every member of the server can message it. A user who opens a direct message with +the bot can ask questions, and the agent will answer from the app's internal database. +The users need no account with Quill and no instructions. This section describes the chat as an end user experiences it, so that +you know what to expect and what to tell your users. + + + +### Starting a conversation + +On Discord, a user opens a direct message with the bot and types a question. +The chat captures shown in this article were taken in Discord's web client, at `discord.com`; the desktop and mobile apps present +similar screens. + + + +Unlike a [Telegram bot](../channels/telegram-bot.mdx#starting-a-conversation), a Discord bot needs no `/start` command: the first +message a user sends is already a question to the agent, and the bot answers it. + + + +![A conversation with the bot](./assets/discord-bot_conversation.png) + +The capture above shows a first question and the bot's answer. +The following holds for every conversation with the bot: + +* **The reply is streamed into the chat as the agent composes it.** + The bot posts the reply and keeps updating the message until the reply is complete, which is why Discord marks the message as + **(edited)**. +* **Messages a user sends while the bot is still answering wait their turn.** + The bot answers them one by one, as long as the queue Quill keeps for this user has room. +* **The bot recognizes no commands.** + Every message is handled as a question, including messages that start with `/`. + +The behavior common to all channels, like the conversation's context, is described in the channels overview, in +[Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels). + + + + + +### Messages the bot does not answer + +The bot answers text-only messages. A message that carries an attachment, like a photo or a file, or that has no text at all, is +answered with "I can only read text messages right now." +The bot answers in direct messages only. A message posted in one of the server's chat rooms, such as #general, where every member +can read it, gets no reply, even if the message mentions the bot. + + + + + + + +Some agents have **parameters**: values the agent's queries require, and that must come from the channel rather than be chosen +by the LLM. e.g., the ID of the customer whose orders the agent looks up. +When you add a Discord bot channel for such an agent, the form asks you to bind each parameter to a source, which can be: + +* A constant value that you type, which is then the same for all bot users. +* A detail of the Discord user who is messaging the bot: the user's Discord ID or username. + The parameter then carries a different value for each user, so that each user is answered about this user's own data. + +This section describes the sources a parameter can be bound to, and shows a parameter bound to a constant value. + + + +### Choosing a source for each parameter + +When the selected agent has parameters, the channel form presents a **Parameters** section with one row per parameter, labeled +with the parameter's name, e.g., `customerPhone`. +In each parameter row, select where the parameter's value comes from: + +![Choosing a source for a parameter](./assets/discord-bot_parameter-mapping.png) + +1. The parameter's source + Select the source from the list: + * **Constant value** + A value that you type in the form. Quill will then pass this value to the agent with every message, from every user. + e.g., the ID of the customer whose Discord server the bot was invited to. + * **Sender Discord user ID** + The numeric ID of the Discord user who sent the message. + * **Sender Discord username** + The Discord username of the user who sent the message. + + The user ID and username sources tie the answers to the Discord user, and suit an app whose data holds the users' Discord IDs + or usernames. +2. **Value** + The value to bind when the source is **Constant value**. + +The bindings can be changed later in the channel's **Parameters** tab, described in the +[Parameters](#the-parameters-tab) tab section of Managing the channel. + + + + + +### Binding a parameter to a constant value + +In this example, the app's **Order Lookup Assistant** agent has a `customerPhone` parameter: the agent's queries find a customer's +orders by the customer's phone number. +The bot is meant for the Discord server of a single customer, where every member belongs to this customer, so the channel binds the +parameter to a constant value: the customer's phone number. The agent then answers every user of this bot about this customer's +orders: + +![The orders of the bound customer](./assets/discord-bot_orders-answer.png) + +A constant value suits a channel whose users all share the value, like the bot above. + + + + + + + +Once added, the channel is managed from its details view, described in +[Dashboard: Channels view](../dashboard/channels-view.mdx#the-channel-s-details-view): the view's header carries the +**Pause**/**Resume** button and the **⋮** menu with **Edit** and **Delete**, common to every channel type, and the tabs below the +header are specific to the channel type. + +To open the details view, open the app from **My apps** in Quill's management dashboard, select **Channels** in the sidebar, and +click the channel's box: + +![The channel's box in the Channels view](./assets/discord-bot_channel-box.png) + +--- + + + +### Pausing and deleting the channel + +To pause or resume the channel, click **Pause**/**Resume** in the header; to delete it, select **Delete** in the header's **⋮** menu. + +![Pause and the channel's menu in the details view's header](./assets/discord-bot_channel-menu.png) + +Both actions are explained in the Channels view article, in +[Pausing and resuming a channel](../dashboard/channels-view.mdx#pausing-and-resuming-a-channel) and +[Deleting a channel](../dashboard/channels-view.mdx#deleting-a-channel). Each of them also has a Discord side, explained here: + +* A paused bot stops answering, and Quill closes its connection to Discord, so the bot appears offline on Discord. + Messages users send while the channel is paused do not reach Quill, and will not be answered when the channel is resumed. +* A deleted channel stops the bot, but the bot itself remains yours in the Discord Developer Portal, and a member of your server; + its token can be used to connect it again. + + + + + +### Rotating the bot token + +To replace the bot token, select **Edit** in the header's **⋮** menu, and rotate the token in the **Edit channel** form. +If you reset the bot token in the Discord Developer Portal for any reason (e.g., because the existing token leaked), you have to +enter the new token here: Discord stops accepting the old token the moment a new one is issued, so the bot stops answering until the +channel holds the new token. + +![Rotating the bot token](./assets/discord-bot_rotate-token.png) + +1. **Rotate bot token** + Turn the toggle on to replace the current token. +2. **New bot token** + Paste the new token. Quill will validate the token with Discord before saving it. + The token has to belong to the same bot as the current one; the token of a different bot is refused. +3. **Save changes** + Click to save. + The bot resumes answering under the new token. + + + + + +### The tabs of the details view + +The details view presents an informative **Connect** tab, and a **Parameters** tab that allows you to change the bindings of the +agent's parameters: + +--- + +#### The Connect tab + +The **Connect** tab shows the state of the bot's connection to Discord, the bot's invite link, and the way a user opens a direct +message with the bot. + +![The Connect tab](./assets/discord-bot_channel-details.png) + +1. **Connect** + Open the Connect tab. +2. **Connection** + The Discord bot the channel is connected to, and the state of the connection: + * **Token valid** or **Token rejected** + Whether Discord still accepts the bot token. While the tab is open, Quill re-checks the token with Discord every few minutes. + A rejected token comes with alerts below the **Connection** card, asking you to reset the token on the app's Bot page in the + Discord Developer Portal, and rotate it in the channel. + * **Gateway connected**, **Connecting...**, **Gateway disconnected**, or **Paused** + The state of Quill's connection to Discord, over which the users' messages arrive. + When the connection is down, the reason is shown in an alert below the **Connection** card. + * **Last message** + The time of the last message a user sent to the bot, or **Waiting for the first message...** if no user has messaged the bot + yet. + * **Last reply could not be delivered** + A red alert shown below the **Connection** card when Discord refused to deliver the bot's last reply, quoting Discord's error. +3. **Invite the bot** + The two steps on the Discord side, as shown when the channel was added: the bot's invite link, which you can open to invite the + bot to another server your users are in, and the way a user opens a direct message with the bot. + +When the channel is paused, the tab opens with an alert saying so, and the connection card shows **Paused**. + +--- + +#### The Parameters tab + +The **Parameters** tab lists the agent's parameters and the source each of them is currently bound to, as set when the channel was +added, and lets you change the bindings. +A parameter that is added to the [agent configuration](../getting-started/adding-an-ai-agent.mdx#modifying-the-agent-configuration) +after the channel was added appears in this tab unbound, and the bot will not answer until the parameter is bound: users get the +reply "Sorry - something went wrong handling that message. Please try again." + +![The Parameters tab](./assets/discord-bot_parameters.png) + +1. **Parameters** + Open the Parameters tab. +2. **Edit** + Click to make the bindings editable, and click **Save** when done. +3. **customerPhone** + The example agent has one parameter, `customerPhone`, bound to a constant value: the phone number of the customer the bot + serves (see [Binding agent parameters](#binding-agent-parameters)). + Each row shows a parameter's name, the source the parameter is bound to, and, for a constant, the bound value. + + + + + + + +A Discord bot channel is designed to answer, in a direct message, any member of a server the bot is in. +The limits below follow this design and Discord's own rules. None of them can be changed in the channel's settings. + +* **Any member of a server the bot is in can chat with it.** + The channel cannot select the users that will have access to the bot: + * Any member of a server the bot was invited to can open a direct message with the bot and ask it questions. + * Agent parameters bound to the Discord user can tie the answers to this user's own data, but cannot turn anyone away. + + What you do control is which servers the bot is added to. The **Public Bot** toggle on the app's Bot page in the Discord Developer + Portal decides who can add the bot to a server: when the toggle is on, as it is by default, anyone who has the invite link can add + the bot to a server that this person manages; when the toggle is off, only you can. +* **The bot answers in direct messages only.** + A message posted in one of the server's chat rooms, such as #general, where every member can read it, gets no reply, even if the + message mentions the bot. +* **The bot answers text-only messages.** + In a direct message, a message with an attachment, e.g., an image or a file, or a message with no text, gets the reply "I can only + read text messages right now." +* **The agent remembers a conversation for one day at most.** + A user cannot make the agent forget sooner. + See [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels) + in the channels overview. +* **Messages sent faster than the bot answers may go unanswered.** + See [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels) + in the channels overview. +* **The bot's own messages cannot be customized.** + See [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels) + in the channels overview. + + + + + + + +Symptoms met by the users of every bot type, not just of a Discord bot, are listed in the channels overview, in +[Troubleshooting](../channels/overview.mdx#troubleshooting). + + + +The symptoms below are shown by a Discord bot channel when something goes wrong, each with its likely cause and what to do about it. +The first symptoms are seen in Quill's management dashboard: in the channel form, in the **Edit channel** form, and in the channel's +[Connect](#the-connect-tab) tab. The rest are encountered by the bot's users on Discord, in the server's chat rooms or in their direct +messages with the bot. + + + +### In the dashboard + +* **Clicking `Connect bot` fails with "discord rejected the bot token".** + Likely cause: the token pasted in the form may be incomplete or mistyped, or a newer token may have been issued for the bot in the + Discord Developer Portal, so this one is no longer accepted. + What to do: whichever the cause, reset the token, since the Discord Developer Portal shows a token only once: open the app's Bot + page there, click **Reset Token**, and paste the new token in the form's [Bot token](#filling-in-the-channel-form) field. +* **Clicking `Connect bot` fails with "that token belongs to a user account, not a bot".** + Likely cause: the pasted token may be the token of a Discord user account rather than the bot's. + What to do: copy the token from the app's Bot page in the Discord Developer Portal, as described in + [Creating a bot in the Discord Developer Portal](#creating-a-bot-in-the-discord-developer-portal). +* **Clicking `Connect bot` fails with "Discord bot ... is already connected".** + Likely cause: the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve + only one channel. When the channel is in another app, the message names that app. + What to do: delete the channel that holds the bot, in this app or in the app the message names, as described in + [Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another application, with its own bot, in the + Discord Developer Portal, as described in + [Creating a bot in the Discord Developer Portal](#creating-a-bot-in-the-discord-developer-portal), and paste the new bot's token in + this form instead. +* **Clicking `Save changes` in the `Edit channel` form fails with "the token belongs to a different bot".** + Likely cause: the new token may have been copied from the Bot page of a different application in the Discord Developer Portal. + What to do: copy the token from the Bot page, in the Discord Developer Portal, of the application whose bot the channel was created + for. + To switch to a different bot, add a new channel for that bot instead, as described in + [Connecting the bot to your app](#connecting-the-bot-to-your-app). +* **The `Connect` tab shows "Token rejected", and the bot does not answer.** + Likely cause: the token may have been reset in the Discord Developer Portal, so Discord no longer accepts it. + The bot is offline on Discord, and messages users send meanwhile do not reach Quill and are not answered later. + + ![The Connect tab with a rejected token](./assets/discord-bot_token-rejected.png) + + What to do: if you hold the token issued at the reset, enter it in the channel, as described in + [Rotating the bot token](#rotating-the-bot-token). If you do not, click **Reset Token** on the app's Bot page in the Discord + Developer Portal, and enter the token it shows in the channel the same way. +* **The `Connect` tab shows "Gateway disconnected" or "Connecting...", and the bot does not answer.** + Likely cause: Quill may be unable to reach Discord. The red alert under the connection card in the Connect tab quotes the error + Quill received. + The bot needs the machine running Quill to have access to `discord.com` and `gateway.discord.gg`, as described in + [Prerequisites](#prerequisites); a firewall or a proxy blocking these addresses is the usual cause. + What to do: allow outgoing HTTPS connections from the machine running Quill to these two addresses in the firewall or proxy that + blocks them, or ask your network administrator to. Quill reconnects on its own, within a few minutes of the access returning. +* **The `Connect` tab shows "Paused", and the bot does not answer.** + Likely cause: the channel was paused, using **Pause** in the header of its details view. + Messages users send while the channel is paused do not reach Quill and are not answered later. + What to do: resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). +* **The `Connect` tab shows a red alert, "Last reply could not be delivered", under the connection card.** + Likely cause: Discord may have refused to deliver the bot's last reply. The alert quotes Discord's error; the usual reason is that + the user can no longer receive messages from the bot, because the user left the server the bot is in, blocked the bot, or turned + off direct messages from server members in Discord's **Privacy & Safety** settings. + The alert does not name the user; most likely, it is the user whose message arrived last, at the time shown under + **Last message**. + What to do: the fix is on the user's side. Advise the user to undo whichever of these applies: rejoin the server, unblock the bot, + or allow direct messages from server members again. + + + + + +### On Discord + +* **A user cannot find the bot, or cannot open a direct message with it.** + Likely cause: the user may not be a member of the server the bot was invited to. On Discord, a user can message a bot only if the + user and the bot are both members of the same server. + What to do: invite the bot to a server the user is a member of, using the invite link in the [Connect](#the-connect-tab) tab, or + advise the user to join the server the bot is in. Then advise the user to open a direct message with the bot, as described in + [Finishing the connection on Discord](#finishing-the-connection-on-discord). +* **The bot does not reply to a message a user posted in one of the server's chat rooms.** + Likely cause: the bot reads only the direct messages sent to it. A message posted in one of the server's chat rooms, such as + #general, where every member can read it, does not reach the bot, even if the message mentions the bot. + What to do: advise the user to send the question in a direct message with the bot, opened as described in + [Finishing the connection on Discord](#finishing-the-connection-on-discord). +* **The bot replies "Sorry - something went wrong handling that message. Please try again."** + Likely cause: either the agent has a parameter the channel does not bind, e.g., a parameter added to the agent after the channel + was added, or the agent failed to answer, e.g., because the database it queries or the LLM service it uses could not be reached. + What to do: if a parameter is shown unbound in the channel's [Parameters](#the-parameters-tab) tab, bind it. If every parameter is + bound, the agent itself failed to produce the answer: verify that the app's database, and the LLM service behind the agent's AI + connection string, can be reached. The connection string can be tested as described in + [Dashboard: AI connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then send the bot a + question again. + + + + diff --git a/quill/channels/overview.mdx b/quill/channels/overview.mdx new file mode 100644 index 0000000000..7eda6ebcc3 --- /dev/null +++ b/quill/channels/overview.mdx @@ -0,0 +1,205 @@ +--- +title: "Channels: Overview" +sidebar_label: Overview +sidebar_position: 1 +description: "The channels of a Quill app: the channel types, how channels relate to agents, where channels are added and managed, the behavior and limitations all channels share, and the problems a channel's users may meet." +--- + +import Admonition from '@theme/Admonition'; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + +# Channels: Overview + + +* A **channel** carries the conversations between your users and an [agent](../overview.mdx#ai-agent) + of your app: user messages reach the agent through the channel, and replies return the same way. + Quill offers four channel types: a chat widget on your site, or a bot on Telegram, Slack, or Discord, reaching your users where + they already are. + +* Each channel type has an article of its own, describing how a channel of this type is added, and what the channel's users encounter. + This article covers what applies to channels of every type. + +* In this article: + * [Channel types](#channel-types) + * [Channels and agents](#channels-and-agents) + * [Adding and managing channels](#adding-and-managing-channels) + * [Binding agent parameters](#binding-agent-parameters) + * [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels) + * [Troubleshooting](#troubleshooting) + + + + + +Quill offers four channel types, each carrying the conversations through a different medium. +A channel's type is selected in the **Add channel** menu, described in [Adding and managing channels](#adding-and-managing-channels): + +* **Web widget** + A [chat widget](../overview.mdx#chat-widget) embedded in a page of your site, which your users open through an + [embed link](../getting-started/adding-a-chat-widget.mdx#generating-an-embed-link) placed on the page. + See [Getting started: Adding a chat widget](../getting-started/adding-a-chat-widget.mdx). +* **Telegram bot** + A bot that your users chat with on Telegram, created using @BotFather. + See [Channels: Telegram bot](../channels/telegram-bot.mdx). +* **Slack** + A Slack app that the members of a Slack workspace message directly. + Slack delivers the users' messages to your Quill deployment, so the deployment must be reachable from the internet. + See [Channels: Slack bot](../channels/slack-bot.mdx). +* **Discord** + A bot that the members of a Discord server message directly, created in the Discord Developer Portal. + See [Channels: Discord bot](../channels/discord-bot.mdx). + +| Channel type | Where your users chat | What you set up outside Quill | Quill reachable from the internet | +|---|---|---|---| +| Chat widget | On a page of your site | The embed snippet, in the page's HTML | Not required | +| Telegram bot | In Telegram | A bot, using @BotFather | Not required | +| Slack bot | In the Slack client | A Slack app, from Quill's manifest | Required | +| Discord bot | In Discord | A bot, in the Discord Developer Portal | Not required | + + + + + +A channel is added for one of the app's agents, and carries conversations to this agent alone. +The following holds for channels of every type: + +* **An agent can serve several channels at once.** + e.g., a chat widget on your site and a Telegram bot, both answered by the same agent. +* **A channel serves the agent it was added for.** + The agent cannot be changed afterwards. To serve another agent, add a new channel for this agent. +* **A bot serves one channel.** + A Telegram, Slack, or Discord bot can be connected to a single channel, in a single app of the deployment; connecting the bot + to another channel fails with an "already connected" error that names the app holding the bot. + To connect a bot to a different channel, delete the channel that holds the bot and add a new channel for the bot. + + + + + +Channels of every type are added and managed in the same places of Quill's management dashboard, described in +[Dashboard: Channels view](../dashboard/channels-view.mdx). + +* **Adding a channel starts with selecting the channel's type in the Add channel menu.** + The menu opens from the [Channels view](../dashboard/channels-view.mdx#adding-a-channel), from the + [channels list in the app's Overview](../dashboard/channels-view.mdx#an-additional-entry-point-the-channels-list-in-the-overview), + and at the last stage of the [Add agent wizard](../getting-started/adding-an-ai-agent.mdx#saving-the-agent), right after an + agent is created. + Selecting a type opens the type's form, described in the type's article. +* **Once added, a channel is managed from its details view.** + The [details view](../dashboard/channels-view.mdx#the-channel-s-details-view) opens from the channel's box in the Channels view. + The view's header carries the **Pause**/**Resume** button and the **⋮** menu with **Edit** and **Delete**, common to every + channel type, and the tabs below the header are specific to the channel type. + The tabs and the other type-specific parts of the view are described in the type's article. + + + + + +Some agents have **parameters**: values the agent's queries require, and that must come from the channel rather than be chosen by +the LLM, like the phone number of the customer whose orders the agent looks up. +Agent parameters are bound by the channel, and the source of a parameter's value depends on the channel type: + +* A **bot channel** binds each parameter when the channel is added, to a constant value or to a selected detail of each user who sends + the channel a message; the user details that can be bound differ by platform, and are listed in each bot's article. + A parameter left unbound, e.g., a parameter added to the agent after the channel was added, stops the bot from answering until + the parameter is bound in the **Parameters** tab of the + [channel's details view](../dashboard/channels-view.mdx#the-channel-s-details-view). +* A **chat widget** binds the parameters into each embed link + [when the link is generated](../getting-started/adding-a-chat-widget.mdx#setting-the-link-limits), and a link cannot be generated + until every parameter has a value. + + + + + +* **Users need no account with Quill.** + Who can reach a channel depends on the channel type: + * A chat widget is reached by whoever opens the page that holds its embed link. + * A Telegram bot is reached by any Telegram user who finds it. + * A Slack bot is reached by the members of the workspace the bot is installed in. + * A Discord bot is reached by the members of a server the bot is in. +* **The reply is streamed into the chat as the agent composes it.** +* **A long answer is delivered in several messages.** + On Telegram, Slack, and Discord, an answer that exceeds the platform's message limit is split across several messages. + In a chat widget the whole answer appears in a single reply. +* **Quill keeps the conversation's context, so a follow-up question is understood against the earlier exchange.** + The duration of a conversation depends on the channel type: + + | Channel type | The conversation lasts | A user can end it sooner | + |---|---|---| + | Chat widget | As long as the embed link that opened the widget | No | + | Telegram bot | Until midnight UTC | Yes, by sending `/clear` | + | Slack bot | Until midnight UTC | No | + | Discord bot | Until midnight UTC | No | + + * On Telegram, Slack, and Discord, the agent remembers a conversation for one day at most: at midnight UTC the agent forgets + the earlier exchange, and the next message is answered without the earlier context. The messages themselves remain in the + chat. + A Telegram user can make the agent forget sooner by sending `/clear`; Slack and Discord users cannot. + * In a chat widget, the conversation belongs to the embed link that opened the widget, and lasts as long as the link does: + everyone who opens the widget through the same link shares one conversation, and the conversation ends when the link + [expires, reaches its usage cap, or is revoked](../getting-started/adding-a-chat-widget.mdx#setting-the-link-limits). +* **Messages sent faster than the bot answers may go unanswered.** + On Telegram, Slack, and Discord, a message a user sends while the bot is still answering waits in a queue that Quill keeps for + this user. When the queue is full, further messages are not taken, and the bot sends one notice asking the user to send the + message again after the bot has replied. + A Telegram bot answers the queued messages together, as a single question; a Slack or Discord bot answers them one by one. +* **The bots answer text-only messages.** + On Telegram, a photo, a document, a sticker, or a voice message gets no reply. On Slack and Discord, a message that carries a file + gets the reply "I can only read text messages right now." +* **Pausing a channel takes it out of service; deleting a channel removes it.** + Both actions are described in the Channels view article, in + [Pausing and resuming a channel](../dashboard/channels-view.mdx#pausing-and-resuming-a-channel) and + [Deleting a channel](../dashboard/channels-view.mdx#deleting-a-channel). The conversations a deleted channel carried remain + available in the app's **Conversations** view. + What each action means for the channel's users, and for a bot on its platform, depends on the channel type and is described in + the type's article. +* **The messages a channel sends on its own have a default text set by Quill.** + The notices a chat widget shows when its embed link no longer works, and the replies a Slack or Discord bot sends on its own, like + "I can only read text messages right now.", cannot be changed. A Telegram bot's own messages can be replaced with texts of yours + in the **Bot messages** tab of the channel's details view. + + + + + +The symptoms below may be met by a channel's users, each with its likely cause and what to do about it. +The bots' messages are quoted in their default form; a Telegram bot with customized messages shows your texts instead. + +**In a chat with a Telegram, Slack, or Discord bot** + +* **The bot does not reply to a photo or a file, or replies "I can only read text messages right now."** + Likely cause: the bots answer text-only messages, as stated in + [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels), and the user's message may + carry a file, like an image or a document. A Telegram bot gives such a message no reply; a Slack or Discord bot answers with the + quoted notice. + What to do: advise the user to send the question as text. + A chat widget takes text only, so its users do not meet this symptom. +* **The bot replies "I'm still working through your earlier messages, so that one didn't make it. Please resend it once I've + replied."** + Likely cause: the user may have sent more messages than the bot's queue can hold while an answer was still being composed, as + stated in [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels). + What to do: advise the user to wait for the bot's reply, and then send the message again. + A chat widget takes no new message while the agent is still answering, so its users do not meet this symptom. + +**In a channel of any type** + +* **The agent answers from outdated information.** + Likely cause: one of the following may have happened. + * The app's internal database may not yet hold the latest changes from the source database. + What to do: check the state of the mirroring in the app's **Data source** view, which shows the number of recent writes and + reports any errors met while syncing. + * The conversation may hold earlier replies carrying data the agent had retrieved, that the agent now reads instead of + retrieving the data again. + What to do: a message that asks pointedly for the current data may make the agent retrieve it again. + In any case, the agent retrieves the data again once it forgets the earlier exchange, as described in + [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels). + +Symptoms specific to a channel type, including those seen in Quill's management dashboard and on the bot's platform, are listed in +the Troubleshooting section of the type's article: [Telegram bot](../channels/telegram-bot.mdx#troubleshooting), +[Slack bot](../channels/slack-bot.mdx#troubleshooting), and [Discord bot](../channels/discord-bot.mdx#troubleshooting). +The notices a chat widget shows when its embed link cannot be used are listed in +[Embed the Chat Widget](../developer-access/embed-the-chat-widget.mdx#when-a-link-or-widget-cannot-be-used). + + diff --git a/quill/channels/slack-bot.mdx b/quill/channels/slack-bot.mdx new file mode 100644 index 0000000000..8acd232b84 --- /dev/null +++ b/quill/channels/slack-bot.mdx @@ -0,0 +1,726 @@ +--- +title: "Channels: Slack bot" +sidebar_label: Slack bot +sidebar_position: 4 +description: "A Slack bot channel for a Quill app: creating a Slack bot from Quill's manifest, connecting it to the app and finishing the event subscription on Slack, what its users meet in a direct message with the bot, binding agent parameters, managing the channel, and the limitations of a Slack bot." +--- + +import Admonition from '@theme/Admonition'; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + +# Channels: Slack bot + + +* A Quill **Slack bot** channel lets your users converse with an [agent](../overview.mdx#ai-agent) + of your app in a direct message with a bot on Slack. + Users can message the bot from any Slack client, and the agent will answer from the app's internal database. + +* The bot is a **Slack app** installed in the Slack workspace the users belong to. + The bot is created at `api.slack.com/apps`, free of charge, from a manifest that Quill provides. + Slack issues two credentials that Quill needs in order to operate the bot: a **bot token** and a **signing secret**. + Slack delivers the users' messages to your Quill deployment, so the deployment must be reachable from the internet. + +* The channel is added from Quill's management dashboard, in a short form that asks you to select one of the agents you created + and provide the bot token and the signing secret. + One step then remains on Slack: subscribing the bot to the users' messages, so that Slack delivers these messages to Quill. + +* In this article: + * [Prerequisites](#prerequisites) + * [Creating a Slack bot from Quill's manifest](#creating-a-slack-bot-from-quill-s-manifest) + * [Connecting the bot to your app](#connecting-the-bot-to-your-app) + * [Opening the Add channel menu](#opening-the-add-channel-menu) + * [Filling in the channel form](#filling-in-the-channel-form) + * [Finishing the event subscription on Slack](#finishing-the-event-subscription-on-slack) + * [Checking the new channel](#checking-the-new-channel) + * [Chatting with the bot](#chatting-with-the-bot) + * [Starting a conversation](#starting-a-conversation) + * [Messages the bot does not answer](#messages-the-bot-does-not-answer) + * [Binding agent parameters](#binding-agent-parameters) + * [Choosing a source for each parameter](#choosing-a-source-for-each-parameter) + * [Binding a parameter to a constant value](#binding-a-parameter-to-a-constant-value) + * [Managing the channel](#managing-the-channel) + * [Pausing and deleting the channel](#pausing-and-deleting-the-channel) + * [Rotating the credentials](#rotating-the-credentials) + * [The tabs of the details view](#the-tabs-of-the-details-view) + * [Slack bot limitations](#slack-bot-limitations) + * [Troubleshooting](#troubleshooting) + + + + + +Before adding a Slack bot channel, make sure you have: + +* **An agent in your app.** + The channel is added for one of the app's agents, and this agent will answer the users who message the bot. + To add an agent, see [Getting started: Adding an AI agent](../getting-started/adding-an-ai-agent.mdx). +* **A Slack workspace your users are members of, and a Slack account in this workspace.** + The bot is created and installed while you are signed in to the workspace, and only workspace members can message the bot. + Once the channel is added, you can try the bot out from this account. + If you have no Slack workspace yet, you can [create one](https://slack.com/help/articles/206845317-Create-a-Slack-workspace). +* **Permission to install the bot in the workspace.** + A workspace's admins can + [require approval](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace) for the Slack apps that + members add to the workspace. In a workspace that requires approval, installing the bot only files a request with the admins, and the + bot can be connected to your app only after an admin approves the request. +* **A Quill deployment that can be reached from the internet.** + Slack delivers the users' messages to your Quill domain over HTTPS, so the machine that runs Quill must accept HTTPS connections + from the internet on port `443`, at the public IP address you gave at + [sign-up](../getting-started/signing-up.mdx#naming-your-quill-domain). + If the deployment cannot be reached from the internet, e.g., because it runs on your machine without a public IP address, + Slack cannot deliver the messages, and the bot will not answer. +* **Access to Slack from the machine that runs Quill.** + Quill validates the bot token and sends the bot's replies through Slack's API at `slack.com`, over HTTPS. + + + + + +The bot is created on Slack as a **Slack app**, from a **manifest**: a short text, provided by Quill, that describes the bot to +Slack, including the bot's name and the permissions the bot needs. +Creating the bot takes three steps: + +* Copying the manifest from Quill. +* Creating the bot from the manifest at `api.slack.com/apps`. +* Copying the two credentials that Slack issues for the bot: the **bot token** and the **signing secret**. + + + +### Copying the manifest from Quill + +Quill shows the manifest in the **New Slack channel** form that is used to add the channel. +To open the form: in Quill's management dashboard, open your app from **My apps**, click **Add channel** in the **Channels** +section of the app's **Overview**, and select **Slack**. +When the form opens, expand **No Slack app yet?** at the top. + +![The manifest in the New Slack channel form](./assets/slack-bot_manifest.png) + +1. **Create the app from this manifest** + The manifest, written in YAML, a text format that Slack accepts. + Click the copy icon at the top right of the manifest to copy it. +2. **Install it and copy the credentials** + A reminder of the pages on Slack that show the bot token and the signing secret, described in + [Collecting the bot token and the signing secret](#collecting-the-bot-token-and-the-signing-secret). + +You can leave the form open while you create the bot on Slack, and return to complete the form when Slack provides you with the +bot token and the signing secret. + + + +The manifest lists the permissions the bot needs, and nothing else: reading the direct messages sent to the bot (`im:history`), +posting the replies (`chat:write`), and reading the users' profiles and email addresses (`users:read` and `users:read.email`). +The bot reads a user's profile only when an agent parameter is bound to the email address of the user who sent the message, as +described in [Binding agent parameters](#binding-agent-parameters). + + + + + + + +### Creating the bot on Slack + +Open [api.slack.com/apps](https://api.slack.com/apps), sign in with your Slack account, and click **Create New App**: + +![Create new app](./assets/slack-bot_create-app.png) + +1. **From a manifest** + Select this option: the bot is created from the manifest you copied. +2. **Continue** + Click to open the **Create from a manifest** form. + +--- + +![Create from a manifest](./assets/slack-bot_paste-manifest.png) + +1. **YAML** + Select the YAML tab, the format of Quill's manifest. +2. **Manifest** + Paste the manifest you copied from Quill, replacing the editor's content. + The manifest names the bot `Quill`, in its `name` and `display_name` lines. To give the bot a different name + (e.g., if you create a second bot and the first is already named "Quill"), edit both lines before clicking **Next**. +3. **Workspace** + Select the workspace your users belong to. + The workspace cannot be changed after the bot is created. +4. **Next** + Click to proceed. + On the next page, Slack will show a summary of the bot as described by the manifest. + Click **Create and Install** under the summary, and then **Allow** when Slack asks you to permit the bot's installation in + the workspace. + + + +In a workspace that requires an admin's approval for the Slack apps that members add (see [Prerequisites](#prerequisites)), +installing the bot only sends a request to the admins; the bot is installed once an admin approves the request. + + + + + + + +### Collecting the bot token and the signing secret + +#### Collecting the bot token: + +Once the bot is installed, Slack shows a page that announces the bot is ready, headed **Quill is ready!** for a bot named Quill, +with a collapsed **Your app credentials** card. Expand the card: + +![Your app credentials](./assets/slack-bot_app-credentials.png) + +Copy the **Bot token**: this token is the first of the two credentials you need to collect. +Note that this card also shows an **App token**, which Quill does not use and you do not need to copy. + + + +The bot token can also be copied later, from the bot's settings on Slack: select **OAuth & Permissions** in the bot settings +sidebar, and copy the **Bot User OAuth Token**: + +![The Bot User OAuth Token](./assets/slack-bot_bot-token.png) + + + +--- + +#### Collecting the signing secret: + +To find the **signing secret**, click **Go to App Settings** at the bottom of the **Quill is ready!** page. +Open the **Basic Information** page from the bot settings sidebar, and find **Signing Secret** in the **App Credentials** section: + +![The signing secret](./assets/slack-bot_signing-secret.png) + +Click **Show** to reveal the secret, and copy it. + + + +Handle the bot token and the signing secret as secrets: anyone holding the bot token can read the messages users send to the bot +and answer in the bot's name, and anyone holding the signing secret can send messages to Quill in Slack's name. + +* If the signing secret leaks, click **Regenerate** next to the secret to recreate it. +* If the bot token leaks, have Slack issue a new token by clicking **Revoke All OAuth Tokens** on the OAuth & Permissions page + and reinstalling the bot from the same page. +* In either case, enter the new credential in the channel as described in [Rotating the credentials](#rotating-the-credentials). + + + + + + + + + +To connect the bot to the app, add a **Slack** channel for one of the app's agents. +The channel is added in Quill's management dashboard, and one last step is then taken on Slack, so that Slack delivers the users' +messages to the channel. + + + +### Opening the Add channel menu + +In Quill's management dashboard, open your app from **My apps**. The app's **Overview** holds a **Channels** section: click the +section's **Add channel** button to open the menu of channel types, and select **Slack**. + +![The Add channel menu](./assets/slack-bot_add-channel-menu.png) + + + +The [Add agent wizard](../getting-started/adding-an-ai-agent.mdx#saving-the-agent) ends on an **Add a channel** stage that shows +the same Channels section, so a bot can also be connected right after its agent is created. +The form then has no **Agent** field: the channel is added for the agent the wizard just created. + + + + + + + +### Filling in the channel form + +Selecting **Slack** opens the **New Slack channel** form. + +![New Slack channel](./assets/slack-bot_new-channel.png) + +1. **No Slack app yet?** + Click to expand a block that holds the manifest and a reminder of the steps on Slack, described in + [Creating a Slack bot from Quill's manifest](#creating-a-slack-bot-from-quill-s-manifest). +2. **Agent** + Select the agent that will answer the bot's users. The list holds the app's agents. + + + + When the form is opened from the [Add agent wizard](../getting-started/adding-an-ai-agent.mdx#saving-the-agent), the channel is + added for the newly created agent and this field is absent. + + + +3. **Bot token** + Paste the bot token you collected on Slack. The field shows the token as dots; click the eye icon to reveal it. + Quill validates the token with Slack when the channel is added, and never displays it again afterwards. +4. **Signing secret** + Paste the signing secret you collected on Slack. The field shows the secret as dots; click the eye icon to reveal it. + Quill uses the secret to verify that every message delivered to the channel really comes from Slack, and never displays the + secret again afterwards. +5. **Channel name** (optional) + If you leave this field empty, Quill will name the channel after the bot's username on Slack, e.g., `quill`. +6. **Connect bot** + Click to add the channel. If Slack rejects the token, or the bot is already connected to another channel, the form will + report the error and no channel will be added. + + + +When the selected agent has parameters, a **Parameters** section appears below the channel name, described in +[Binding agent parameters](#binding-agent-parameters). + + + + + + + +### Finishing the event subscription on Slack + +Once the channel is added, the form is replaced by a **Bot connected** sheet. The sheet shows the state of the connection, and +lists the steps that remain on Slack, where the bot has to be subscribed to the users' messages: + +![The Bot connected sheet](./assets/slack-bot_bot-connected.png) + +1. **Northwind Traders** + The workspace the bot is installed in, the bot's user ID on Slack, and the state of the connection: + * **Token valid**: Slack accepted the bot token. + * **Waiting for the first message...**: no user has messaged the bot yet. +2. **Open Event Subscriptions** + The first step on Slack: opening the bot's Event Subscriptions page, described below. +3. **Paste the request URL** + The address Slack has to deliver the users' messages to, unique to this channel. + Click the copy icon next to the URL to copy it, for the second step on Slack. +4. **Subscribe to bot events** + The third step on Slack: adding the `message.im` event, described below. +5. **Test it** + The last step: sending the bot a message in the Slack client, described in [Starting a conversation](#starting-a-conversation). +6. **Done** + Click to close the sheet once the steps on Slack are done. + The connection state and the steps remain available in the channel's [Connect](#the-connect-tab) tab. + +The above steps are performed in the bot's settings on Slack. Open [api.slack.com/apps](https://api.slack.com/apps) in your +browser, select the bot in the list of apps, and select **Event Subscriptions** in the sidebar on the left. The +**Event Subscriptions** page opens: + +![Event Subscriptions](./assets/slack-bot_event-subscriptions.png) + +1. **Enable Events** + Turn the toggle on, so that Slack can notify Quill of events like a direct message sent to the bot. +2. **Request URL** + Paste the request URL shown in the **Paste the request URL** step of Quill's **Bot connected** sheet, depicted above. + Slack verifies the URL at once and marks the field **Verified**. If the field is not marked Verified, see + [Troubleshooting](#troubleshooting). +3. **message.im** + Scroll down to the **Subscribe to bot events** section, click **Add Bot User Event**, and select `message.im`, the event Slack + raises when a user sends the bot a direct message. +4. **Save Changes** + Click to save the subscription. Slack will then deliver the direct messages that users send the bot to Quill. + + + + + +### Checking the new channel + +Back in Quill, you can now see the new channel in the Overview's **Channels** section: + +![The new channel](./assets/slack-bot_channel-created.png) + +1. **Channel name** + The channel's name, with the name of the bot's Slack workspace beneath it. +2. **Status** + **Active**: the channel is enabled; **Disabled**: the channel is paused. + Pausing and resuming a channel is described in + [Dashboard: Channels view](../dashboard/channels-view.mdx#pausing-and-resuming-a-channel). +3. **Active links** + Embed links belong to web widget channels; a Slack bot channel has none, so the column shows a dash. + + + + + + + +Once the channel is connected, every member of the workspace can message the bot. A user who opens a direct message with the bot +can ask questions, and the agent will answer from the app's internal database. +The users need no account with Quill and no instructions. This section describes the chat as an end user experiences it, so that +you know what to expect and what to tell your users. + + + +### Starting a conversation + +In the Slack client, a user opens the bot from the **Agents and apps** section of the sidebar, or by searching for the bot's name, +and types a question in the bot's **Messages** tab. + +![A conversation with the bot](./assets/slack-bot_conversation.png) + +The following holds for every conversation with the bot: + +* **Messages a user sends while the bot is still answering wait their turn.** + The bot answers the waiting messages one by one, as long as the queue Quill keeps for this user has room. +* **The bot has no commands.** + Every message the bot receives is handled as a question. + +The behavior common to all channels, like the streaming of the reply and the conversation's context, is described in the channels +overview, in [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels). + + + + + +### Messages the bot does not answer + +The bot answers text-only messages. A message that carries a file, like an image or a document, gets the reply "I can only read text +messages right now." A message with no text at all gets no reply. +The bot answers in direct messages only. A message posted in a Slack channel, such as #general, or in a group direct message with +several people, gets no reply, even if the message mentions the bot. + + + + + + + +Some agents have **parameters**: values the agent's queries require, and that must come from the channel rather than be chosen +by the LLM, e.g., the ID of the customer whose orders the agent looks up. +When you add a Slack channel for such an agent, the form asks you to bind each parameter to a source, which can be: + +* A constant value that you type, which is then the same for all bot users. +* A detail of the Slack user who is messaging the bot: the user's Slack user ID or email address. + The parameter then carries a different value for each user, so that each user is answered about this user's own data. + + + +### Choosing a source for each parameter + +The **New Slack channel** form presents a **Parameters** section with one row per parameter, labeled with the parameter's name, +e.g., `customerPhone`. +In each parameter row, select where the parameter's value comes from: + +![Choosing a source for a parameter](./assets/slack-bot_parameter-mapping.png) + +1. The parameter's source + Select the source from the list: + * **Constant value** + A value that you type in the form. Quill will then pass this value to the agent with every message, from every user. + e.g., the phone number of the customer whose workspace the bot is installed in. + * **Sender Slack user ID** + The Slack user ID of the user who sent the message, e.g., `U0BV4AE3M5Z`. + * **Sender email** + The email address on the Slack profile of the user who sent the message. + A user whose profile has no email address gets the reply "Sorry - something went wrong handling that message. Please try + again." + + The user ID and email sources tie the answers to the Slack user, and suit an app whose data holds the users' Slack IDs or + email addresses. +2. **Value** + The value to bind when the source is **Constant value**. + +The bindings can be changed later in the channel's **Parameters** tab, described in +[The Parameters tab](#the-parameters-tab). + + + + + +### Binding a parameter to a constant value + +In this example, the app's **Order Lookup Assistant** agent has a `customerPhone` parameter: the agent's queries find a customer's +orders by the customer's phone number. +The bot, named `Northwind Orders`, serves the Slack workspace of a single customer, where every member belongs to this customer, so +the channel binds the parameter to a constant value: the customer's phone number. The agent then answers every user of this bot +about this customer's orders: + +![The orders of the bound customer](./assets/slack-bot_orders-answer.png) + +A constant value suits a channel whose users all share the value, like the bot above. + + + + + + + +Once added, the channel is managed from its details view, described in +[Dashboard: Channels view](../dashboard/channels-view.mdx#the-channel-s-details-view): the view's header carries the +**Pause**/**Resume** button and the **⋮** menu with **Edit** and **Delete**, common to every channel type, and the tabs below the +header are specific to the channel type. + +To open the details view, open the app from **My apps** in Quill's management dashboard, select **Channels** in the sidebar, and +click the channel's box: + +![The channel's box in the Channels view](./assets/slack-bot_channel-box.png) + +--- + + + +### Pausing and deleting the channel + +To pause or resume the channel, click **Pause**/**Resume** in the header; to delete it, select **Delete** in the header's **⋮** menu. + +![Pause and the channel's menu in the details view's header](./assets/slack-bot_channel-menu.png) + +Both actions are explained in the Channels view article, in +[Pausing and resuming a channel](../dashboard/channels-view.mdx#pausing-and-resuming-a-channel) and +[Deleting a channel](../dashboard/channels-view.mdx#deleting-a-channel). Each of them also has a Slack side, explained here: + +* A paused bot stops answering. Nothing changes on Slack: the bot remains installed, and Slack keeps delivering the users' + messages, which Quill discards. + Messages users send while the channel is paused will not be answered when the channel is resumed. +* A deleted channel stops the bot, but the bot itself remains installed in the workspace, and its credentials can be used to + connect it again, in a new channel. + The new channel has a new request URL, which you have to paste into the bot's **Event Subscriptions** page on Slack in place of + the old one, as described in [Finishing the event subscription on Slack](#finishing-the-event-subscription-on-slack). + + + + + +### Rotating the credentials + +To replace the bot token, the signing secret, or both, select **Edit** in the header's **⋮** menu, and rotate the credentials in the +**Edit channel** form. +The channel has to hold the credentials that Slack currently issues for the bot: + +* If you revoke and reissue the bot token on Slack, the bot will stop answering until the channel holds the new token. +* If you regenerate the signing secret on Slack, Quill will reject every delivery until the channel holds the new secret. + +![Rotating the credentials](./assets/slack-bot_rotate-credentials.png) + +1. **Rotate credentials** + Turn the toggle on to replace one credential or both. +2. **New bot token** + Paste the new bot token, or leave the field empty to keep the current token. + Quill validates the token with Slack before saving it; the token has to belong to the same workspace and bot as the current one. +3. **New signing secret** + Paste the new signing secret, or leave the field empty to keep the current secret. +4. **Save changes** + Click to save. Quill will use the new credentials from now on. + + + + + +### The tabs of the details view + +The details view presents an informative **Connect** tab, and a **Parameters** tab that allows you to change the bindings of the +agent's parameters: + +--- + +#### The Connect tab + +The **Connect** tab shows the state of the bot's connection to Slack, and keeps the channel's request URL and the steps taken on +Slack when the channel was added, in case they have to be repeated. + +![The Connect tab](./assets/slack-bot_channel-details.png) + +1. **Connect** + Open the Connect tab. +2. **Connection** + The workspace the bot is installed in, the bot's user ID on Slack, and the state of the connection: + * **Token valid**, **Token rejected**, or **Token status unknown** + Whether Slack still accepts the bot token. While the tab is open, Quill re-checks the token with Slack every few minutes; + **Token status unknown** is shown when Slack could not be reached for the check. + * **Last message** + The time of the last message a user sent to the bot, or **Waiting for the first message...** if no user has messaged the bot + yet. + * **A delivery failed signature verification** + A red alert shown below the **Connection** card when Slack delivered a message that Quill could not verify, most likely + because the channel holds an outdated signing secret. + The alert disappears once a delivery is verified again. + * **The bot couldn't deliver a reply** + A red alert shown below the **Connection** card when Slack refused the bot's last reply, quoting Slack's error and the time + of the failure. The alert remains after the problem is solved, until Quill is restarted. +3. **Slack event subscription** + The steps taken on Slack when the channel was added, with the channel's request URL, as shown in the **Bot connected** sheet + at the time (see [Finishing the event subscription on Slack](#finishing-the-event-subscription-on-slack)). + +When the channel is paused, the tab opens with an alert saying so. + +--- + +#### The Parameters tab + +The **Parameters** tab lists the agent's parameters and the source each of them is currently bound to, as set when the channel was +added, and lets you change the bindings. +A parameter that is added to the [agent configuration](../getting-started/adding-an-ai-agent.mdx#modifying-the-agent-configuration) +after the channel was added appears in this tab unbound, and the bot will not answer until the parameter is bound: users get the +reply "Sorry - something went wrong handling that message. Please try again." + +![The Parameters tab](./assets/slack-bot_parameters.png) + +1. **Parameters** + Open the Parameters tab. +2. **customerPhone** + The example agent has one parameter, `customerPhone`, bound to a constant value: the phone number of the customer the bot + serves (see [Binding agent parameters](#binding-agent-parameters)). + Each row shows a parameter's name, the source the parameter is bound to, and, for a constant, the bound value. +3. **Edit** + Click to make the bindings editable, and click **Save** when done. + + + + + + + +A Slack bot channel is designed to answer, in a direct message, any member of the workspace the bot is installed in. +The limits below follow this design and Slack's own rules. None of them can be changed in the channel's settings. + +* **Any member of the workspace can chat with the bot.** + You select the workspace the bot will serve when you create the bot on Slack, but within this workspace the channel cannot + select the users that will have access to the bot. Agent parameters bound to the Slack user can tie the answers to this user's + own data, but cannot turn anyone away. +* **The bot answers in direct messages only.** + A message posted in a Slack channel, such as #general, or in a group direct message with several people, gets no reply, even if + the message mentions the bot. +* **The bot answers text-only messages.** + In a direct message, a message that carries a file, e.g., an image or a document, gets the reply "I can only read text messages + right now." +* **The bot answers only while the deployment can be reached from the internet.** + Slack delivers each message to the channel's request URL as the user sends it. If the deployment cannot be reached at that + moment, the message does not reach Quill. Slack may retry the delivery a few times shortly afterwards; a message that no retry + delivers is never answered. +* **The agent remembers a conversation for one day at most.** + A user cannot make the agent forget sooner. + See [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels) + in the channels overview. +* **Messages sent faster than the bot answers may go unanswered.** + See [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels) + in the channels overview. +* **The bot's own messages cannot be customized.** + See [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels) + in the channels overview. + + + + + + + +Symptoms met by the users of every bot type, not just of a Slack bot, are listed in the channels overview, in +[Troubleshooting](../channels/overview.mdx#troubleshooting). + + + +The symptoms below are shown by a Slack bot channel when something goes wrong, each with its likely cause and what to do about it. +The first symptoms are seen in Quill's management dashboard: in the channel form and in the channel's [Connect](#the-connect-tab) +tab. One symptom is seen in the bot's settings on Slack, on the **Event Subscriptions** page. The rest are encountered by the bot's +users in the Slack client. + + + +### In the dashboard + +* **The `Bot token` field reports "The bot token starts with xoxb- (not a user or app-level token)".** + Likely cause: the pasted token may be the **App token** (`xapp-...`) shown next to the bot token on the **Quill is ready!** page + on Slack. + What to do: copy the **Bot User OAuth Token** from the bot's **OAuth & Permissions** page on Slack, as described in + [Collecting the bot token and the signing secret](#collecting-the-bot-token-and-the-signing-secret), and paste it in the field. +* **Clicking `Connect bot` fails with "slack rejected the bot token".** + Likely cause: the token pasted in the form may be incomplete or mistyped, or it may have been revoked on Slack since it was + copied. + What to do: copy the **Bot User OAuth Token** from the bot's OAuth & Permissions page on Slack again, and paste it in the form's + [Bot token](#filling-in-the-channel-form) field. If the bot was uninstalled, reinstall it from the same page first. +* **Clicking `Connect bot` fails with "slack is rate-limiting the token check" or "could not reach the Slack API".** + Likely cause: Slack may be limiting Quill's requests for a moment, or the machine that runs Quill may be unable to reach + `slack.com`. + What to do: wait a minute or two and try again. If the failure persists, verify that the machine that runs Quill can open HTTPS + connections to `slack.com`, as described in [Prerequisites](#prerequisites). +* **Clicking `Connect bot` fails with "Slack bot ... is already connected".** + Likely cause: the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve + only one channel. When the channel is in another app, the message names that app. + What to do: delete the channel that holds the bot, in this app or in the app the message names, as described in + [Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another bot from the manifest, with a name of its + own, as described in [Creating a Slack bot from Quill's manifest](#creating-a-slack-bot-from-quill-s-manifest), and paste the new + bot's credentials in this form instead. +* **The `Connect` tab shows "Token rejected", and the bot does not answer.** + Likely cause: the bot's token may have been revoked on Slack, by **Revoke All OAuth Tokens** on its OAuth & Permissions page or by + uninstalling the bot from the workspace. + The users' messages still reach Quill, but the bot cannot post its replies, so the messages are not answered, and are not answered + later. Quill re-checks the token every few minutes, so the badge may turn red a few minutes after the revocation. The tab then + also shows the red alert "The bot couldn't deliver a reply" under the connection card, which remains until Quill is restarted. + + ![The Connect tab with a rejected token](./assets/slack-bot_token-rejected.png) + + What to do: reinstall the bot from its OAuth & Permissions page on Slack, copy the new **Bot User OAuth Token** the page then + shows, and enter it in the channel, as described in [Rotating the credentials](#rotating-the-credentials). +* **The `Connect` tab shows a red alert, "A delivery failed signature verification", under the connection card.** + Likely cause: the signing secret held by the channel may differ from the bot's: the secret may have been regenerated on Slack, + or mistyped when the channel was added. + Quill rejects the deliveries it cannot verify, so the users' messages are not answered until the secrets match. + + ![The Connect tab with a failed signature verification](./assets/slack-bot_signature-failed.png) + + What to do: copy the **Signing Secret** from the **App Credentials** section of the bot's **Basic Information** page on Slack, and + enter it in the channel, as described in [Rotating the credentials](#rotating-the-credentials). The alert disappears once a + delivery is verified. +* **The `Connect` tab shows "Token valid", but "Last message" does not change when users message the bot, and the bot does not + answer.** + Likely cause: Slack may not be delivering the messages to Quill: the event subscription may be incomplete, the request URL may + have failed Slack's verification, or the deployment may no longer be reachable from the internet. + What to do: open the bot's **Event Subscriptions** page on Slack and check that **Enable Events** is on, that the **Request URL** + is marked **Verified**, that `message.im` is listed under **Subscribe to bot events**, and that the changes were saved, as + described in [Finishing the event subscription on Slack](#finishing-the-event-subscription-on-slack). If the URL is not verified, + see the "Your URL didn't respond." entry below. +* **The `Connect` tab opens with "This channel is paused, so the bot isn't answering right now."** + Likely cause: the channel was paused, using **Pause** in the header of its details view. + Messages users send while the channel is paused do not reach the agent and are not answered later. + What to do: resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). + + + + + +### In the bot's settings on Slack + +* **The `Request URL` field of the `Event Subscriptions` page shows "Your URL didn't respond."** + Likely cause: Slack may be unable to reach the deployment at the URL: Quill may be stopped, the machine that runs Quill may not + accept connections from the internet, or the URL may have been pasted incompletely. A channel that was deleted no longer answers + at its URL either. + + ![The Request URL field after a failed verification](./assets/slack-bot_url-not-responding.png) + + What to do: make sure that Quill is running, and that the machine that runs it accepts HTTPS connections from the internet, as + described in [Prerequisites](#prerequisites). Then paste the URL again from the channel's [Connect](#the-connect-tab) tab, and + click **Retry**. If the channel was deleted, add a channel for the bot again and paste the new channel's request URL instead. + + + + + +### In the Slack client + +* **A user cannot find the bot.** + Likely cause: the user may not be a member of the workspace the bot is installed in, or the bot may not be listed in the user's + sidebar. + What to do: if the user is not a member of the workspace, have a workspace admin invite the user. Then advise the user to search + for the bot's name in the Slack client's search box, and to write in the bot's **Messages** tab, as described in + [Starting a conversation](#starting-a-conversation). +* **The bot does not reply to a message posted in a Slack channel or in a group direct message.** + Likely cause: the bot reads only the direct messages sent to it. A message posted in a Slack channel, such as #general, or in a + group direct message with several people, does not reach the bot, even if the message mentions the bot. + What to do: advise the user to send the question in a direct message with the bot. +* **The bot replies "Sorry - something went wrong handling that message. Please try again."** + Likely cause: one of the following may have happened. + * The agent has a parameter the channel does not bind, e.g., a parameter added to the agent after the channel was added. + * A parameter is bound to **Sender email**, and the Slack profile of the user who sent the message carries no email address. + * The agent failed to answer, e.g., because the database it queries or the LLM service it uses could not be reached. + + What to do: if a parameter is shown unbound in the channel's [Parameters](#the-parameters-tab) tab, bind it. If a parameter is + bound to **Sender email**, ask the user to check that the Slack profile shows an email address. If every parameter is bound, the + agent itself most likely failed to produce the answer: verify that the app's database, and the LLM service behind the agent's AI + connection string, can be reached. The connection string can be tested as described in + [Dashboard: AI connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then send the bot a + question again. + + + + diff --git a/quill/channels/telegram-bot.mdx b/quill/channels/telegram-bot.mdx new file mode 100644 index 0000000000..2dc5c05dfa --- /dev/null +++ b/quill/channels/telegram-bot.mdx @@ -0,0 +1,565 @@ +--- +title: "Channels: Telegram bot" +sidebar_label: Telegram bot +sidebar_position: 2 +description: "A Telegram bot channel for a Quill app: creating the bot with @BotFather, connecting it to the app, what its users meet in the chat, binding agent parameters to the Telegram user, managing the channel, and the limitations of a Telegram bot." +--- + +import Admonition from '@theme/Admonition'; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + +# Channels: Telegram bot + + +* A Quill **Telegram bot** channel lets your users converse with an [agent](../overview.mdx#ai-agent) + of your app in a private chat with a bot on Telegram. + Users can chat with the bot using any Telegram client, and the agent will answer from the app's internal database. + +* The bot is created using **@BotFather**, an official Telegram bot that creates other bots, free of charge. + @BotFather also issues the **bot token**, a credential that Quill needs to operate the bot. + Quill collects the incoming messages from Telegram, so the deployment needs no public address or open inbound port. + +* The channel is added from Quill's management dashboard, using one short form that asks you to select one of the agents you + created and provide the bot token and an optional channel name. + * If the selected agent has parameters, the form also asks you to settle each parameter's value. + You can either provide a fixed value, or take the value from the Telegram user the bot is chatting with, e.g., the user's + phone number. + * When an agent parameter takes the user's phone number, the bot will ask each user it chats with to share the number before + answering the user's first question. + +* In this article: + * [Prerequisites](#prerequisites) + * [Creating a bot using @BotFather](#creating-a-bot-using-botfather) + * [Connecting the bot to your app](#connecting-the-bot-to-your-app) + * [Opening the Add channel menu](#opening-the-add-channel-menu) + * [Filling in the channel form](#filling-in-the-channel-form) + * [Checking the new channel](#checking-the-new-channel) + * [Chatting with the bot](#chatting-with-the-bot) + * [Starting a conversation](#starting-a-conversation) + * [Clearing the conversation](#clearing-the-conversation) + * [Messages the bot ignores](#messages-the-bot-ignores) + * [Binding agent parameters](#binding-agent-parameters) + * [Choosing a source for each parameter](#choosing-a-source-for-each-parameter) + * [Sharing the phone number](#sharing-the-phone-number) + * [Returning users](#returning-users) + * [Managing the channel](#managing-the-channel) + * [Pausing and deleting the channel](#pausing-and-deleting-the-channel) + * [Rotating the bot token](#rotating-the-bot-token) + * [The tabs of the details view](#the-tabs-of-the-details-view) + * [Telegram bot limitations](#telegram-bot-limitations) + * [Troubleshooting](#troubleshooting) + + + + + +Before adding a Telegram bot channel, make sure you have: + +* **An agent in your app.** + The channel is added for one of the app's agents, and this agent will answer the users who chat with the bot. + To add an agent, see [Getting started: Adding an AI agent](../getting-started/adding-an-ai-agent.mdx). +* **A Telegram account.** + The bot is created in a private chat with @BotFather from your [Telegram account](https://telegram.org). + Once the channel is added, you can try the bot out from the same account. +* **Access to Telegram from the machine running Quill.** + The only connection the bot needs is the one Quill opens to Telegram's servers, `api.telegram.org`, over HTTPS. + The users' messages travel to Quill over this connection too, so a deployment that cannot be reached from the internet, like + one running on your machine, can still operate a bot. + + + + + +To create the bot, open a chat with [**@BotFather**](https://t.me/BotFather) in your Telegram client and send this command: `/newbot` +The genuine @BotFather carries Telegram's blue verification mark next to its name. +@BotFather then asks for two details, one at a time: + +* A **name** for the bot. + e.g., `Northwind Traders Catalog` + This name will appear at the top of users' chats with the bot. +* A **username** for the bot. + e.g., `NorthwindCatalogBot` + The username has to be unique across Telegram and end in `bot`. + The username is the bot's address on Telegram: users find the bot by it, and Quill names the channel after it (unless you + name the channel yourself). + +![Creating the bot with @BotFather](./assets/telegram-bot_botfather-newbot.png) + +@BotFather's final message carries the **bot token** (the string after "Use this token to access the HTTP API"). +Copy the token: you will need to hand it to Quill in the next section, +[Connecting the bot to your app](#connecting-the-bot-to-your-app). + + + +The bot token is a secret: anyone holding it can control the bot, read the messages users send to it, and answer in the bot's name. +If the token ever leaks, have @BotFather issue a new token and enter it in the channel as described in +[Rotating the bot token](#rotating-the-bot-token). + + + + + + + +To connect the bot to the app, add a **Telegram bot** channel for one of the app's agents. + +* The channel is added in a short form that asks you to provide the bot token issued by @BotFather, and to select the agent that + will answer the users. +* Once the channel is added, Quill starts operating the bot, and messages sent to the bot will reach the agent. + + + +### Opening the Add channel menu + +In Quill's management dashboard, open the app from **My apps**. The app's **Overview** holds a **Channels** section: click the +section's **Add channel** button to open the menu of channel types, and select **Telegram bot**. + +![The Add channel menu](./assets/telegram-bot_add-channel-menu.png) + + + +The [Add agent wizard](../getting-started/adding-an-ai-agent.mdx#saving-the-agent) ends on an **Add a channel** stage that shows +the same Channels section, so a bot can also be connected right after its agent is created. +The form then has no **Agent** field: the channel is added for the agent the wizard just created. + + + + + + + +### Filling in the channel form + +Selecting **Telegram bot** opens the **New Telegram bot channel** form. + +![New Telegram bot channel](./assets/telegram-bot_new-channel.png) + +1. **Agent** + Select the agent that will answer the bot's users. The list holds the app's agents. + + + + When the form is opened from the [Add agent wizard](../getting-started/adding-an-ai-agent.mdx#saving-the-agent), the channel is + added for the newly created agent and this field is absent. + + + +2. **Bot token** + Paste the token you received from @BotFather. The field shows the token as dots; click the eye icon to reveal it. + Quill validates the token with Telegram when the channel is added, and never displays it again afterwards. +3. **Channel name** + This field is optional. If you leave it empty, Quill will name the channel after the bot's username, e.g., `@NorthwindCatalogBot`. +4. **Connect bot** + Click to add the channel. If Telegram rejects the token, or the bot is already connected to another channel, the form will + report the error and no channel will be added. + + + + + +### Checking the new channel + +The new channel appears in the **Channels** section: + +![The new channel](./assets/telegram-bot_channel-created.png) + +1. **Channel name** + The channel's name, with the bot's username beneath it. + In this example the name was left empty, so the channel is named after the username. +2. **Status** + **Active**: the channel is enabled; **Disabled**: the channel is paused. + Pausing and resuming a channel is described in + [Dashboard: Channels view](../dashboard/channels-view.mdx#pausing-and-resuming-a-channel). +3. **Active links** + Embed links belong to web widget channels; a Telegram bot channel has none, so the column shows a dash. + + + + + + + +Once the channel is added, the bot is reachable by anyone on Telegram. A user who finds the bot, by its username or through a +search, can open a private chat with it and ask questions, and the agent will answer from the app's internal database. +The users need no account with Quill and no instructions. This section describes the chat as an end user experiences it, so that +you know what to expect and what to tell your users. + + + +### Starting a conversation + +A first chat with a bot opens in Telegram with a **Start** button, and clicking the button sends the `/start` command. +The bot answers with a greeting, and from then on every message the user sends is a question to the agent. + +![A conversation with the bot](./assets/telegram-bot_conversation.png) + +Messages a user sends while the bot is still answering are gathered and answered together, as a single question, as long as the +queue Quill keeps for this chat has room. +The bot recognizes only two Telegram commands: `/start` and `/clear`. Any other string is handled as text, even if preceded by `/`. +The behavior common to all channels, like the streaming of the reply and the conversation's context, is described in the channels +overview, in [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels). + + + + + +### Clearing the conversation + +The agent remembers a conversation for one day at most: at midnight UTC the agent forgets the earlier exchange, and the next +message is answered without the earlier context. +A user can also start afresh at any moment by sending `/clear`. The bot confirms, and the next message opens a new conversation. + +![Clearing the conversation](./assets/telegram-bot_clear.png) + +In the chat above, the question answered before `/clear` can no longer be answered after it, since the list the question referred to +is no longer part of the conversation. +Clearing also deletes the conversation from the app's **Conversations** view in the management dashboard. + + + + + +### Messages the bot ignores + +The bot answers text-only messages. A photo, a document, a sticker, or a voice message gets no reply. +A contact card is accepted only when an agent parameter takes the user's phone number, as described in +[Binding agent parameters](#binding-agent-parameters); otherwise the card is ignored as well. +The bot answers in private chats only. Added to a group, the bot posts one refusal and then stays silent in the group. + + + + + + + +Some agents have **parameters**: values the agent's queries require, and that must come from the channel rather than be chosen by +the LLM. e.g., the phone number of the customer whose orders the agent looks up. +When you add a Telegram bot channel for such an agent, the form asks you to bind each parameter to a source, which can be: + +* A constant value that you type, which is then the same for all bot users. +* A detail of the Telegram user who is messaging the bot: the user's Telegram id, username, or phone number. + The parameter then carries a different value for each user, so that each user is answered about this user's own data. + +This section describes the sources a parameter can be bound to, and what a user meets when the bot needs the user's phone number. + + + +### Choosing a source for each parameter + +When the selected agent has parameters, the channel form presents a **Parameters** section with one row per parameter, labeled +with the parameter's name, e.g., `customerPhone`. +In each parameter row, select where the parameter's value comes from: + +![Binding a parameter](./assets/telegram-bot_parameter-mapping.png) + +1. **The parameter's source** + Select the source from the list: + * **Constant value** + A value that you type in the form. Quill will then pass this value to the agent with every message, from every user. e.g., to + mark every user of this bot as a member of a specific customer group. + * **Telegram user id** + The numeric id of the Telegram user who sent the message. + * **Telegram username** + The Telegram username of the user who sent the message, without the `@`. A user who has no username set will be asked to add + one before the agent answers. + * **Telegram phone number** + The phone number of the user's Telegram account. The user will be asked to share the number once, as described in + [Sharing the phone number](#sharing-the-phone-number). + + The user id, username, and phone number sources tie the answers to the Telegram user, and suit an app whose data holds these + details. +2. **Value** + The value to bind when the source is **Constant value**. + +In this article's example, `customerPhone` is bound to **Telegram phone number**, as the following sections show. +The bindings can be changed later in the channel's **Parameters** tab, described in the +[Parameters](#the-parameters-tab) tab section of Managing the channel. + + + + + +### Sharing the phone number + +When a parameter is bound to the account's phone number, the bot asks for the number right after `/start`, or before answering the +first question: + +![The phone number request](./assets/telegram-bot_share-phone-request.png) + +The request comes with a **Share phone number** button, which Telegram shows in place of the keyboard. +Pressing the button asks the user to confirm sharing the number, and then posts the user's contact card to the chat. + +![The phone number flow](./assets/telegram-bot_phone-flow.png) + +* The bot confirms that the number was received. + Questions sent before the number is shared are not answered, and have to be resent once it is shared. +* From then on the number is passed to the agent with every message from this user. + Its use is up to the agent's queries: in this example, they find the customer's own orders. +* Telegram sends the number as the user's contact card. + The bot will only accept the sender's own card: a card taken from the user's address book, holding another person's number, + will be refused, and the request will be repeated. + + + + + +### Returning users + +The shared number is kept for the channel and the Telegram user. In later chats the user is answered right away, and neither +`/clear` nor the daily roll of the conversation makes the bot ask for the number again: + +![A returning user](./assets/telegram-bot_orders-answer.png) + +A new channel, even one added for the same bot, knows nothing of earlier shares and asks the user to share the phone number again. + + + + + + + +Once added, the channel is managed from its details view, described in +[Dashboard: Channels view](../dashboard/channels-view.mdx#the-channel-s-details-view): the view's header carries the +**Pause**/**Resume** button and the **⋮** menu with **Edit** and **Delete**, common to every channel type, and the tabs below the +header are specific to the channel type. + +To open the details view, open the app from **My apps** in Quill's management dashboard, select **Channels** in the sidebar, and +click the channel's box: + +![The channel's box in the Channels view](./assets/telegram-bot_channel-box.png) + +--- + + + +### Pausing and deleting the channel + +To pause or resume the channel, click **Pause**/**Resume** in the header; to delete it, select **Delete** in the header's **⋮** menu. + +![Pause and the channel's menu in the details view's header](./assets/telegram-bot_channel-menu.png) + +Both actions are explained in the Channels view article, in +[Pausing and resuming a channel](../dashboard/channels-view.mdx#pausing-and-resuming-a-channel) and +[Deleting a channel](../dashboard/channels-view.mdx#deleting-a-channel). Each of them also has a Telegram side, explained here: + +* A paused bot stops answering, and messages users send meanwhile are held by Telegram for up to 24 hours, to be answered if + the channel is resumed within this time. +* A deleted channel stops the bot, but the bot itself remains yours on Telegram, and its token can be used to connect it again. + + + + + +### Rotating the bot token + +To replace the bot token, select **Edit** in the header's **⋮** menu, and rotate the token in the **Edit channel** form. +If you have @BotFather issue a new token for any reason (e.g., because the existing token leaked), you can switch the channel to +the new token here. + +![Rotating the bot token](./assets/telegram-bot_rotate-token.png) + +1. **Rotate bot token** + Turn the toggle on to replace the current token. +2. **New bot token** + Paste the new token. Quill will validate the token with Telegram before saving it. + The token has to belong to the same bot as the current one; the token of a different bot is refused. +3. **Save changes** + Click to save. + The bot continues to answer under the new token; the old token is no longer used. + + + + + +### The tabs of the details view + +The details view presents an informative **Connect** tab, a **Parameters** tab that allows you to change the bindings of the +agent's parameters, and a **Bot messages** tab that allows you to replace the bot's own messages with texts of yours: + +--- + +#### The Connect tab + +The **Connect** tab shows the bot's address on Telegram, which you can hand to your users so they can open a chat with the bot, +and the two commands a user needs in the chat, `/start` and `/clear`. + +![The Connect tab](./assets/telegram-bot_channel-details.png) + +1. **Connect** + Open the Connect tab. +2. **@NorthwindCatalogBot** + The bot's address on Telegram: the link `https://t.me/`, formed from the bot's username, which your users can open + in any Telegram client. + Click **Open in Telegram** to open a chat with the bot in your own Telegram client. + +--- + +#### The Parameters tab + +The **Parameters** tab lists the agent's parameters and the source each of them is currently bound to, as set when the +channel was added, and lets you change the bindings. +A parameter that is added to the [agent configuration](../getting-started/adding-an-ai-agent.mdx#modifying-the-agent-configuration) +after the channel was added appears in this tab unbound, and the bot will not answer until the parameter is bound: users are told +that the assistant is not fully configured yet. + +![The Parameters tab](./assets/telegram-bot_parameters.png) + +1. **Parameters** + Open the Parameters tab. +2. **Edit** + Click to make the bindings editable, and click **Save** when done. +3. **customerPhone** + The example agent has one parameter, `customerPhone`: the phone number its queries use to find a customer's orders + (see [Binding agent parameters](#binding-agent-parameters)). + Each row shows a parameter's name and the source the parameter is bound to; here, the Telegram phone number. + +--- + +#### The Bot messages tab + +Besides replying to user messages, the bot sends messages of its own: the greeting, the confirmation after `/clear`, the requests +for the user's details, and the notices sent when the bot cannot answer. +The default text of each of these messages is shown in the **Bot messages** tab, and can be replaced with a text of your own. + +![The Bot messages tab](./assets/telegram-bot_bot-messages.png) + +1. **Bot messages** + Open the Bot messages tab. +2. **Edit** + Click to make the message fields editable, and click **Save** when done. +3. **Greeting (/start)** + The bot's reply to `/start`. Type a text of your own, or leave the field empty to keep the default text. + + + +The available messages are arranged in the **Bot messages** tab by groups, as listed below. In the example above, only the +**Commands** group is visible. + +* **Commands**: the replies to `/start` and `/clear`. +* **Collecting details**: the requests for a username or a phone number, the label of the **Share phone number** button, and the + confirmations. +* **Errors & limits**: the notices sent when the agent is not fully configured, when a chat is overloaded, when a message failed, + and when the bot is added to a group. + + + + + + + + + +A Telegram bot channel is designed to allow any Telegram user to reach the bot and be answered by the agent. +The limits below follow this design and Telegram's own rules. None of them can be changed in the channel's settings. + +* **Anyone on Telegram can chat with the bot.** + The channel cannot select the users that will have access to the bot: any Telegram user who finds the bot can ask it questions. + Agent parameters bound to the Telegram user can tie the answers to this user's own data, but cannot turn anyone away. +* **One bot per channel, one agent per channel.** + See [Channels and agents](../channels/overview.mdx#channels-and-agents) in the channels overview. +* **The bot answers in private chats only.** + Added to a group, the bot posts one refusal and then stays silent in the group. +* **The bot answers text-only messages.** + A photo, a document, a sticker, or a voice message gets no reply. A contact card is accepted only when an agent parameter + takes the user's phone number. +* **The agent remembers a conversation for one day at most.** + A user can make the agent forget sooner by sending `/clear`, as described in [Clearing the conversation](#clearing-the-conversation). + See also [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels) + in the channels overview. +* **Messages sent faster than the bot answers may go unanswered.** + See [Behavior and limitations common to all channels](../channels/overview.mdx#behavior-and-limitations-common-to-all-channels) + in the channels overview. + + + + + + + +Symptoms met by the users of every bot type, not just of a Telegram bot, are listed in the channels overview, in +[Troubleshooting](../channels/overview.mdx#troubleshooting). + + + +The symptoms below are shown by a Telegram bot channel when something goes wrong, each with its likely cause and what to do about it. +The first symptoms are seen in Quill's management dashboard: in the channel form, in the **Edit channel** form, and in the Channels +view. The rest are encountered by the bot's users in their chats with the bot on Telegram. +The bot's messages are quoted in their default form, shown in [The Bot messages tab](#the-bot-messages-tab); a channel with +customized messages shows your texts instead. + + + +### In the dashboard + +* **Clicking `Connect bot` fails with "invalid bot token format".** + Likely cause: the token pasted in the form may be incomplete or mistyped. A bot token is the bot's numeric id, a colon, and a + secret string, e.g., `123456789:AA...`. + What to do: copy the whole token from @BotFather's message, as described in + [Creating a bot using @BotFather](#creating-a-bot-using-botfather), and paste it in the form's + [Bot token](#filling-in-the-channel-form) field. +* **Clicking `Connect bot` fails with "telegram rejected the bot token".** + Likely cause: the token may have been replaced using @BotFather, so Telegram no longer accepts the old one. + What to do: paste the token @BotFather issued last in the form's [Bot token](#filling-in-the-channel-form) field; if you are not + sure which token is current, have @BotFather issue a new one and paste it. +* **Clicking `Connect bot` fails with "could not reach telegram" or "telegram did not respond".** + Likely cause: the machine running Quill may have no access to `api.telegram.org`, as required in [Prerequisites](#prerequisites); + a firewall or a proxy blocking the address is the usual cause. + What to do: allow outgoing HTTPS connections from the machine running Quill to `api.telegram.org` in the firewall or proxy that + blocks them, or ask your network administrator to. +* **Clicking `Connect bot` fails with "bot @... is already connected".** + Likely cause: the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve + only one channel. When the channel is in another app, the message names that app. + What to do: delete the channel that holds the bot, in this app or in the app the message names, as described in + [Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another bot using @BotFather, as described in + [Creating a bot using @BotFather](#creating-a-bot-using-botfather), and paste the new bot's token in this form instead. +* **Clicking `Save changes` in the `Edit channel` form fails with "the token belongs to a different bot".** + Likely cause: the new token may have been copied from @BotFather's message about a different bot. + What to do: paste the token of the bot the channel was added for in the **New bot token** field of the **Edit channel** form. + To switch to a different bot, add a new channel for that bot instead, as described in + [Connecting the bot to your app](#connecting-the-bot-to-your-app). +* **The channel shows as `Active` in the Channels view, but the bot does not answer.** + Likely cause: the bot token may have been replaced using @BotFather, so Telegram no longer answers the requests Quill makes + with the old one. + The dashboard shows no warning for a replaced token, and messages users send meanwhile are lost. + What to do: enter the token @BotFather issued last in the channel, as described in [Rotating the bot token](#rotating-the-bot-token). +* **The channel shows as `Disabled` in the Channels view, and the bot does not answer.** + Likely cause: the channel was paused, using **Pause** in the header of its details view. + Messages users send while the channel is paused are held by Telegram for up to 24 hours, and are answered if the channel is + resumed within this time. + What to do: resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). + + + + + +### On Telegram + +* **The bot replies "This assistant is not fully configured yet. Please contact whoever set up this bot."** + Likely cause: the agent may have a parameter the channel does not bind, e.g., a parameter added to the agent after the channel + was added. + What to do: bind the parameter in the channel's [Parameters](#the-parameters-tab) tab. +* **The bot replies "Sorry - something went wrong handling that message. Please try again."** + Likely cause: the agent failed to produce the answer, e.g., because the database it queries or the LLM service it uses could not + be reached. + What to do: verify that the app's database, and the LLM service behind the agent's AI connection string, can be reached. The + connection string can be tested as described in + [Dashboard: AI connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then try the bot from + your own Telegram account. +* **The bot replies "This assistant needs your Telegram username. Set one in Telegram Settings and send your message again."** + Likely cause: a parameter is bound to **Telegram username**, and the user has no username set in Telegram. + What to do: advise the user to set a username in Telegram's settings and send the question again; or bind the parameter to + another source, in the channel's [Parameters](#the-parameters-tab) tab. +* **The bot replies "I only work in one-on-one chats. Message me directly to start a conversation." in a group, and then stays + silent there.** + Likely cause: the bot was added to a Telegram group; the bot answers in private chats only. + What to do: hand the users the bot's address, shown in the channel's [Connect](#the-connect-tab) tab, and advise them to open a + private chat with the bot at that address. +* **The bot asks a returning user for the phone number again.** + Likely cause: the channel may have been deleted and added again. The number is kept per channel, so a new channel has no record + of the number the user shared. + What to do: advise the user to share the number again. See [Returning users](#returning-users). + + + + diff --git a/quill/dashboard/assets/channels-view_box-actions.png b/quill/dashboard/assets/channels-view_box-actions.png new file mode 100644 index 0000000000..5ab50d5e69 Binary files /dev/null and b/quill/dashboard/assets/channels-view_box-actions.png differ diff --git a/quill/dashboard/assets/channels-view_channel-details.png b/quill/dashboard/assets/channels-view_channel-details.png new file mode 100644 index 0000000000..7a11c08c3d Binary files /dev/null and b/quill/dashboard/assets/channels-view_channel-details.png differ diff --git a/quill/dashboard/assets/channels-view_channel-menu.png b/quill/dashboard/assets/channels-view_channel-menu.png new file mode 100644 index 0000000000..f7fbfee385 Binary files /dev/null and b/quill/dashboard/assets/channels-view_channel-menu.png differ diff --git a/quill/dashboard/assets/channels-view_channel-paused.png b/quill/dashboard/assets/channels-view_channel-paused.png new file mode 100644 index 0000000000..d18908c473 Binary files /dev/null and b/quill/dashboard/assets/channels-view_channel-paused.png differ diff --git a/quill/dashboard/assets/channels-view_channels-view.png b/quill/dashboard/assets/channels-view_channels-view.png new file mode 100644 index 0000000000..b97dff7f31 Binary files /dev/null and b/quill/dashboard/assets/channels-view_channels-view.png differ diff --git a/quill/dashboard/assets/channels-view_delete-channel.png b/quill/dashboard/assets/channels-view_delete-channel.png new file mode 100644 index 0000000000..24ef437d6d Binary files /dev/null and b/quill/dashboard/assets/channels-view_delete-channel.png differ diff --git a/quill/dashboard/assets/channels-view_edit-channel.png b/quill/dashboard/assets/channels-view_edit-channel.png new file mode 100644 index 0000000000..0e506b147d Binary files /dev/null and b/quill/dashboard/assets/channels-view_edit-channel.png differ diff --git a/quill/dashboard/assets/channels-view_new-channel-menu.png b/quill/dashboard/assets/channels-view_new-channel-menu.png new file mode 100644 index 0000000000..1ef8d42f50 Binary files /dev/null and b/quill/dashboard/assets/channels-view_new-channel-menu.png differ diff --git a/quill/dashboard/assets/channels-view_overview-channels.png b/quill/dashboard/assets/channels-view_overview-channels.png new file mode 100644 index 0000000000..98e07b1040 Binary files /dev/null and b/quill/dashboard/assets/channels-view_overview-channels.png differ diff --git a/quill/dashboard/assets/snagit/channels-view_box-actions.snagx b/quill/dashboard/assets/snagit/channels-view_box-actions.snagx new file mode 100644 index 0000000000..4233e1299d Binary files /dev/null and b/quill/dashboard/assets/snagit/channels-view_box-actions.snagx differ diff --git a/quill/dashboard/assets/snagit/channels-view_channel-details.snagx b/quill/dashboard/assets/snagit/channels-view_channel-details.snagx new file mode 100644 index 0000000000..79986b7eec Binary files /dev/null and b/quill/dashboard/assets/snagit/channels-view_channel-details.snagx differ diff --git a/quill/dashboard/assets/snagit/channels-view_channel-paused.snagx b/quill/dashboard/assets/snagit/channels-view_channel-paused.snagx new file mode 100644 index 0000000000..5b994c6b09 Binary files /dev/null and b/quill/dashboard/assets/snagit/channels-view_channel-paused.snagx differ diff --git a/quill/dashboard/assets/snagit/channels-view_channels-view.snagx b/quill/dashboard/assets/snagit/channels-view_channels-view.snagx new file mode 100644 index 0000000000..1485d38b77 Binary files /dev/null and b/quill/dashboard/assets/snagit/channels-view_channels-view.snagx differ diff --git a/quill/dashboard/assets/snagit/channels-view_delete-channel.snagx b/quill/dashboard/assets/snagit/channels-view_delete-channel.snagx new file mode 100644 index 0000000000..f869139cae Binary files /dev/null and b/quill/dashboard/assets/snagit/channels-view_delete-channel.snagx differ diff --git a/quill/dashboard/assets/snagit/channels-view_edit-channel.snagx b/quill/dashboard/assets/snagit/channels-view_edit-channel.snagx new file mode 100644 index 0000000000..72a814dbdf Binary files /dev/null and b/quill/dashboard/assets/snagit/channels-view_edit-channel.snagx differ diff --git a/quill/dashboard/assets/snagit/channels-view_new-channel-menu.snagx b/quill/dashboard/assets/snagit/channels-view_new-channel-menu.snagx new file mode 100644 index 0000000000..50a1930663 Binary files /dev/null and b/quill/dashboard/assets/snagit/channels-view_new-channel-menu.snagx differ diff --git a/quill/dashboard/assets/snagit/channels-view_overview-channels.snagx b/quill/dashboard/assets/snagit/channels-view_overview-channels.snagx new file mode 100644 index 0000000000..7f759b509e Binary files /dev/null and b/quill/dashboard/assets/snagit/channels-view_overview-channels.snagx differ diff --git a/quill/dashboard/channels-view.mdx b/quill/dashboard/channels-view.mdx new file mode 100644 index 0000000000..5928e5ff66 --- /dev/null +++ b/quill/dashboard/channels-view.mdx @@ -0,0 +1,246 @@ +--- +title: "Dashboard: Channels view" +sidebar_label: Channels view +sidebar_position: 14 +description: "The Channels view of a Quill app: the channels the app serves its users through, listed by type, with the actions common to every channel type: adding a channel, opening its details view, editing, pausing and resuming, and deleting it." +--- + +import Admonition from '@theme/Admonition'; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + +# Dashboard: Channels view + + +* A [channel](../overview.mdx#channels) carries the conversations between your users and one of your app's agents: a chat widget + on your site, a Telegram bot, a Slack app, or a Discord bot. + The **Channels** view lists the channels you already created, and allows you to view and modify channel settings, add new + channels, check each channel's status, and perform other channel-related tasks like pausing or deleting a channel. + +* The view is opened from the app's sidebar, where it is listed under the **Settings** group. + The app's **Overview** also lists existing channels, in a table that offers some of the actions available through the + Channels view. + +* This page covers Channels view features that are common to all channel types. + Features and behaviors specific to each channel type are covered in the pages dedicated to the various types, listed in + [Channels: Overview](../channels/overview.mdx#channel-types). + +* In this article: + * [Opening the Channels view](#opening-the-channels-view) + * [Adding a channel](#adding-a-channel) + * [The channel's details view](#the-channel-s-details-view) + * [Editing a channel](#editing-a-channel) + * [Pausing and resuming a channel](#pausing-and-resuming-a-channel) + * [Deleting a channel](#deleting-a-channel) + * [An additional entry point: the channels list in the Overview](#an-additional-entry-point-the-channels-list-in-the-overview) + + + + + +The Channels view is the place where an app's channels are managed. +To open it, open the app in Quill's management dashboard and click **Channels** in the sidebar, under **Settings**. + +![The Channels view](./assets/channels-view_channels-view.png) + +1. **Channels** + Open the Channels view. +2. **Search by name** + Type a part of a channel's name to show only the channels whose names contain it. +3. **New channel** + Click to select a channel type and add a channel of this type. See [Adding a channel](#adding-a-channel). +4. **All channels** + List channels of all types or of one type only: Web widgets, Telegram bots, WhatsApp, Slack, or Discord. +5. **Any status** + Show only active channels, only paused channels, or both. +6. **Telegram bots** + The channels are grouped by type. Each group is headed by its type name and the number of channels in the group. +7. **A channel box** + Each box shows the channel's name (and, for a bot, the bot's username), the channel's status, the agent the channel was added + for, and the time the channel was added. A web widget's box also shows its number of active embed links. + Click the box to open the channel's details view. See [The channel's details view](#the-channel-s-details-view). +8. **Edit channel** and **Delete channel** + Edit the channel, or delete it. See [Editing a channel](#editing-a-channel) and [Deleting a channel](#deleting-a-channel). + + + + The channel box depicted above is for a Telegram bot. A web widget's box also carries a **Generate link** icon, which opens + [the dialog for generating an embed link](../getting-started/adding-a-chat-widget.mdx#generating-an-embed-link) for the widget. + + + + + + + +A channel is added for one of the app's agents, and carries conversations to this agent alone. +Adding a new channel starts with selecting the channel's type: click **New channel** in the Channels view (or **Add channel** +in the [Overview's channels list](#an-additional-entry-point-the-channels-list-in-the-overview)) to open the menu of types, and +select a type to open its form. +The form for each type and what it asks for are described on the type's own page. + +![The New channel menu](./assets/channels-view_new-channel-menu.png) + +1. **Web widget** + A chat widget embedded in a page of your site. + See [Getting started: Adding a chat widget](../getting-started/adding-a-chat-widget.mdx). +2. **Telegram bot** + A bot your users chat with on Telegram. See [Channels: Telegram bot](../channels/telegram-bot.mdx). +3. **WhatsApp Personal** and **WhatsApp Business** + Not available yet; **Coming soon**. +4. **Slack** and **Discord** + A Slack app, or a Discord bot, that your users message directly. + See [Channels: Slack bot](../channels/slack-bot.mdx) and [Channels: Discord bot](../channels/discord-bot.mdx). + + + + + +Clicking a channel's box in the Channels view, or **Open details** in the +[Overview's channels list](#an-additional-entry-point-the-channels-list-in-the-overview), opens the channel's details view. +The view's header is the same for every channel type. The tabs below the header change per channel type: those depicted in the +image below, for example, are a web widget's tabs. The tabs provided for each channel type are described in the type's dedicated +page, e.g., [Channels: Telegram bot](../channels/telegram-bot.mdx#managing-the-channel). + +![The channel's details view](./assets/channels-view_channel-details.png) + +1. **Active** + The channel's status: **Active**, or **Disabled** when the channel is paused. +2. **Pause** + Pause the channel, or resume its activity when paused. See [Pausing and resuming a channel](#pausing-and-resuming-a-channel). +3. **Edit or Delete the channel** + The **⋮** button opens the channel's menu. The same two actions are also offered on the channel's box in the Channels view, as + the pencil and trash icons: + + | Edit/delete on the channel's menu | Edit/delete on a channel's box | + |---|---| + | ![Edit/delete on the channel's menu](./assets/channels-view_channel-menu.png) | ![Edit/delete on a channel's box](./assets/channels-view_box-actions.png) | + + **Edit** opens the form described in [Editing a channel](#editing-a-channel). + **Delete** allows you to [delete the channel](#deleting-a-channel). +4. **Web widget**, **Product Catalog Assistant**, and the channel id + The channel's type, the agent the channel was added for, and the channel's id, the identifier Quill's API uses for the channel. +5. **Embed**, **Active links**, and **Customize appearance** + The tabs of the channel's type, in this case a web widget. + + + + + +A channel is edited in the **Edit channel** form, opened using the pencil icon or the **Edit** menu entry described in +[The channel's details view](#the-channel-s-details-view), or from the +[channels list in the Overview](#an-additional-entry-point-the-channels-list-in-the-overview). +The form presents the channel's name at the top (in this case, "Catalog chat") and a section relevant to the selected channel +type below. +The agent the channel was added for cannot be changed; to serve another agent, add a new channel for the agent. + +![The Edit channel form](./assets/channels-view_edit-channel.png) + +1. **Channel name** + Change the name shown for the channel in the Channels view and in the Overview's channels list. +2. **Allowed origins** + The section that belongs to the channel's type. For the web widget shown here: the sites the widget may be embedded in + (see [Restrict where the widget loads](../developer-access/embed-the-chat-widget.mdx#restrict-where-the-widget-loads)); + for a Telegram bot: the option to replace the bot token (see + [Channels: Telegram bot](../channels/telegram-bot.mdx#rotating-the-bot-token)); for a Slack bot: the option to rotate the + credentials (see [Channels: Slack bot](../channels/slack-bot.mdx#rotating-the-credentials)); for a Discord bot: the option to + replace the bot token (see [Channels: Discord bot](../channels/discord-bot.mdx#rotating-the-bot-token)). +3. **Save changes** + Click to save the changes. **Cancel** closes the form without saving. + + + + + +Pausing a channel takes it out of service without deleting anything: the channel's settings and conversations are kept, and the +channel can be resumed at any time. +A channel is paused and resumed using the **Pause**/**Resume** button in the header of its details view, described in +[The channel's details view](#the-channel-s-details-view). + +![A paused channel](./assets/channels-view_channel-paused.png) + +1. **Disabled** + The status of a paused channel. +2. **Resume** + Put the channel back in service. + +What a pause means for the channel's users depends on the channel type: + +* **Web widget** + A paused web widget will stop answering. + A page that embeds it reports that the conversation has ended, as it does for an expired embed link. + No new embed link can be generated for the channel while it is paused. + Once the channel is resumed, its embed links that have not expired work again. +* **Telegram bot** + A paused Telegram bot will stop answering. + Messages users send meanwhile are held by Telegram for up to 24 hours, and answered if the channel is resumed within this time. + See [Channels: Telegram bot](../channels/telegram-bot.mdx#pausing-and-deleting-the-channel). +* **Slack bot** + A paused Slack bot will stop answering. + Slack keeps delivering the users' messages, which Quill discards; messages sent while the channel is paused are not answered when + the channel is resumed. + See [Channels: Slack bot](../channels/slack-bot.mdx#pausing-and-deleting-the-channel). +* **Discord bot** + A paused Discord bot will stop answering and appear offline on Discord. + Messages users send while the channel is paused do not reach Quill, and are not answered when the channel is resumed. + See [Channels: Discord bot](../channels/discord-bot.mdx#pausing-and-deleting-the-channel). + + + + + +Deleting a channel removes it from the app for good, with its settings; the deletion cannot be undone. +A channel is deleted using the trash icon or the **Delete** menu entry described in +[The channel's details view](#the-channel-s-details-view), or from the +[channels list in the Overview](#an-additional-entry-point-the-channels-list-in-the-overview). A confirmation is asked first: + +![The Delete channel dialog](./assets/channels-view_delete-channel.png) + +The conversations the channel carried are kept, and remain available in the app's **Conversations** view. +What else the deletion means depends on the channel type: + +* **Web widget** + A deleted web widget's embed links will stop working. + A page that embeds an embed link reports that the conversation is not available. +* **Telegram bot** + A deleted Telegram bot channel will stop the bot. + The bot itself remains yours on Telegram, and its token can be used to connect it again, to this app or to another. + See [Channels: Telegram bot](../channels/telegram-bot.mdx#pausing-and-deleting-the-channel). +* **Slack bot** + A deleted Slack bot channel will stop the bot. + The bot itself remains installed in the workspace, and its credentials can be used to connect it again, in a new channel with a + new request URL. + See [Channels: Slack bot](../channels/slack-bot.mdx#pausing-and-deleting-the-channel). +* **Discord bot** + A deleted Discord bot channel will stop the bot. + The bot itself remains yours in the Discord Developer Portal, and a member of your server; its token can be used to connect it + again. + See [Channels: Discord bot](../channels/discord-bot.mdx#pausing-and-deleting-the-channel). + + + + + +Besides the Channels view, the app's **Overview** ends with a list of the app's channels, showing for each channel the channel's +name (and, for a bot, the bot's username), the agent the channel was added for, its status, its type, its number of active embed +links (web widgets only), and the time it was added. +The list's **Add channel** button opens the same menu of channel types as the Channels view's +[**New channel**](#adding-a-channel) button, and each row ends with the channel's actions: + +![The channels list in the Overview](./assets/channels-view_overview-channels.png) + +1. **Open details** + Open the channel's details view. See [The channel's details view](#the-channel-s-details-view). +2. **Edit channel** + Edit the channel. See [Editing a channel](#editing-a-channel). +3. **Delete channel** + Delete the channel. See [Deleting a channel](#deleting-a-channel). + + + +The channel row depicted above is for a Telegram bot. A web widget's row also carries a **Generate link** icon, which opens +[the dialog for generating an embed link](../getting-started/adding-a-chat-widget.mdx#generating-an-embed-link) for the widget. + + + + diff --git a/quill/getting-started/adding-a-chat-widget.mdx b/quill/getting-started/adding-a-chat-widget.mdx index f5da921739..0e15d22e07 100644 --- a/quill/getting-started/adding-a-chat-widget.mdx +++ b/quill/getting-started/adding-a-chat-widget.mdx @@ -37,8 +37,8 @@ current with your source data. -* The chat widget is one of the channel types Quill offers. You can also add channels that carry conversations - through a Telegram bot, a Slack app, or a Discord bot, reaching your users where they already are. +* The chat widget is one of the [channel types Quill offers](../channels/overview.mdx#channel-types). You can also add channels + that carry conversations through a Telegram bot, a Slack app, or a Discord bot, reaching your users where they already are. * A channel has no address of its own. A chat widget is opened through an **embed link**, an address you generate for the channel and place on your @@ -197,7 +197,7 @@ When the agent takes parameters, the dialog opens a field for each parameter. The field's name and the text under it are the parameter's name and description, taken from the agent's configuration. -Every parameter the agent declares has to be given a value before the link can be generated. +Every parameter the agent has must be given a value before the link can be generated. The values you enter for these parameters are bound into the link and cannot be changed by users. You can, for example, generate an embed link for a specific product, with the product's ID already bound into diff --git a/quill/overview.mdx b/quill/overview.mdx index 19da955fdd..3d0ddf0d59 100644 --- a/quill/overview.mdx +++ b/quill/overview.mdx @@ -122,8 +122,8 @@ Parts of the Quill service and the data flow between them: #### Channels -* A channel carries the conversations between your users and an agent: user messages reach the agent through the - channel, and replies return the same way. +* A [channel](channels/overview.mdx) carries the conversations between your users and an agent: user messages reach the agent + through the channel, and replies return the same way. * Each channel is bound to a single agent. * An agent can serve several channels at once.