はじめに

本記事では、Hinemos ver.7.2.0から提供されている「電話通知機能（Twilio連携スクリプト）」の概要と設定のポイントについて解説します。

システム運用において、クリティカルな障害が発生した際、メールや画面上のアラートだけでは担当者が気づくのに遅れてしまうケースがあります。

本機能を利用することで、Hinemosで検知した異常やジョブの実行結果などのイベントを契機に、外部サービスの「Twilio」を通じて
電話やSMSで担当者に直接通知を行うことが可能になります。

前提条件

本機能を利用するために必要な環境は以下の通りです。

・対応バージョン: Hinemos ver.7.2.0以降

・必要なコンポーネント:

  - Hinemos マネージャ

  - Hinemos Webクライアント

  - Hinemos エージェント

実行環境（エージェントサーバ側）

・ランタイム: Python 3.11以降

・通信要件: Twilio APIへのHTTPS通信、およびpipによる依存パッケージ取得のための通信が可能であること

外部サービス（Twilio）

・Twilioアカウントの作成

・API認証情報の取得（Account SID、Auth Token、またはAPIキー等）

・発信元として利用するTwilio電話番号の取得

事前準備

実際に通知を行うための初期セットアップの流れは以下のようになります。

1.スクリプトの配置と依存関係の導入

 Hinemosエージェントのサーバにパッケージを展開し、以下のコマンドを実行して必要なPythonライブラリを一括導入します。

# pip install -r requirements.txt

2.設定ファイルの編集

 conf/config.toml ファイルを編集し、Twilioの各種認証情報を設定します。

3.セットアップスクリプトの実行

  scripts/configure.py を手動で実行し、Twilio側に必要な設定を自動登録します。

電話通知機能の主な特徴と挙動

本スクリプトでは、単に架電を行うだけでなく、運用に合わせた柔軟な通知設定が可能です。

電話通知とSMS通知の使い分け

・電話通知では、指定したメッセージを自動音声で読み上げます。

・SMS通知では、指定した宛先へテキストメッセージを送信します。

グループ発信の挙動

複数の宛先（グループ）へ発信する際、以下の2つのモードから発信方式を選択できます。

・一斉発信（broadcast）: 登録されたメンバー全員に同時に発信します。

・順次発信（sequential）: 登録されたメンバーに対して順番に発信します。

通知メッセージの設定とチューニング

読み上げる音声メッセージについて、以下のような高度な調整・制御が可能です。

・合成音声・言語の選択 : Twilioがサポートする各種合成音声や言語を指定できます。

・繰り返し再生: メッセージを繰り返し再生する回数を指定できます。

・SSML（音声合成マークアップ言語）対応: テキスト内にSSMLタグを含めることで、音声のトーン、速度、間隔などを細かく調整できます。

・終話・応答メッセージ: メッセージ終了まで入力がない場合の「終話メッセージ」や 、入力受付後に読み上げる「応答メッセージ」を個別に設定できます。

・読み上げ用の文字変換: 記号など読み方が不定な文字を、辞書ファイル（conversion_rules.tsv）に従って指定した文字列に
 自動置換して読み上げさせることが可能です。

電話番号照会機能

コマンドラインで直接電話番号を指定するだけでなく、外部リソースや管理ファイルから「エイリアス（名前）」を使って
番号を照会・検索する機能が備わっています。

照会先は以下の2つから選択可能です。

・Twilioへの番号照会（service）: Twilioに登録されている番号をAPI経由で照会

発信先（To）は「Verified Caller IDs」、発信元（From）は「Active Numbers」に登録された「Friendly Name（登録名）」に対して
前方一致で検索を行います。

複数ヒットした場合は自動的にグループ発信として扱われます。

・ファイルへの番号照会（file）: スクリプトのインストールフォルダにある電話番号管理ファイル（conf/phone_book.ini）を完全一致で検索

ファイル内に1つのエイリアスに対してカンマ区切りで複数の番号を記載しておくことで、グループ発信の対象にすることも可能です。

受話側の操作とHinemosでの成否判定

電話通知では、電話を受けた担当者のアクションによって、ジョブの終了コードが変化します。

・承諾（終了コード0）: 電話に応答し、設定された「承諾キー」を入力した場合、グループ発信時は、誰か一人が承諾した時点で発信処理が終了

・拒否（終了コード1）: 指定キー以外を入力した、あるいは入力しなかった場合

・不応答（終了コード2）: 電話に出なかった場合

その他、エラーコードなどについては公式ドキュメントをご参照ください。

Hinemosでのジョブ設定・組み込みの流れ

実際に監視エラー発生時に架電を行うためには、Hinemos上でジョブとジョブ通知の設定を行います。

コマンドジョブの作成

電話通知を行いたい場合は、起動コマンドに make_call.pyを指定し、
引数で宛先（--to）や読み上げるメッセージ（--message）、HinemosのセッションID・ジョブID変数を渡します。

# 起動コマンド例
python /opt/hinemos_call_notification/bin/make_call.py \
 --to +8190XXXXXXXX \
 --session-id "#[SESSION_ID]" \
 --job-id "#[JOB_ID]" \
 --message "Hinemos alert: #[MESSAGE]"

誤発信を途中で止める等の要件に備え、停止コマンドとして hangup_call.py を設定しておくことで、
Hinemosからの操作で実行中の電話通知を終了させることができます。

# 停止コマンド例
python /opt/hinemos_call_notification/bin/hangup_call.py \
 --session-id "#[SESSION_ID]" \
 --job-id "#[JOB_ID]"

ジョブ通知への設定

監視やジョブの「ジョブ通知」の実行対象に、上記で作成した電話通知用のジョブを指定します。

まとめ

本記事のまとめです。

運用の注意点

本機能は外部サービス（Twilio）と通信キャリアのネットワークを利用するため、宛先が圏外であったり、
ネットワーク障害が発生している場合は到達が遅延・失敗する可能性があります。

メール通知などと併用して、確実な障害検知ルートを設計することをお勧めします。