diff --git a/README.md b/README.md index 482f257..d37aa42 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ We used to have Slack as communication platform. When an event occur in our infr ### Our solution -![main-diagram](doc/main-diagram.png) +![main-diagram](doc/img/main-diagram.png) We've implemented a MSTeams Bot that allows us to interact with users through text and cards while exposing a regular HTTP API. @@ -138,7 +138,7 @@ cards: This `.yaml` file would render as: -![default-options](doc/default-options.png) +![default-options](doc/img/default-options.png) --- @@ -162,14 +162,14 @@ We'll need a few resources from the [Azure portal](https://portal.azure.com/#hom ``` https://{domain}/api/v1/messages ``` - + 3. Go to the settings of your **Bot Channel Registration** - - Select "Settings": + - Select "Settings": - Copy the **Microsoft App ID** value (the one that can't be changed) - - Click "Manage", then "Certificate & secrets": + - Click "Manage", then "Certificate & secrets": - Create a "New client secret" and copy its value (you won't see it again). This will be our **Microsoft App Secret** 4. Go back to the settings of your **Bot Channel Registration** - - Select "Channels": + - Select "Channels": - Connect to Microsoft Teams channel. It should say "Running" ### Remote Connection diff --git a/doc/api.md b/doc/api.md index cdac63e..24b9308 100644 --- a/doc/api.md +++ b/doc/api.md @@ -29,13 +29,13 @@ POST /api/v1/notify ### Parameters -| Name | Required | Type | Description | -| :---------- | :------- | :------------------------- | :----------------------------------------- | -| **user** | Required | `string` | Name of the recipient for the notification | -| **message** | Required | `string` or `Activity`(\*) | The notification | -| mention | Optional | `boolean` | Append a mention to the user (@user) | +| Name | Required | Type | Description | +| :---------- | :------- | :---------------------------------------- | :-------------------------------------------------------------- | +| **user** | Required | `string` | Name of the recipient for the notification | +| **message** | Required | `string` or `Activity` or `RichCard` (\*) | The notification | +| mention | Optional | `boolean` | Append a mention to the user (@user) (only for string messages) | -> \*[Activity](https://www.npmjs.com/package/botframework-schema?activeTab=explore): JSON object defined in `botframework`. +> \* `message` allows 3 formats, [read more](./message-format.md) ### Response Codes @@ -58,16 +58,6 @@ curl -s -H "content-type: application/json"\ } ``` -```bash -# 202 -curl -s -H "content-type: application/json"\ - -d '{"user": "jane.doe@megacoorp.com", "message": {"text": "this is the text", "title": "this is the title"}}'\ - localhost:3978/api/v1/notify | jq -{ - "conversationKey": "6afb0bc0-6ba7-11eb-98a1-211142846850|livechat" -} -``` - ```bash # 202 curl -s -H "content-type: application/json"\ @@ -110,18 +100,18 @@ POST /api/v1/broadcast ### Parameters -| Name | Required | Type | Description | -| :--------------------- | :------- | :------------------------- | :----------------------------------------------------------------------------------- | -| **topic** | Required | `string` | Name of the topic: every user subscribed to this topic will receive the notification | -| **message** | Required | `string` or `Activity`(\*) | The notification | -| mention | Optional | `boolean` | Append a mention to the user (@user) | -| createTopicIfNotExists | Optional | `boolean` | Ensure topic is created if wasn't registered on db | +| Name | Required | Type | Description | +| :--------------------- | :------- | :---------------------------------------- | :----------------------------------------------------------------------------------- | +| **topic** | Required | `string` | Name of the topic: every user subscribed to this topic will receive the notification | +| **message** | Required | `string` or `Activity` or `RichCard` (\*) | The notification | +| mention | Optional | `boolean` | Append a mention to the user (@user) (only for string messages) | +| createTopicIfNotExists | Optional | `boolean` | Ensure topic is created if wasn't registered on db | -> \*[Activity](https://www.npmjs.com/package/botframework-schema?activeTab=explore): JSON object defined in `botframework`. +> \* `message` allows 3 formats, [read more](./message-format.md) ### Response Codes -- **202 Accepted**: multiple notifications have been submitted to Microsoft's endpoint.
+- **202 Accepted**: 1+ notifications have been submitted to Microsoft's endpoint.
Returns every used `conversationId` for traceability.
Note: empty list would mean that there are currently no subscribers to the given topic. - **400 Bad Request**: request body doesn't fulfill the requirements.
@@ -146,19 +136,7 @@ curl -s -H "content-type: application/json"\ ```bash # 202 curl -s -H "content-type: application/json"\ - -d '{"topic": "banana", "message": {"text": "this is the text", "title": "this is the title"}}'\ - localhost:3978/api/v1/broadcast | jq -{ - "conversationKeys": [ - "6afb0bc0-6ba7-11eb-98a1-211142846850|livechat" - ] -} -``` - -```bash -# 202 -curl -s -H "content-type: application/json"\ - -d '{"topic": "banana", "message": "hi there", "mention": true}'\ + -d '{"topic": "banana", "message": "broadcasting to banana subscribers", "mention": true}'\ localhost:3978/api/v1/broadcast | jq { "conversationKeys": [ @@ -360,3 +338,4 @@ curl -s -X PUT -H "content-type: application/json"\ --- > - [Back to main README](../README.md) +> - [More about `message` format](./message-format.md) diff --git a/doc/azure-bot-management.png b/doc/img/azure-bot-management.png similarity index 100% rename from doc/azure-bot-management.png rename to doc/img/azure-bot-management.png diff --git a/doc/azure-bot-management2.png b/doc/img/azure-bot-management2.png similarity index 100% rename from doc/azure-bot-management2.png rename to doc/img/azure-bot-management2.png diff --git a/doc/azure-connect-to-channels.png b/doc/img/azure-connect-to-channels.png similarity index 100% rename from doc/azure-connect-to-channels.png rename to doc/img/azure-connect-to-channels.png diff --git a/doc/azure-create-bot-channel.png b/doc/img/azure-create-bot-channel.png similarity index 100% rename from doc/azure-create-bot-channel.png rename to doc/img/azure-create-bot-channel.png diff --git a/doc/azure-manage-appid.png b/doc/img/azure-manage-appid.png similarity index 100% rename from doc/azure-manage-appid.png rename to doc/img/azure-manage-appid.png diff --git a/doc/default-options.png b/doc/img/default-options.png similarity index 100% rename from doc/default-options.png rename to doc/img/default-options.png diff --git a/doc/main-diagram.drawio b/doc/img/main-diagram.drawio similarity index 100% rename from doc/main-diagram.drawio rename to doc/img/main-diagram.drawio diff --git a/doc/main-diagram.png b/doc/img/main-diagram.png similarity index 100% rename from doc/main-diagram.png rename to doc/img/main-diagram.png diff --git a/doc/open-bot-emulator.png b/doc/img/open-bot-emulator.png similarity index 100% rename from doc/open-bot-emulator.png rename to doc/img/open-bot-emulator.png diff --git a/doc/message-format.md b/doc/message-format.md new file mode 100644 index 0000000..ef36a54 --- /dev/null +++ b/doc/message-format.md @@ -0,0 +1,138 @@ +# message format 🔡 + +Both `/api/v1/notify` & `/api/v1/broadcast` needs `message` as parameter. This message accepts 3 different formats: + +1. Plain `string`. + +2. [**`Activity`**](https://www.npmjs.com/package/botframework-schema?activeTab=explore): JSON object defined in `botframework-schema`. These JSON structures are what the framework accepts in the end. + +If the service detects the message is already formatted as an `Activity`, it will post it directly to `botframework`
+Note: meant for debugging and repeatability + +Example of an `Activity` object. + +```json +{ + "type": "message", + "inputHint": "acceptingInput", + "attachmentLayout": "list", + "attachments": [ + { + "contentType": "application/vnd.microsoft.card.hero", + "content": { + "title": "Just 2 buttons", + "buttons": [ + { + "title": "Button no. 1", + "value": "one", + "type": "imBack" + }, + { + "title": "Button no. 2", + "value": "two", + "type": "imBack" + } + ] + } + } + ] +} +``` + +3. [**`AdaptiveCard`**](https://docs.microsoft.com/en-us/adaptive-cards/): JSON object defined and supported by Microsoft. These JSON structures are what you'll typically use.
+ + Adaptive Cards have wide support from Microsoft: + + - [docs](https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#adaptive-card) + - [schema reference](https://adaptivecards.io/explorer/) + - [online designer](https://adaptivecards.io/designer/) + +Internally, if the service detects the message is an `AdaptiveCard` it will wrap it into an `Activity` before posting to `botframework`
+Note: In the designer, make sure you set **target version to 1.2** + +Example of an `AdpativeCard` (v1.2) object. + +```json +{ + "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", + "type": "AdaptiveCard", + "version": "1.2", + "body": [ + { + "type": "Container", + "items": [ + { + "type": "TextBlock", + "text": "Megacoorp", + "size": "Medium", + "wrap": true + }, + { + "type": "TextBlock", + "text": "The Future, Today", + "isSubtle": true, + "spacing": "None", + "wrap": true + }, + { + "type": "TextBlock", + "text": "{{DATE(2042-01-01T22:00:00+02:00, SHORT)}}", + "wrap": true + } + ] + }, + { + "type": "Container", + "spacing": "None", + "items": [ + { + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "stretch", + "items": [ + { + "type": "TextBlock", + "text": "42", + "size": "ExtraLarge", + "wrap": true + } + ] + } + ] + } + ] + } + ] +} +``` + +## API Call + +Remember that the `message` property should be defined in the first level. + +```bash +curl -s -H "content-type: application/json"\ + -d '{"user": "jane.doe@megacoorp.com", "message": { ... }}'\ + localhost:3978/api/v1/notify | jq +{ + "conversationKey": "6afb0bc0-6ba7-11eb-98a1-211142846850|livechat" +} +``` + +```bash +curl -s -H "content-type: application/json"\ + -d '{"topic": "banana", "message": { ... }}'\ + localhost:3978/api/v1/broadcast | jq +{ + "conversationKeys": [ + "6afb0bc0-6ba7-11eb-98a1-211142846850|livechat" + ] +} +``` + +--- + +> - [To main README](../README.md) +> - [Back to API docs](./api.md) diff --git a/local-development/doc/rich-card.json b/doc/sdk-objects/activity-card.json similarity index 100% rename from local-development/doc/rich-card.json rename to doc/sdk-objects/activity-card.json diff --git a/local-development/doc/adaptive-card.json b/doc/sdk-objects/adaptive-card.json similarity index 100% rename from local-development/doc/adaptive-card.json rename to doc/sdk-objects/adaptive-card.json diff --git a/local-development/README.md b/local-development/README.md index 8fcc28f..1762cc4 100644 --- a/local-development/README.md +++ b/local-development/README.md @@ -45,7 +45,6 @@ docker-compose up -d - add "172.17.0.1" to the setting "localhost override" in the Emulator - Bot URL would be `http://localhost:3978/api/v1/messages` - Leave app id and password empty for local development -

open-bot-emulator

![local-bot-emulator](doc/local-bot-emulator.png) _Bot Emulator connected to local service_