# 🤖 Notification Bot Deployment SOP v1.0

:::info
:gear: 這份文件用於幫助部屬使用到Azure的許多服務串成的Notification Bot
:::
## 💪 Function 功能
### **Post方法撥打提醒電話** :phone:
- Request Body為application/json格式，包含下列資訊
- text: 轉成語音的文字
- userId: 接聽的使用者識別碼
- tenantId: 租用戶識別碼
- 內容為文字轉語音的提醒事項
- 提醒事項撥放完畢電話自動掛斷
- 未接通的提醒電話成為**提醒事項語音信箱** ❗**使用者須開啟語音信箱功能**❗

## :beginner: Pre-requesite 必要條件

<!-- :::success
部屬Notification Bot之前置作業與必要條件
::: -->

<!-- :small_blue_diamond:Design Name:

:small_blue_diamond:Author: -->

<!-- :small_blue_diamond:需求: -->
- [ ] 管理員權限的Azure帳號
- [ ] Azure訂閱
- [ ] 包含Microsoft Teams的M365方案

<!-- ## :wrench: Specs

:::success
List the specs you design.
:::

| **Item** | **Spec** | **Note** |
|---------- |---------- |---------- |
| | | |
| | | |

***
:::warning
The following items can make this document more complete.
::: -->

## :brain: 部屬步驟

<!-- :::success
Describe how you implement this design, including flow, specs, and innovation.
::: -->
### :book:[註冊應用程式](https://learn.microsoft.com/zh-tw/azure/active-directory/develop/quickstart-register-app)

