API 上の Viber ビジネス

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

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

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

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

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

テンプレート
テキスト
画像
ビデオ
ファイル
テキスト+行動を促すフレーズボタン
テキスト+画像
テキスト + 動画
テキスト + 画像 + コールトゥアクションボタン
テキスト + 動画 + 行動を促すフレーズのボタン

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

情報

このメッセージの種類は、ロシア、ベラルーシ、ウクライナでのみ使用できます。

ロシア、ベラルーシ、ウクライナでは、エンドユーザーに送信するトランザクション(情報)メッセージは、Viberによって承認された登録済みテンプレートを使用する必要があります。これらのテンプレートは、事前定義されたメッセージ構造に従い、Viber ガイドラインに従う必要があります。

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

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

ビジネスがこのセクションに記載されている国のいずれかに拠点を置いていて、これらの国以外の顧客にトランザクションメッセージを送信する場合は、2 つのアカウント (1 つは上記の国内の顧客との通信用、もう 1 つは他のすべての国の顧客用) を使用する必要があります。

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

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

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

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

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

書式設定されたメッセージを送信するには、テキスト文字列にマークダウンを追加します。送信メッセージ > テキスト > テキストの書式設定 セクションを参照してください。メッセージテンプレートでテキストの書式設定を使用することはできません。
API を介して送信されたメディア URL が解析され、コンテンツが正しく表示されるようにするには、次のガイドラインに従います。
- 要求では、セキュリティで保護された HTTPS リンクのみを使用します。
- 画像の URL が CAPTCHA で保護されていないことを確認します。
画像には、.jpg、.jpeg、.png、.bmp、.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]

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

json

2 "SendAt": 2015-07-07T17:00:00.000+01:00

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

json

2 "sendingSpeedLimit": {

3 "amount": 30,

4 "timeUnit": "HOUR"

5 }

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

json

2 "deliveryTimeWindow": {

3 "days": [

4 "MONDAY",

5 "TUESDAY",

6 "WEDNESDAY",

7 "THURSDAY",

8 "FRIDAY",

9 "SATURDAY",

10 "SUNDAY"

11 ],

12 "from": {

13 "hour": 6,

14 "minute": 0

15 },

16 "to": {

17 "hour": 15,

18 "minute": 30

19 }

20 }

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

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

json

2 "validityPeriod": {

3 "amount": 30,

4 "timeUnit": "MINUTES"

5 }

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

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

json

2 "smsFailover": {

3 "sender": "41793026726",

4 "text": "Failover message text",

5 "validityPeriod": {

6 "amount": 2,

7 "timeUnit": "HOURS"

8 }

9 }

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

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

json

2 "platform": {

3 "entityId": "priorityCustomer",

4 "applicationId": "clientTestEnvironment"

5 }

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

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

json

2 "webhooks": {

3 "delivery": {

4 "url": "https://www.example.com/viberbm"

5 },

6 }

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 全体を短縮します。	元の URL のメッセージ: ビジネスメッセージの詳細については、以下を参照してください。 `../viber/business-messages'</div>.</i></li></ul><br /><br /><b>既定の短縮 URL のメッセージ</b>:<ul><li><i>ビジネスメッセージの詳細については、以下を参照してください。 <div style={{ fontsize: '14px' }}>`https://rrj.nu/x5T3jd2Y` .
カスタムドメイン短縮 URL		カスタムドメインを保持するように URL を短縮します。カスタムドメイン URL短縮は、カスタムドメイン(サブドメイン)を含む URL に対してのみ使用できます。 `www.dev.infobip.com` . カスタムドメイン URL短縮は、プライマリドメインを含む URL には使用できません `www.infobip.com` .	元の URL のメッセージ: ビジネスメッセージの詳細については、以下を参照してください。 `https://www.dev.infobip.com/docs/api/channels/viber` . 既定の短縮 URL のメッセージ: ビジネスメッセージの詳細については、以下を参照してください。 `https://www.dev.infobip.com/x5T3jd2Y` .
プロトコルの削除	プライマリドメインを含む URL	URL から 'http' または 'https' プレフィックスを削除し、URL を短縮します。 URL にプライマリドメインが含まれている場合は、URL 全体が短縮されます。	元の URL のメッセージ: ビジネスメッセージの詳細については、以下を参照してください。 `../viber/business-messages'</div>.</i></li></ul><br /><br /><b>プロトコルが削除され、URL が短縮されたメッセージ</b>:<ul><li><i>ビジネスメッセージの詳細については、以下を参照してください。 <div style={{ fontsize: '14px' }}>`rrj.nu/x5T3jd2Y` .
プロトコルの削除	カスタムドメイン (サブドメイン) を含む URL	URL から 'http' または 'https' プレフィックスを削除し、URL を短縮します。 URL にカスタムドメイン (サブドメイン) が含まれている場合、URL はカスタムドメインを保持するように短縮されます。	元の URL のメッセージ: ビジネスメッセージの詳細については、以下を参照してください。 `https://www.dev.infobip.com/docs/api/channels/viber` . プロトコルが削除され、URL が短縮されたメッセージ: ビジネスメッセージの詳細については、以下を参照してください。 `www.dev.infobip.com/x5T3jd2Y` .

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

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

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

