API 上の Viber ビジネス

Viberメッセージを送信する前に、コンプライアンスとガイドラインとメッセージタイプの詳細をよく理解していることを確認してください。

Viber Business Messages APIを使用して、conversational、 promotional、および transactional メッセージをエンドユーザーに送信します。

認証ガイドに従って、NTT CPaaS との接続をセキュリティで保護します。

送信メッセージ [#outbound-messages-business-messages-api]

API を介して次の種類のメッセージを送信できます。

ベーシック

• テンプレート
• テキスト
• 画像
• ビデオ
• ファイル

複合

• テキスト+行動を促すフレーズボタン
• テキスト+画像
• テキスト + 動画
• テキスト + 画像 + コールトゥアクションボタン
• テキスト + 動画 + 行動を促すフレーズのボタン

セキュリティ

• アクティベーションチェック

メッセージテンプレート [#message-template-business-messages-api]

エンドユーザーに送信するトランザクション(情報)メッセージは、Viberによって承認された登録済みテンプレートを使用する必要があります。これらのテンプレートは、事前定義されたメッセージ構造に従い、Viberのガイドラインに従う必要があります。この要件は、Viberビジネスメッセージが利用可能なすべての国に適用されます。

登録済みのメッセージ テンプレートを使用しないトランザクションメッセージを送信すると、標準のプロモーションメッセージ料金が請求されます。

メッセージテンプレートを送信するには、専任のNTT CPaaSアカウントマネージャーにお問い合わせいただくか、 NTT CPaaSお問い合わせフォームから営業チームにお問い合わせください。

プライマリデバイス [#primary-device-business-messages-api]

このセクションは、テキストテンプレートとメッセージテンプレートにのみ適用されます。

エンドユーザーは、複数のデバイスにViberをインストールすることができます。例:スマートフォン、タブレット、デスクトップ。スマートフォンまたはタブレットのいずれかがプライマリデバイスであり、その他はセカンダリデバイスです。

エンドユーザーに送信したViberメッセージは、すべてのデバイスに配信されます。エンド ユーザーのプライマリ デバイスにのみメッセージを強制的に配信する場合は、API リクエストで toPrimaryDeviceOnly パラメーターを true に設定します。

アクティベーションチェック [#activation-check-business-messages-api]

アクティベーションチェックメッセージタイプは、Viber Business Messagesを介して機密情報を送信するときにセキュリティレイヤーを追加します。メッセージを配信する前に、Viber は受信者が新しいデバイスで最近 Viber をアクティベートしたかどうかを確認します。

• 最近のアクティベーションが検出されない場合、受信者は信頼されていると見なされ、メッセージはプライマリデバイスにのみ配信されます。メッセージはセカンダリ デバイスには送信されません。
• 最近のアクティブ化が検出された場合、受信者は信頼できないと見なされ、メッセージは配信されません。ビジネス要件に従ってシナリオを処理できるように、特定のエラー コードが返されます (たとえば、別のメッセージの種類を使用してメッセージを送信したり、別の方法で受信者を確認したりします)。

このメッセージ タイプは、Android と iOS (プライマリ デバイスのみ) でテキストのみのメッセージをサポートします。

次の応答コードは、このメッセージの種類に固有です。

リクエストパラメータの詳細については、「 Viberメッセージの送信 APIリファレンス」を参照してください。

推奨 事項 [#recommendations-business-messages-api]

• 書式設定されたメッセージを送信するには、テキスト文字列にマークダウンを追加します。テキスト メッセージ > テキストの書式設定 セクションを参照してください。メッセージテンプレートでテキストの書式設定を使用することはできません。
• API を介して送信されたメディア URL が解析され、コンテンツが正しく表示されるようにするには、次のガイドラインに従います。
  • 要求では、セキュリティで保護された HTTPS リンクのみを使用します。
  • 画像の URL が CAPTCHA で保護されていないことを確認します。
• 画像には、.bmp、.gif、.jpg、.jpeg、.png、.svg、.webp のファイル形式を使用します。詳細な仕様は、イメージメッセージの項目を参照してください。
• ビデオには、.3gp、.m4v、.mov、.mp4 のファイル形式を使用します。詳細な仕様は、ビデオメッセージの項目を参照してください。
• ファイルには、.csv、.doc、.docx、.dot、.dotx、.eps、.fods、.fodt、.info、.odf、.ods、.odt、.pdax、.pdf、.rtf、.txt、.xls、.xlsx、.xltx、.xps、xlsm。詳細な仕様は、ファイルメッセージの項目を参照してください。

追加機能の恩恵を受けたい場合に備えて、送信リクエストに追加オプションを追加することを忘れないでください。

メッセージ・オプション [#message-options-business-messages-api]

追加のメッセージ オプションを API 要求に適用できます。

一括メッセージ [#bulk-messages-business-messages-api]

1 つの API リクエストで複数のテキストメッセージまたはメッセージテンプレートを送信できます。

メッセージのスケジューリング [#scheduling-messages-business-messages-api]

すべての通信をスケジュールできます。開始日、時刻、タイムゾーンを設定できます。この機能は、夜間に顧客の邪魔をしたくない場合や、最適なコンバージョンのために特定の期間にのみメッセージを送信したい場合に便利です。

追加のスケジュールオプションは、送信速度制限を設定することです。たとえば、メッセージを一括送信して、より長い期間にわたってメッセージを配信する場合、送信速度を制限できます。この機能は、ディスパッチされたメッセージに埋め込まれた行動喚起に受信者が反応することが予想される場合に役立ちます。そうすることで、エンドユーザーからの応答の流入でシステムやエージェントを圧倒することを回避し、運用上の負担を回避できます。定期的に送信される**メッセージの数(量)**を設定できます。使用可能な時間単位は、分、時間、日です。

また、メッセージが配信されない特定のメッセージ配信ウィンドウを設定することもできます。開始時刻(時/分)、終了時刻(時/分)、曜日を設定できます。時刻は UTC タイムゾーンで表されます。

有効期間 [#validity-period-business-messages-api]

メッセージには、システムが配信を試みる特定の期間があります。たとえば、オーディエンスにメッセージを送信したいときに、一部のユーザーが携帯電話の電源を切っている場合、システムは有効期間が経過するまでこれらのユーザーへの配信を再試行します。デフォルトと最大有効期間は 48 時間です。要求ごとに設定する必要はありません。より短い期間を設定する場合は、有効期間で定義します。使用可能な時間単位は、秒、分、時間です。デフォルト値は minutes です。

SMSフェイルオーバー [#sms-failover-business-messages-api]

定義された期間内にViberメッセージが終了ユーザーに到達しない場合に備えて、SMSへのフェールオーバーオプションを追加します。また、SMSメッセージの有効期間を設定することもできます。

プラットホーム [#platform-business-messages-api]

Viber APIは、CPaaS X(/cpaas-x/applications-and-entities)とシームレスに連携します。これにより、ニーズに合った方法で構成とリソースをより柔軟に管理できます。CPaaS X の詳細については、CPaaS X ドキュメント を参照してください。

Webhook (英語) [#webhooks-business-messages-api]

webhooks > delivery > url パラメータ オプションは、ユーザーがAPI応答を受信するURLを設定できるようにする場合に使用します。API 要求の Webhook パラメーターの下に URL を定義します。

URL の短縮と追跡 [#url-shortening-and-tracking-business-messages-api]

URL を短縮し、これらの URL のクリック数を追跡できます。URLトラッキングを有効にしなくても、URL短縮を有効にすることができます。URL トラッキングを有効にするには、URL 短縮を有効にする必要があります。

URL の短縮と追跡は、次のメッセージの組み合わせでサポートされています。

• テキストのみ: テキスト内の URL
• テキスト+画像:テキスト内のURL
• テキスト + 動画: テキスト内の URL
• テキスト + CTA ボタン: テキスト内の URL と CTA ボタン
• 画像 + テキスト + CTA ボタン: テキスト内の URL と CTA ボタン
• 動画 + テキスト + CTA ボタン: テキスト内の URL と CTA ボタン
• ファイル: メディア URL

URL 短縮 [#url-shortening-business-messages-api]

URL 短縮を使用して、エンド ユーザーと共有する URL の長さを短くします。URL は、メッセージ本文に追加すると短縮されます。

次の種類の URL 短縮を使用できます。

URL トラッキング [#url-tracking-business-messages-api]

URL のクリック数を追跡できます。

trackingUrl を指定し、trackClicks を true に設定します。

エンド ユーザーがメッセージ本文の URL をクリックすると、イベントが NTT CPaaS に返されます。このイベントはレポートと通知に記録され、クリック通知が届きます。

クリック通知で渡されるデータの構造を以下に示します。

受信メッセージ [#inbound-messages-business-messages-api]

受信メッセージは、双方向通信に API を使用するとリアルタイムで転送されます。メッセージは、NTT CPaaS ソリューションで Viber アカウントを設定したときに指定したエンドポイントに転送されます。

NTT CPaaS Web インターフェイスからのメッセージを API エンドポイントに転送できるようにするには、関連するアクセス許可を API エンドポイントに付与する必要があります。追加の承認ヘッダーを使用して、接続をセキュリティで保護します。

エンド ユーザーから次の種類のメッセージを 受信 できます。

• テキスト
• 画像
• ビデオ
• ファイル

エンドユーザーは、次のファイルタイプを送信できます。

• 画像 (.jpg、.jpeg、.png、.bmp、.gif、.svg、.webp): サイズ制限はありません。GIF は最大 24 MB まで許可されます。
• ビデオ (.avi、.wmv、.mov、.mp4、.m4v、.3gpp、.3gpp2、.asf、.mkv、.mp2ts、.webm): 最大 100 MB。
• ファイル(.doc、.docx、.rtf、.dot、.dotx、.odt、.odf、.fodt、.txt、.info、.pdf、.xps、.pdax、.eps、.xls、.xlsx、.ods、.fods、.csv、.xlsm、.xltx):最大200MB。

NTT CPaaS は、これらのファイルを 30 日間保存します。この期間を過ぎると、インバウンド・メッセージ・ログ内のファイルに関連付けられた URL にはアクセスできなくなります。

レポート [#reports-business-messages-api]

メッセージが正常に送信されたら、送信されたメッセージのステータスを確認できます。次のレポートは、定義されたエンドポイントに転送されます。

• 配信レポート
• 既読メッセージレポート

配信レポートと表示レポートをリアルタイムで URL に転送できます。この機能を設定するには、NTT CPaaS アカウント マネージャーに URL を提供してください。

(オプション)エンドポイントは、メッセージのAPIリクエストの webhooks > delivery > url パラメーターで定義できます。このエンドポイントを定義しない場合、レポートはプラットフォームで定義されているエンドポイントに転送されます。