API による Zoho Survey のメール招待のトリガー
お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。
概要
Zoho Survey APIを有効にすると、連絡先にアンケートをメールで自動配信できます。どのアプリケーションでも、トリガーに基づくメール配信を使用して、イベント発生時に招待を送信できます。
使用例
Zoho Survey API連携を有効にできるシナリオはこちらです。
- 顧客がECサイトで商品を購入し、販売者が商品配送後に商品フィードバックアンケートを送信したい場合。
- 旅行会社が、旅行者の帰着後に旅行に関するフィードバックを収集したい場合に、API連携を利用できます。
- 病院が、診察後に患者へフィードバックアンケートを送信したい場合。
- イベント後アンケートを送信して、参加者から有用なフィードバックを収集し、イベントに関するインサイトを得たい場合。
- 学習プラットフォームで学生がコースを完了した際に、コースと学習体験に関するフィードバックを収集するためのアンケートを送信できます。
- 従業員が組織に入社した際に、オンボーディング体験アンケートを送信したい場合。
用語。
- OAuth- ユーザーのパスワードを共有することなく、保護されたリソースへの安全なアクセスを提供する業界標準のプロトコルです。
- クライアント- エンドユーザーに代わってトリガー招待にアクセスするために、Zoho Surveyにリクエストを送信するアプリケーションです。
- クライアントID- アプリケーションをZohoに登録した際に受け取る一意の識別子です。
- クライアントシークレット- アプリケーションをZohoに登録した際に生成される一意のキーです。これは機密情報として管理する必要があります。
- グラントトークン- アクセストークンとリフレッシュトークンを生成するために使用する一時トークンです。組織固有のグラントトークンの生成は一度だけ必要です。
- アクセストークン- ユーザーのトリガー招待にアクセスするためにZoho Survey APIへ送信されるトークンです。アクセストークンにより、Zoho Survey APIへ安全かつ一時的にアクセスできます。各アクセストークンは1時間のみ有効で、スコープに記載された一連の操作にのみ使用できます。
- リフレッシュトークン- 新しいアクセストークンを取得するために使用できるトークンです。このトークンは、エンドユーザーによって取り消されるまで無期限で有効です。
- APIレート制限- APIレート制限とは、任意の時点で同時に有効にできるAPI呼び出しの最大数です。
前提条件。
- 有効なZoho Surveyユーザー認証情報。
- Zoho Survey APIにアクセスするための有効な認証トークンまたはOAuth。
- Zoho Surveyポータルでメール配信を設定済みであること。
手順。
APIトリガー招待を有効にするには、まずZoho Developerコンソールにクライアントを登録します。
アプリケーションの登録
- クライアントIDとクライアントシークレットを生成するために、アプリケーションをZoho Developerコンソールに登録します。
- クライアントIDとクライアントシークレットが生成されたら、スコープ「ZohoSurvey.invitation.CREATE」を使用して、クライアントの種類に基づく組織固有のグラントトークンを生成します。グラントトークンは、セルフクライアントやサーバーベースのアプリケーションなど、特定のクライアントでのみ必要です。
- 生成されたグラントトークンをコピーします。さまざまなアプリの種類に応じたクライアントIDとクライアントシークレットの生成については、詳細はこちらをご参照ください。
アクセストークンとリフレッシュトークンの生成
次に、グラントトークンを使用して、ドメイン固有のZoho Accounts URLでアクセストークンとリフレッシュトークンを生成します。
各ドメインと対応するアカウントURLは次のとおりです。
EUの場合：https://accounts.zoho.eu
INの場合：https://accounts.zoho.in
JPの場合：https://accounts.zoho.jp
CA（カナダ）の場合：https://accounts.zohocloud.ca
SA（サウジアラビア）の場合：https://accounts.zoho.sa
メモ。
- サーバーベースのアプリケーションでは、アクセスタイプパラメーターの値を「offline」として認可リクエストを送信します。値がofflineの場合、初回のリクエスト時にアクセストークンとともにリフレッシュトークンを受け取ります。アクセストークンの有効期限が切れたら、リフレッシュトークンを使用して再生成できます。
- 各アクセストークンは1時間のみ有効で、スコープで定義された操作にのみ使用できます。
- 新しいアクセストークンを生成するには、リフレッシュトークンを使用します。リフレッシュトークンに有効期限はありません。アクセストークンの有効期限が切れたら、リフレッシュトークンを使用してアクセストークンを再生成します。
メール配信の作成
- Zoho Surveyポータルで、［公開］タブに移動し、［コレクターを追加］をクリックします。
- Zoho Surveyのメール招待で、［作成］をクリックします。
- ［メールを作成］をクリックします。
- メールテンプレートを作成したら、［次へ］をクリックします。
- 送信者情報ページで、［次へ］をクリックします。
- ［送信先］セクションで、［トリガーに基づく連絡先］を選択し、［次へ］をクリックします。
- トリガーの頻度として、［1回限りの招待］または［定期招待］を選択します。［定期招待］を選択する場合は、トリガーの頻度をスケジュールします。
- APIトリガーURLを取得するには、［作成］をクリックします。成功画面にAPI情報が表示されます。また、API詳細は、いつでも［公開］→［メール］→［トリガー招待］で確認できます。
- リクエストURLをコピーし、以下のように変数を設定します。
メソッド POST
ヘッダー Authorization: Zoho-oauthtoken e4af2b6xxxxxxxxxxxxxbaaba
（キー）（値）
Content-Type: application/json
リクエスト本文。
リクエスト本文。
|
パラメーター
|
データ型
|
説明
|
|
emailAddress*
|
文字列
|
連絡先のメールアドレスを指定します
|
|
phoneNumber*
|
文字列
|
連絡先の電話番号を指定します。
|
|
firstName
|
文字列
|
連絡先の名を指定します。
|
|
lastName
|
文字列
|
連絡先の姓を指定します。
|
|
variableOne
|
文字列
|
この変数項目を追加して、追加データを収集できます。
|
|
variableTwo
|
文字列
|
この変数項目を追加して、追加データを収集できます。
|
|
variableThree
|
文字列
|
この変数項目を追加して、追加データを収集できます。
|
|
variableFour
|
文字列
|
この変数項目を追加して、追加データを収集できます。
|
|
variableFive
|
文字列
|
この変数項目を追加して、追加データを収集できます。
|
|
variableSix
|
文字列
|
この変数項目を追加して、追加データを収集できます。
|
*必須項目
メモ：
1件のPOST要求に複数の連絡先を追加できます。
サンプル要求
APIを実行するcurlコマンドの使用方法については、以下のサンプル要求を参照してください。
-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
|
連絡先が空か、無効なメールアドレスが含まれています。
|
|
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
|
アカウントの苦情率の上限に達しました。
|
注意事項
- リフレッシュトークンの取り消し：リフレッシュトークンを取り消すには、ドメイン固有のZoho Accounts URLを使用し、トークン取り消しリクエストを送信する必要があります。詳細はこちら
- トークンの有効期間：保存できるトークン数と、一度に送信できるリクエスト数には上限があります。詳細はこちら
- 配信ごとの1分あたりの合計リクエスト数に対するAPI制限は60です。