json

2 {

3 ...

4 "tracking": {

5 "shortenUrl": true,

6 "trackClicks": true,

7 "trackingUrl": "https://webhook.site/077a5470-42f9-471f-a7f2-c67d5b *",

8 "removeProtocol": true,

9 "customDomain": "m.infobip.com"

10 }

11 }

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

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

json

2 {

3 "notificationType": "CLICKED",

4 "recipient": "38591 ***",

5 "url": "https://www.infobip.com",

6 "sendDateTime": 1603440470723,

7 "messageId": "303440456940035 *",

8 "recipientInfo": {

9 "deviceType": "Phone",

10 "os": "Android 10",

11 "deviceName": "Unknown"

12 }

13 }

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

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

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

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

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

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

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

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

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

オムニ API

API 経由で Viber メッセージを送信するには、シナリオを設定する必要があります。 APIリファレンスを参照してください。

シナリオの作成 [#create-scenario-omni-api]

最初のステップは、 OMNIシナリオを作成することです。OMNIシナリオ構成で、個別に実行されるOMNIステップを定義します。

Viber 送信者 ("channel": "VIBER" フロー) は、アクティベーションプロセス中に提供された電話番号、つまりアクティベーションされた国際形式の電話番号 (385981234567 など) を使用します。安全な接続が必要です。NTT CPaaS 資格情報の Base64 ハッシュの組み合わせ、API キー (推奨)、または トークン を使用します。手順については、API 認証を参照してください。

リクエスト例

json

2 {

3 "from": "InfoSMS",

4 "channel": "SMS"

5 },

6 {

7 "from": "3045",

8 "channel": "VIBER"

9 }

シナリオは、初期段階でのみ作成します。メッセージを送信するたびにこの手順を繰り返す必要はありません。シナリオは、フェールオーバーシナリオで新しいチャネルを追加するとき、または送信者を変更するときに作成します。

これを既定のシナリオとして使用するには、既定値を true に設定します。この時点から、scenarioKeyはメッセージ送信時の必須パラメータではなくなります。

json

2 {

3 "from": "InfoSMS",

4 "channel": "SMS"

5 },

6 {

7 "from": "3045",

8 "channel": "VIBER"

9 }

key パラメーターは、メッセージの送信時に使用されるため、格納します。

既定のシナリオ [#default-scenario-omni-api]

アカウント用に作成した最初のシナリオが、既定のシナリオとして使用されます。これは、別のシナリオを既定のシナリオとして設定するまで使用されます。これを変更するには、既定値を true に設定します。

回答形式

成功すると、応答ヘッダーのHTTPステータスコードが201 Createdになり、シナリオが作成されます。

承認なしでシナリオを作成しようとすると、401 Unauthorizedエラーが表示されます。

この方法を短期間に頻繁に使用すると、ステータスコード429 Too Many Requestsが表示されます。これにより、メソッドを誤用して多くの不要なシナリオが作成されるのを防ぐことができます。

シナリオを作成したら、シナリオキーを介していつでも参照し、OMNIメッセージの送信に何度でも再利用できます。OMNIメッセージごとに新しいシナリオを作成する必要はありません。

OMNIメッセージの送信 [#sendomni-messages-omni-api]

シナリオの作成セクションの説明に従ってOMNIシナリオ(keyパラメーターで識別)を作成したら、定義されたViberおよびSMS通信チャネルを介してOMNIメッセージを送信する準備が整います。

定義された phoneNumber に Viber メッセージを送信します。
なんらかの理由で、Viber アプリケーションでメッセージが拒否された場合、またはエンドユーザーに Viber アプリケーションがインストールされていない場合、メッセージは SMS 経由で送信されます。

OMNI メッセージを送信するには、高度な API メソッドを使用できます。 API のドキュメントを参照してください。

設定する必要があるパラメータは、scenarioKey、phoneNumber、および各通信チャネルの特定のテキストです。

OMNIのデフォルトの有効期間は、ViberメッセージとSMSメッセージの両方で48時間です。

応答例

json

2 {

3 "to":{

4 "phoneNumber": "41793026727"

5 }

6 }

7 ],

8 "viber": {

9 "text": "This Viber message will be delivered to Viber application on the user device."

10 },

11 "sms": {

12 "text": "This is the SMS failover message"

13 }

Viber経由でリッチメッセージを送信する [#send-rich-messages-over-viber-omni-api]

テキスト、画像、CTAボタンを含むViberメッセージを送信する方法は次のとおりです。各通信チャネルのカスタム有効期間を設定できます。

テキスト、画像、またはボタンの任意の組み合わせが許可されます。buttonUrl と buttonText は必須です。

json

2 {

3 "to":{

4 "phoneNumber": "41793026727"

5 }

6 }

7 ],

8 "viber": {

9 "text": "This is the message which will be displayed in Viber Application. It can contain up to 1000 characters. ",

10 "imageURL": "http://www.infobip.com/infobip-logo.png",

11 "buttonText": "More information",

12 "buttonURL": "http://www.infobip.com/",

13 "isPromotional": true,

14 "validityPeriod":1

15 },

16 "sms": {

17 "text": "This text will be received via SMS if Viber message is not delivered.",

18 "validityPeriod":1

19 }

サポートされている画像形式: .jpeg、.jpg、.png。絵文字は、APIを介してViberチャネルを介して送信することもでき、エンドユーザーエクスペリエンスを向上させます。

SMSへのフェイルオーバー [#failover-to-sms-omni-api]

定義された期間内にViberメッセージが終了ユーザーに到達しない場合に備えて、SMSへのフェールオーバーオプションを追加します。フェイルオーバー・オプションは、すべてのメッセージ・タイプに適用できます。

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

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

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

推奨事項 [#recommendations-omni-api]

書式設定されたメッセージを送信するには、テキスト文字列にマークダウンを追加します。送信メッセージ > テキスト > テキストの書式設定 セクションを参照してください。メッセージテンプレートでテキストの書式設定を使用することはできません。
API を介して送信されたメディア URL が解析され、コンテンツが正しく表示されるようにするには、次のガイドラインに従います。
- 要求では、セキュリティで保護された HTTPS リンクのみを使用します。
- 画像の URL が CAPTCHA で保護されていないことを確認します。
画像には、.jpg、.jpeg、.png、.bmp、.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。詳細な仕様については、ファイルの送信メッセージ>を参照してください。

配信レポート [#delivery-reports-omni-api]

高度な API メソッドを使用してメッセージを正常に送信したら、OMNI レポートメソッドを使用して送信されたメッセージのステータスを確認できます。

最も簡単な方法は、クエリパラメーターなしでメソッドを使用することです。その場合、応答には特定のアカウントに送信されたすべてのメッセージが含まれます。

応答には、次の例に示すように、拒否されたメッセージと配信されたメッセージの両方が含まれます。

応答

json

2 {

3 "results":[

4 {

5 "messageId":"1215f543ab19-345f-adbd-12ad31451ed25f35",

6 "to":"41793026731",

7 "messageCount": 1,

8 "sentAt":"2016-02-23T17:41:11.833+0100",

9 "doneAt":"2016-02-23T17:41:11.843+0100",

10 "mccMnc":"22801",

11 "price":{

12 "pricePerMessage":0.0104,

13 "currency":"EUR"

14 },

15 "status":{

16 "groupId":2,

17 "groupName":"UNDELIVERABLE",

18 "id":9,

19 "name":"UNDELIVERABLE_NOT_DELIVERED",

20 "description":"Message sent not delivered"

21 },

22 "error":{

23 "groupId":1,

24 "groupName":"HANDSET_ERRORS",

25 "id":6,

26 "name":"EC_ABSENT_SUBSCRIBER_SM",

27 "description":"Absent Subscriber",

28 "permanent":false

29 },

30 "channel": "VIBER"

31 },

32 {

33 "messageId":"2315d543441c-335f-1d3d-142d31451ed25f35",

34 "to":"41793026731",

35 "sentAt":"2016-06-23T17:40:31.773+0100",

36 "doneAt":"2016-06-23T17:40:31.787+0100",

37 "messageCount":1,

38 "mccMnc":"22801",

39 "price":{

40 "pricePerMessage":0.01,

41 "currency":"EUR"

42 },

43 "status":{

44 "groupId":3,

45 "groupName":"DELIVERED",

46 "id":5,

47 "name":"DELIVERED_TO_HANDSET",

48 "description":"Message delivered to handset"

49 },

50 "error":{

51 "groupId":0,

52 "groupName":"OK",

53 "id":0,

54 "name":"NO_ERROR",

55 "description":"No Error",

56 "permanent":false

57 },

58 "channel": "SMS"

59 }

60 ]

61 }

すべての API ステータスとエラーコードの完全なリストについては、応答ステータスとエラーコードの記事を参照してください。

備考

配信レポートを URL にリアルタイムで転送することもできます。その場合は、専任のアカウントマネージャーにURLを提供すると、アカウントマネージャーが設定してくれます。

リアルタイム配信レポート [#real-time-delivery-reports-omni-api]

URL にリアルタイムで転送される配信レポートの形式は、OMNI レポートメソッドを使用して取得されるレポートとは異なります。

json

2 {

3 "results": [{

4 "bulkId": "",

5 "price": {

6 "pricePerMessage": 0,

7 "currency": "EUR"

8 },

9 "status": {

10 "id": 5,

11 "groupId": 3,

12 "groupName": "DELIVERED",

13 "name": "DELIVERED_TO_HANDSET",

14 "description": "Message delivered to handset"

15 },

16 "error": {

17 "id": 0,

18 "name": "NO_ERROR",

19 "description": "No Error",

20 "groupId": 0,

21 "groupName": "OK",

22 "permanent": false

23 },

24 "messageId": "fb469d73-d362-463f-b30f-1e959b53badc",

25 "doneAt": "2019-04-09T16:01:56.494-0300",

26 "messageCount": 1,

27 "sentAt": "2019-04-09T16:00:58.647-0300",

28 "to": "41793026731",

29 "channel": "VIBER"

30 }]

31 }

API 上の Viber ビジネス

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

オムニ API

シナリオの作成 [#create-scenario-omni-api]

既定のシナリオ [#default-scenario-omni-api]

OMNIメッセージの送信 [#sendomni-messages-omni-api]

Viber経由でリッチメッセージを送信する [#send-rich-messages-over-viber-omni-api]

SMSへのフェイルオーバー [#failover-to-sms-omni-api]

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

推奨 事項 [#recommendations-omni-api]

配信レポート [#delivery-reports-omni-api]

リアルタイム配信レポート [#real-time-delivery-reports-omni-api]

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

推奨事項 [#recommendations-omni-api]