Zoho Survey APIを通じたアンケートの配信

概要

Zoho SurveyのAPIを使用すると、連絡先や顧客リストにアンケートを自動で配信することができます。また、Zoho SurveyのAPIを使用すると、さまざまなアプリから特定の条件に基づき、Zoho Surveyのアンケートを配信できます。

使用例

Zoho SurveyのAPIを以下のような場合に活用することができます。

Webサイトで製品を購入した顧客に、製品に関するフィードバックアンケートを送信したい場合。
旅行後に帰国した旅行者から、旅行に関するフィードバックを収集したい場合。
病院での診断後、患者にフィードバックアンケートを送信したい場合。
イベントや展示会終了後、ブースを訪れた見込み客からフィードバックを収集したい場合。
受講者がオンライン講座を受講後、講座や学習体験についてのアンケートを受講者に送信したい場合。
入社後の従業員研修について、フィードバックを収集したい場合。

用語

OAuth：ユーザーのパスワードや認証情報を知らせることなくリソースや情報に安全にアクセス可能な標準のプロトコルです。
クライアント：アンケートを配信するため、Zoho SurveyへAPIリクエストを送信するアプリケーションです。
クライアントID：Zohoにアプリケーションを登録する際に付与される一意のIDです。
クライアントシークレット：Zohoにアプリケーションを登録する際に生成される一意のキーです。セキュリティ上の安全のため、クライアントシークレットは厳重に保管しなければなりません。
認可トークン：アクセストークン／リフレッシュトークンを生成するために使用される一時的なトークンです。組織固有のグラントトークンの生成は一度きりです。
アクセストークン：アンケートへの配信機能にアクセスするため、Zoho Survey APIへ送信されるトークンです。アクセストークンを使用することで、Zoho Survey APIに安全にアクセスできます。各アクセストークンは1時間のみ有効です。また、アクセストークンは設定されたスコープ（アクセス権の範囲）の操作にのみ使用できます。
リフレッシュトークン：新しいアクセストークンを取得するために使用できるトークンです。このトークンは、ユーザーによって取り消されるまで有効です。
API実行数の上限：API実行数の上限とは、同時に実行可能なAPIリクエストの最大数です。

前提条件

Zoho Surveyの有効なユーザー認証情報。
Zoho Survey APIにアクセスするために有効な認証トークンまたはOAuth。
Zoho Surveyのポータルで、メール配信の設定が完了済みであること。

Zoho Survey APIの有効化の手順

Zoho Surveyでメール配信のAPIアクセスを有効にするには、まずZoho Developer Consoleにクライアント（Zoho SurveyのAPIリクエストを送信するアプリ）の登録を行います。

アプリケーションを登録するには

クライアントIDとクライアントシークレットを生成するには、Zoho の開発者コンソールにアプリケーションを登録します。
クライアントIDとクライアントシークレットを生成した後、クライアントの種類に応じて「ZohoSurvey.invitation.CREATE」のスコープを使用し、組織専用の認可トークンを生成します。認可トークンは、独自のクライアントアプリケーションやサーバーベースのアプリケーションの場合にのみ必要です。
生成された認可トークンをコピーします。アプリケーションの種類に応じたクライアントIDとクライアントシークレットの生成方法については、こちらをご覧ください。

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

次に、認可トークンを使用して、ドメイン固有のZohoアカウントURLでアクセストークンとリフレッシュトークンを生成します。

以下は、Zohoのドメインと該当するアカウントURLの一覧です。

米国：https://accounts.zoho.com

オーストラリア： https://accounts.zoho.com.au

EU：https://accounts.zoho.eu

インド：https://accounts.zoho.in

中国：https://accounts.zoho.com.cn

日本： https://accounts.zoho.jp

カナダ：https://accounts.zohocloud.ca

サウジアラビア： https://accounts.zoho.sa

注意：

サーバーベースのアプリケーションの場合、アクセス種類のパラメーターを「offline」に設定し、認証リクエストを送信してください。そうすることで、初回の認証リクエスト時にアクセストークンと共にリフレッシュトークンも受け取りることができます。アクセストークンの有効期限が切れると、リフレッシュトークンを使ってアクセストークンを再生成することができます。
各アクセストークンは、1時間のみ有効です。また、アクセストークンは設定されたスコープ（アクセス権の範囲）の操作にのみ使用できます。
新しいアクセストークンを生成するには、リフレッシュトークンを使用します。リフレッシュトークンには有効期限がないため、アクセストークンの有効期限が切れた際に、アクセストークンを再生成するために使用できます。

メール配信の設定

Zoho Surveyのポータルで、［公開］→［配信］→［メール］→［メールを作成する］の順に移動します。

［送信者情報］セクションで、［条件に基づく連絡先の抽出］ を選択し、［次へ］をクリックします。

アンケートの配信間隔で、［一回のみに配信する］ または［定期的に配信する］を選択します。定期的な配信を選択する場合、条件を実行する間隔を設定する必要があります。

APIリクエストのURLを受信するには、［作成する］をクリックします。 ［公開］→［メール］→［配信済みのアンケート］に移動し、APIの実行履歴を確認できます。

リクエストURLをコピーし、以下のように変数を設定します。

Method Post

Header Authorization：Zoho-oauthtoken e4af2b6xxxxxxxxxxxbaaba

(キー）（値）

Content-Type：application/json

リクエストの本文

パラメーター	データ型	説明
emailAddress*	文字列	連絡先のメールアドレスを指定します。
phoneNumber	文字列	連絡先の電話番号を指定します。
firstName	文字列	連絡先の「名」を指定します。
lastName	文字列	連絡先の「姓」を指定します。
variableOne	文字列	この変数項目を追加することで、追加データを収集できます。
variableTwo	文字列	この変数項目を追加することで、追加データを収集できます。
variableThree	文字列	この変数項目を追加することで、追加データを収集できます。
variableFour	文字列	この変数項目を追加することで、追加データを収集できます。
variableFive	文字列	この変数項目を追加することで、追加データを収集できます。
variableSix	文字列	この変数項目を追加することで、追加データを収集できます。

* 必須項目

注：

POSTリクエストごとに複数の連絡先を追加できます。

サンプルリクエスト

APIを実行するためにcurlコマンドを使用する場合は、以下のサンプルリクエストを参照してください。

curl"https://survey.zoho.com/api/v1/external-private/portals/113436589/departments/soCNLR/surveys/123430000050422385/collectors/123430000050422419/distributions/123430000050460139/email/sendinvitation"

-H "Authorization：Zoho-oauthtoken 1000.e4af2b6xxxxxxxxxxxbaaba.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件です。