Zoho Survey APIを使用したSMS招待のトリガー

Zoho Survey APIを使用したSMS招待のトリガー

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

トリガーSMS招待

トリガーとは、事前に定義されたイベントが発生したときに特定の処理を実行するイベントです。Zoho SurveyのSMSトリガーを使用すると、ユーザーはアンケートフォームをトリガー招待として送信できます。
ユーザーは、SMS配信（トリガーに基づく連絡先）を作成することで、任意のアプリケーションからZoho SurveyのREST APIを使用してSMS招待を送信できます。

利用例

ホテルの顧客フィードバック
顧客からのフィードバックを把握したいレストラン経営者であるとします。顧客が支払いを完了した後、レビューを収集するために、顧客の電話番号宛てにSMSでアンケートを送信できます。
ECアンケート
商品の配送後に顧客へSMSを送信し、購入を確認するとともに、ECシステムからフィードバックを収集できます。

用語

  1. OAuth- ユーザーのパスワードを共有せずに、保護されたリソースへの安全なアクセスを提供する業界標準のプロトコルです。
  2. クライアント- エンドユーザーに代わってトリガー招待にアクセスするため、Zoho Surveyに要求を送信するアプリケーションです。
  3. クライアント ID- Zohoにアプリケーションを登録したときに受け取る一意の識別子です。
  4. クライアント シークレット- Zohoにアプリケーションを登録したときに生成される一意のキーです。機密情報として管理する必要があります。
  5. グラント トークン- アクセストークンとリフレッシュトークンを生成するために使用する一時的なトークンです。組織固有のグラントトークンの生成は、1回限りの処理です。
  6. アクセス トークン- ユーザーのトリガー招待にアクセスするため、Zoho Survey APIに送信されるトークンです。アクセストークンにより、Zoho Survey APIへの安全かつ一時的なアクセスが可能になります。各アクセストークンの有効期間は1時間のみで、スコープに記載された一連の操作にのみ使用できます。
  7. リフレッシュ トークン- 新しいアクセストークンを取得するために使用できるトークンです。このトークンは、エンドユーザーによって取り消されるまで無期限に有効です。
  8. API レート 制限- APIレート制限は、任意の時点で同時に実行できるAPI呼び出しの最大数です。

前提条件

  1. 有効なZoho Surveyユーザー認証情報。
  2. Zoho Survey APIにアクセスするための有効な認証トークンまたはOAuth。
  3. Zoho SurveyポータルでSMS配信を設定済みであること。

アプリケーションの登録方法

APIトリガー招待を有効にするには、まずZoho Developerコンソールにクライアントを登録します。
  1. クライアントIDとクライアントシークレットを生成するため、Zoho Developerコンソールにアプリケーションを登録します。
  2. クライアントIDとクライアントシークレットが生成されたら、クライアントの種類に応じて、スコープ「ZohoSurvey.invitation.CREATE」を使用して組織固有のグラントトークンを生成します。グラントトークンが必要なのは、自己クライアントやサーバーベースのアプリケーションなど、特定のクライアントのみです。
  3. 生成されたグラントトークンをコピーします。各種アプリの種類に応じたクライアントIDとクライアントシークレットの生成方法について、詳細を確認してください。

アクセストークンとリフレッシュトークンの生成

次に、グラントトークンを使用して、ドメインに対応するZoho Accounts URLでアクセストークンとリフレッシュトークンを生成します。
各ドメインと対応するアカウントURLは次のとおりです。
USの場合：https://accounts.zoho.com
AUの場合：https://accounts.zoho.com.au
EUの場合：https://accounts.zoho.eu
INの場合：https://accounts.zoho.in
CNの場合：https://accounts.zoho.com.cn
JPの場合：https://accounts.zoho.jp
CA（カナダ）の場合：https://accounts.zohocloud.ca
SA（サウジアラビア）の場合：https://accounts.zoho.sa

Notes
メモ。
  1. サーバーベースのアプリケーションの場合、アクセス種別パラメーターの値を「offline」として認証要求を送信します。値がofflineの場合、初回の要求時にアクセストークンとともにリフレッシュトークンを受け取ります。アクセストークンの有効期限が切れたら、リフレッシュトークンを使用して再生成できます。
  2. 各アクセストークンの有効期間は1時間のみで、スコープで定義された操作にのみ使用できます。
  3. 新しいアクセストークンを生成するには、リフレッシュトークンを使用します。リフレッシュトークンに有効期限はありません。アクセストークンの有効期限が切れたら、リフレッシュトークンを使用してアクセストークンを再生成します。

トリガーSMS招待の設定方法

Zoho SMS Serviceまたは外部SMSアプリを使用してトリガーSMS招待を設定するには、以下の手順に従います。

Zoho SMS Serviceを使用したSMS配信の作成
  1. Zoho Surveyポータルで、［公開］タブに移動し、［作成 SMS］をクリックします。
            
  1. 次に、［Zoho SMS Service］を［接続の種類］として選択します。SMSとして送信するカスタムメッセージを含むDLTファイルをアップロードするには、［インポート DLT ファイル］ボタンをクリックします。
  2. アップロードしたテンプレートを選択し、［これを使用］をクリックします。
  3. テンプレート内のキーを置き換える変数を選択します。
            
  1. 必須の変数であるため、{Surveylink}変数が追加されていることを確認します。
  2. 変数を追加したら、［保存］をクリックします。
  3. テンプレートメッセージを確認し、［次へ］をクリックします。
  4. 次に、連絡先の追加に進みます。
Notes
メモ。
アップロードしたテンプレートには承認期間があり、承認後にのみSMS招待として送信できます。承認期間中に却下される場合もあります。
SMS Serviceでは、テンプレートを編集できません。テンプレートを置き換えるか、［既存のテンプレートをコピー］をクリックして既存のテンプレートからコピーすることのみ可能です。

