REST API を使用した SMS セッションの制御

SMS Gateway では、エージェントが顧客と SMS エージェント間の SMS セッションを開始できるように、コンタクト・センター・アプリケーションで使用できる REST APIが用意されています。 cURL コマンドを使用して、アプリケーションで REST API を取り込むことができます。 テストのために、Swagger ユーザー・インターフェースを介して直接、REST API と対話することもできます。

REST API について

REST API を使用して、セッションの作成や構成のテストなどの使用可能な操作を実行して、SMS セッションを制御できます。 REST API は、以下の 2 つのタイプの JSON データを SMS Gateway に渡して、SMS セッションを制御します。

REST API Swagger UI を介して直接、各操作をテストできます。あるいは、コンタクト・センター・アプリケーション内で各操作に対して cURL コマンドを使用できます。

実行できる操作

REST API を使用して、以下の操作を実行できます。

いずれかの操作に成功しなかった場合、SMS Gateway ログで何が失敗したのか確認してください。

REST API Swagger ユーザー・インターフェースへのアクセス

SMS Gateway をデプロイした後に、以下の URL で REST API Swagger UI にアクセスできます。

結果として表示された SMS Gateway API ページで、「操作のリスト (List operations)」をクリックして、SMS セッションで使用可能な操作を表示します。

操作のテスト

  1. 「データ・タイプ (Data type)」列で、例をクリックして「値 (Value)」フィールドに事前入力します。
  2. ユーザーおよびテナント電話番号を入力するなどして、「値 (Value)」フィールドの JSON データを変更します。 重要: テナント電話番号は、SMS Gateway 構成で指定されているテナント電話番号に完全に一致している必要があります。
  3. 「試行する (Try it out!)」をクリックして操作を実行します。
  4. プロンプトが出されたら、ユーザー名とパスワードを入力します。 REST API の認証を有効化した場合に限り、認証のためのプロンプトが出されます。

操作を試行すると、インターフェースには、以下の情報が表示されます。

cURL コマンドの使用

cURL コマンドを使用して、REST API 操作を実行できます。これは、コマンド・ラインで行うか、アプリケーションに cURL コマンドを取り込んで行います。 Linux ベースのシステムでは通常、cURL が組み込まれていますが、ご使用のオペレーティング・システムに cURL が組み込まれていない場合は、curl.haxx.se からご使用のオペレーティング・システム用のパッケージをダウンロードしてインストールできます。

要求を送信するコマンドは、以下のフォーマットで指定します。

curl -X <HTTP 要求> --header 'Content-Type: application/json' --header 'Accept: application/json' -d <JSON データ>

以下のオプションも指定できます。 各オプションについて詳しくは、curl 資料を参照してください。

コマンドの例

以下のサンプル curl コマンドでは、REST API を使用して実行できる各種操作を示します。 サンプル・コマンドを実行する際には、必ず、smsUserPhoneNumber および smsTenantPhoneNumber の値をご使用の値に置き換えてください。

重要: テナント電話番号は、SMS Gateway 構成で指定されているテナント電話番号に完全に一致している必要があります。 ユーザー電話番号は、SMS プロバイダーに要求されているのと一致したフォーマットで指定する必要があります。 例えば、Twilio 電話番号には正符号 (+) が必要ですが、RestcommONE 電話番号は正符号 (+) なしで指定する必要があります。

セッションの管理

以下のコマンドを使用してセッションを管理します。

セッションの作成
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsUserData": { "data": "Data"}, \
   "smsSessionTimeoutCount": 600 \
}' 'http://host:9080/sms.gateway/session'
セッションの削除
curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789" \
}' 'http://host:9080/sms.gateway/session'

構成のテスト

以下のコマンドを使用して構成をテストします。

SMS プロバイダー構成のテスト
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321", \
   "smsUserPhoneNumber": "+12345556789" \
 }' 'http://host:9080/sms.gateway/testConfig/SMSProvider'
Watson Assistant サービス構成のテスト
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321", \
   "smsUserPhoneNumber": "+12345556789", \
   "smsUserData": { "data": "Data" }, \
   "smsSessionTimeoutCount": 600 \
}' 'http://host:9080/sms.gateway/testConfig/WCS'
XSLD キャッシュ・サーバー構成のテスト
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321" \
}' 'http://host:9080/sms.gateway/testConfig/XS'

Voice Gateway の SMS Gateway 統合サポートのコマンド例

以下のサンプル curl コマンドは、通話中に Voice Gateway と SMS メッセージをやり取りするカスタマーをサポートするために SMS Gateway が使用するコマンドを示します。 これらのサンプル・コマンドを実行するときには、smsUserPhoneNumber および smsTenantPhoneNumber の値を実際の値に置き換えてください。 また、これらのサンプル・コマンドが正常に機能するには、要求を送信できるように SMS Gateway サーバー URL に host および port を構成する必要があります。 SMS Gateway サーバー URL は、セキュア・ポートがいつ構成されるのかに応じて、http:// または https:// のいずれかにすることができますが、必ず /sms.gateway/smsPipe を含んでいる必要があります。

要求および応答の変数についての説明は REST API Swagger UI にあります。 『REST API Swagger ユーザー・インターフェースへのアクセス』を参照してください。

重要: テナント電話番号は、SMS Gateway 構成で指定されているテナント電話番号に完全に一致している必要があります。 ユーザー電話番号は、SMS プロバイダーに要求されているのと一致したフォーマットで指定する必要があります。 例えば、Twilio 電話番号には正符号 (+) が必要ですが、RestcommONE 電話番号は正符号 (+) なしで指定する必要があります。

SMS パイプの作成

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsResponseURL": "https://vgwServer:port/smsRecv", \
   "smsToken": "tokenID",\
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
        "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ], \
   "smsMessage": "Hello this is a chat message sent from Voice Gateway.",\
   "smsOpaqueData": { "data": "Data"} ,\
   "smsPipeTimeoutCount": 1200 \
}' 'http://host:port/sms.gateway/smsPipe'

SMS パイプ ID を使用した SMS または MMS メッセージの送信

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsMessage": "Hello this is a chat message sent from Voice Gateway.",\
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
           "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ], \
   "smsOpaqueData": { "data": "Data"}
 }' 'http://host:port/sms.gateway/smsPipe/pipeID/KzE1MTAzMzAyNTgyOisxOTE5Njk5MjYwzJjZmNhZC1lMzc/sms'

SMS パイプ ID なしでの SMS または MMS メッセージの送信

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsMessage": "Hello this is a chat session starting from Voice Gateway."\
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
           "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ]
 }' 'http://host:port/sms.gateway/smsPipe/sms'

SMS パイプの削除

curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{}' 'http://host:port/sms.gateway/smsPipe/pipeID/KzE1MTAzMzAyNTgyOisxOTE5Njk5MjYwzJjZmNhZC1lMzc'