- 前往[**Azure portal**](https://ms.portal.azure.com/)
- Azure portal上方搜尋欄搜尋 "**應用程式註冊**"進到服務頁面
- 點選"**新增註冊**"
- 註冊頁面填寫"**名稱**"以及選擇"**支援的帳號類型**"完成下方點擊"**註冊**"完成註冊<br/>(依據需求選擇，若不確定可選擇**單一用戶**)
- 註冊完成的應用程式中我們會針對兩個部分做設定分別是<br/>
"**憑證與秘密**"與"**API權限**"，那麼我們先針對"**憑證與秘密**"的 部分做設定
- 憑證與密碼的部分需要"**新增用戶端密碼**"
- 設定"**描述**"以及"**到期**"日，完成後下方點擊"**新增**"
- **密碼值會用於後續的設定<br/>❗剛產生的密碼值務必要存起來，之後就無法存取❗**
- 再來設定**API權限**，點選"**新增權限**"<br/>
**操作此步驟的使用者須為系統管理員**或是**需通知系統管理員核准權限**:warning:
- 選擇**Microsoft API**的**MicrosoftGraph**
- 如下圖開通**應用程式權限**下**Calls**的五個權限
- 以及同在**應用程式權限下的User.Read.All**權限，這6個權限點選後點選下方**新增權限**
- **權限賦予注意事項**
- 若操作的帳戶為管理者直接點選**代表{組織名}授予管理員同意**即可👌
- 若**非管理者帳戶**則需通知管理員核准權限:warning:<br/>
- 授權完成**狀態**顯示會如下圖做轉換:ok:


#### 註冊應用程式的部分就完成了👌

---

### 🤖[註冊Azure Bot](https://learn.microsoft.com/zh-tw/azure/bot-service/abs-quickstart?view=azure-bot-service-4.0&tabs=singletenant)

- 前往[**Azure portal**](https://ms.portal.azure.com/)
- Azure portal左上方功能表延展開來選擇**建立資源**
- 建立資源頁面的**搜尋欄搜尋**"**Bot**"後選擇**Azure Bot**
<br/><img src="https://i.imgur.com/QE3uXli.png" width="70%">
<br/>
:warning:**建立資源需要Azure的訂閱**:warning:
<br/>
<br/>
- 填入建立機器人的資訊<br/>
- **Bot控制代碼須為獨特的**且會**成為此機器人的Display Name**<br/>
- **資源群組**的部分可建立新的資源群組或是選擇Host WebAPI 的資源群組<br/>
- **定價層**點選**變更方案**，使用**免費方案**即可
- 上圖部分完成後下方**應用程式類型**選擇**單一租用戶**<br/>
- **建立類型**選擇**使用現有的應用程式註冊**，填入剛剛註冊應用程式的**應用程式識別碼(AppId)** 以及**應用程式租用戶識別碼(TenantId)**
⚙️**註冊的應用程式主頁正中間可找到相關資訊**⚙️
<img src="https://i.imgur.com/NGFQIpZ.png" width="85%">
<br/>
- 全部資訊填寫完成就點選"**檢閱 + 建立**"完成建立機器人。
#### 註冊Azure Bot的部分完成，設定部分後續處理👌

---

<!-- - 建立完成後，設定Azure Bot<br/>
**-** 前往**頻道**頁面，在**可用通道**下滑找到**Microsoft Teams**點選設定<br/>
**-** 進入Microsoft Teams的設定頁面後點選**通話Tab勾選啟用通話**<br/>
**-** WebHook後續會回來做設定，目前先留空白 -->

### 🔊註冊[語音服務](https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/rest-text-to-speech?tabs=streaming#convert-text-to-speech)
- 前往[**Azure portal**](https://ms.portal.azure.com/)
- Azure portal上方搜尋欄搜尋 "**語音服務**"進到服務頁面
- 於**認知服務 | 語音服務**頁面點選**建立**
- 填寫建立語音服務內容，**定價層**選擇**免費F0**(每個Azure訂閱限制一個F0:warning:)<br/>內容填寫完成點擊下方**檢閱+建立**，確認資訊正確後點擊**建立**完成語音服務建立
- 等待部屬畫面顯示**部屬完成**即**完成語音服務的註冊**👌

---

### :construction_worker: **部屬機器人到Azure App Service**
- 前往[**Azure portal**](https://ms.portal.azure.com/)
- Azure portal上方搜尋欄搜尋 "**應用程式服務**"進到服務頁面
- 點選**建立**

<img src="https://i.imgur.com/RDIiWMH.png" width="50%">

- 填寫建立Web應用程式資訊
- **資源群組**可選擇與**同前面註冊Azure Bot**
- **發佈**請選擇**代碼**
- **執行階段堆疊**請選擇"**.NET 6(LTS)**"
- **作業系統**請選擇**Windows**
- **地區**可自行選擇，這邊的部分選擇**East Asia**
- **定價方案**選擇**免費F1**即可
- 填寫完成在下方點選**檢閱+建立**並等待部屬


- Web應用程式部屬完成會顯示下圖畫面，點擊**前往資源**開始部屬機器人 <img src="https://i.imgur.com/ZFJodQI.png" width="60%">
- 在Web應用程式主頁面左方的功能欄找到**開發工具**下的**進階工具**Tab後點選**執行**
- 點選**執行**會顯示下圖的介面，在下圖**紅框的URL後面加上**"/ZipDeployUI"
- 下圖為URL後面加上"/ZipDeployUI"後的顯示畫面<br/>直接將機器人的**壓縮檔**(**須為.ZIP檔**)拖拉到畫面中間即開始上傳與部屬<br/>:warning:ZIP檔的目錄結構不能有**多一層資料夾**<br/>
Ex: publish.zip/publish/{files}❌<br/>需直接為publish.zip/{files} :o:
- 上傳且部屬完成後畫面如下圖，注意到**圖左上目錄為wwwroot**且**圖下方顯示Deployment successful**
- 部屬完成後可直接去網站檢查部屬結果是否正常，**若顯示下方畫面即表示部屬完成**<br/>點選**swagger**會前往**測試API機器人的UI**

#### 註冊Web應用程式的部分完成，設定部分接著處理👌
---

### :gear:**Azure Bot以及Web應用程式設定**
- ### 🤖Azure Bot設定
- 前往註冊的Azure Bot，主畫面左方功能欄找到**設定**的**頻道**Tab後點入
- 來到頻道頁面，在**可用通道**下找到並點入**Microsoft Teams**
- **通話**Tab下**勾選啟動通話**且輸入**Webhook**<br/>**Webhook**即為"**{Web應用程式網址}/callback**"<br/>其他設定不需更改，填寫完直接下方**套用**就👌
#### Azure Bot設定部分完成👌
- ### 📌Web應用程式設定
- 前往註冊且部屬好的Web應用程式，主畫面左方功能欄找到**設定**的**組態**Tab後點入
- 找到**應用程式設定**下方的**新增應用程式設定**<br/>先新增**名稱**為下方列出的設定，**值**的部分會陸續填入
- **Bot:AppId**
- **Bot:AppSecret**
- **Bot:BaseURL**
- **Bot:DurationBeforeVoicemail 直接設定25**
- **Bot:TuningDurationForCorrectVoicemail 直接設定9**
- **Speech:EndPoint**
- **Speech:Key**
- **Speech:STSUri**<br/>
<img src="https://i.imgur.com/yBDtXax.png" width="60%">
<img src="https://i.imgur.com/KO5oICt.png" width="60%"><br/><br/>
- #### **Bot:AppId、Bot:AppSecret與Bot:BaseURL**
- **註冊的應用程式主頁正中間可找到AppId將其填入Bot:AppId的值**<br/>
<img src="https://i.imgur.com/uQfUDHk.png" width="85%">
- **Bot:AppSecret的值**填入**前面註冊應用程式時儲存的密碼值**<br/>(若遺失可跟著前面步驟產生新的)
- **Bot:BaseURL即Web應用程式的網址(".azurewebsites.net"結尾)**
- #### **Bot:DurationBeforeVoicemail & Bot:TuningDurationForCorrectVoicemail**
- **Bot:DurationBeforeVoicemail**直接設定為25Fs(語音信箱預設值為20s)<br/>如果**由20s ->30s**此**設定則由25s -> 35s**依此類推
- **Bot:TuningDurationForCorrectVoicemail** <br/>預設設定為9s**但會依據系統狀況增加**，用於確保語音信箱的運作正常
- #### **Speech:EndPoint、Speech:Key**與**Speech:STSUri**
- **Speech:EndPoint**(端點)與**Speech:Key**(金鑰)皆可在註冊的語音服務中**概觀**Tab找到，如下圖點擊右側複製後填入對應的值
- **Speech:STSUri**的部分需前往[這個網站](https://learn.microsoft.com/zh-tw/azure/cognitive-services/speech-service/rest-text-to-speech?tabs=streaming#convert-text-to-speech)找到**對應地區的預建神經語音Uri**<br/>上圖的**語言服務設定位置設定為japanwest**那麼對應的Uri為 "https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1"<br/>如下圖所示
#### 上面7個應用程式設定都設定好後就完成了👌<br/>可以開始進行電話撥打的測試💪

## :hand: Demo與測試
:::success
此章示範測試呼叫機器人的方法，基本上可以呼叫Post方法的管道都可以使用
:::
### Swagger測試介面
- 前往Web應用程式，畫面如下圖<br/>點擊紅框的**swagger**字樣進入**Swagger測試介面**
- Swagger測試介面有兩個測試會用到的功能<br/>**Call下的"/call/BotInfo"以及"/call/raise"**

- **Get - /call/BotInfo**用來**確認應用程式設定值設定正確**<br/>展開後點擊右上方的**Try it out**後點擊**Execute**即可

- **Post - /call/raise 主要撥打提醒電話的API**<br/>展開後點即右上方的**Try it out**開始使用
- **text, userId**與**tenantId**需依照需求填入正確的資訊
- **text欄位填入被轉換成語音的文字提醒事項**
- **userId欄位填入被提醒者的識別碼**
- **tenantId欄位填入租用戶的識別碼**
- 以上資訊填寫完成點即點擊**Execute執行API開始測試**<br/>:warning:**請先開啟被撥打的使用者的Teams，準備好接聽電話確認功能正常**:warning:
- 顯示下圖字樣表示電話撥打成功 :+1:
- 接起由機器人撥打的Teams電話，應該會**撥放text欄位text-to-speech的提醒事項**<br/>且於**撥放完畢後自動掛斷電話**
- **沒有接起的提醒電話會進入語音信箱**，**測試上若沒有顯示進入語音信箱或是語音信箱的資訊不完整則可以調整**[**Bot:TuningDurationForCorrectVoicemail**](#BotDurationBeforeVoicemail-amp-BotTuningDurationForCorrectVoicemail)下圖所示成功進入語音信箱
#### 上述的各個功能皆完整那麼就功能測試完成👌
---