外部アプリを使用したSMS配信の作成

  1. Zoho Surveyポータルで、［公開］タブに移動し、［作成SMS］をクリックします。
            
  1. ［接続の種類］を選択します。ドロップダウンボタンをクリックすると、別の接続を選択できます。
  2. リッチテキストエディターを使用してカスタムメッセージを追加し、［次へ］をクリックして連絡先の追加に進みます。

SMS招待の送信先連絡先の選択方法

  1. ［送信先］セクションで、［連絡先（トリガーに基づく）］を選択し、［次へ］をクリックします。
     
                  
  1. トリガーの頻度として、［1回限りの招待］または［繰り返し招待］を選択します。
    1. ［1回限りの招待］の場合：頻度を設定するには、次のオプションから選択します。
      1. ［即時］- トリガーの設定後、SMS招待がすぐに送信されます。
                                        
      1. 遅延後：トリガーの開始後、特定の時間間隔が経過してからSMS招待が送信されるように、トリガーを設定できます。
      2. 指定した日時：招待は特定の日時にスケジュールできます。
      3. スケジュールされた時間枠：トリガーは特定の時間間隔のバッチとして設定できます。
    1. 対象が定期的な招待の場合、トリガーの頻度を設定します。

  1. ［作成］をクリックすると、成功画面にAPI情報が表示されます。
            
  1. APIの詳細は、いつでも次の場所で確認できます：［公開］→［SMSコレクター］→［トリガー招待］
  2. リクエストURLをコピーし、以下のように変数を設定します。

Notes
メモ：
API情報は、［公開］→［SMSコレクター］→［トリガー招待］→［表示］→［API］で確認できます
メソッド POST
ヘッダー Authorization: Zoho-oauthtoken e4af2b6xxxxxxxxxxxxxbaaba
（キー）（値）
Content-Type: application/json
メソッド POST
ヘッダー Authorization: Zoho-oauthtoken e4af2b6xxxxxxxxxxxxxbaaba
（キー）（値）
Content-Type: application/json
リクエスト本文

リクエスト本文      

パラメーター
データ型
説明
EmailAddress
文字列
連絡先のSMSアドレスを指定します
phoneNumber*
文字列
連絡先の電話番号を指定します。
firstName
文字列
連絡先の名を指定します。
lastName
文字列
連絡先の姓を指定します。
variableOne
文字列
追加データを収集するために、この変数項目を追加できます
variableTwo
文字列
追加データを収集するために、この変数項目を追加できます
variableThree
文字列
追加データを収集するために、この変数項目を追加できます
variableFour
文字列
追加データを収集するために、この変数項目を追加できます
variableFive
文字列
追加データを収集するために、この変数項目を追加できます
variableSix
文字列
追加データを収集するために、この変数項目を追加できます
*必須項目
 
Notes
メモ：POSTリクエストごとに複数の連絡先を追加できます。

サンプルリクエスト    
APIを実行するcurlコマンドの使用方法については、以下のサンプルリクエストを参照してください。
curl 'https://survey.zoho.in/api/v1/external-private/portals/60025974722/departments/djZ1qx/surveys/173695000000237177/collectors/173695000000317088/distributions/173695000000314041/sms/sendinvitation'
-H 'Authorization: Zoho-oauthtoken 1000.e4af2b6xxxxxxxxxxxxxbaaba.xa5xxxxxxxxxxxxxxxf'
-d '@contacts.json'
-X POST
このリクエストでは、'@contacts.json'にサンプル入力データが含まれています。
サンプル入力
{
'contactsList': [
{
'emailAddress': 'bella@example.com',
'phoneNumber': '+1234567890',
'firstName': 'Bella',
'lastName': 'Steve',
'variableOne': 'variable1',
'variableTwo': 'variable2',
'variableThree': 'variable3',
'variableFour': 'variable4',
'variableFive': 'variable5',
'variableSix': 'variable6'
},
{
'emailAddress': 'john@example.com',
'phoneNumber': '+1234567890',
'firstName': 'John',
'lastName': 'Steve'
}
]
}

HTTPSステータスコード

HTTPステータス
メッセージ
説明
200 OK
 
このステータスを受信した場合、APIトリガーが成功したことを意味します。
530
ACCESS_RESTRICTED
配信がトリガー状態ではありません。API要求URLを確認するか、トリガー型の媒体で新しい配信を作成してください。
530
NEED_RECIPIENTS
連絡先が空であるか、無効なSMSアドレスが含まれています。
400
INVALID_REQUEST_METHOD
API URLにアクセスするために無効なHTTPメソッドが指定されています。有効な要求メソッドを指定してください。
401
OAUTH_SCOPE_MISMATCH
クライアントに必要なスコープがありません。有効なスコープで新しいクライアントを作成してください。
530
DISTRIBUTION_DISABLED
指定されたトリガー招待は無効です。
530
INVITATION_LIMIT_REACHED
トリガー有効期限内の招待数の上限に達しました。
530
DAILY_EINVITE_LIMIT_REACHED
1日の招待上限に達しました。
530
EINVITE_BOUNCE_RATE_EXCEEDED
アカウントのバウンス率の上限に達しました。
530
EINVITE_COMPLAINT_RATE_EXCEEDED
アカウントの苦情率の上限に達しました。

Notes

注意点

リフレッシュトークンの取り消し：リフレッシュトークンを取り消すには、ドメイン固有のZoho Accounts URLを使用し、トークン取り消し要求を送信する必要があります。詳細はこちら。
トークンの有効期間：保存できるトークン数と、一度に送信できる要求数には上限があります。詳細はこちら。
配信ごとの1分あたりの要求総数に対するAPI上限は60件です。