NotifyClient - クライアント

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：18分

    • NotifyClient API には、Web ブラウザからのコールの発信や受信など、通知テレフォニー機能を使用できるようにするメソッドが用意されています。

    いくつかの NotifyClient メソッドは、コールバック関数をパラメーターとして受け取ります。NotifyClient メソッドの呼び出しは非同期的に行われるため、これらのメソッドは値を直接返すことができません。コールバック関数を使用し、変数の割り当てや他の API 呼び出しなどを行うことで、返されたデータを解析します。

    NotifyClient - Client(オブジェクト notifyConfig, ブーリアン initializeVendorClientLazily)

    新しい Notify WebRTC クライアントオブジェクトをインスタンス化します。

    表 : 1. パラメーター
    名前 タイプ 説明
    initializeVendorClientLazily ブーリアン setCallerId() メソッドで渡された autoSelectVendorCallback 関数を使用して、発信者の関連ベンダーを自動的に設定するかどうかを示すフラグ (notifyConfig.vendor をコンストラクターで定義する必要なし)。
    • false：デフォルト。autoSelectVendorCallback 関数を使用して発信者のベンダーを設定しない。ベンダーをコンストラクターで設定する必要あり。
    • true：発信者 ID が設定されている場合は、autoSelectVendorCallback 関数を使用してベンダーを定義します。
    notifyConfig オブジェクト Notify WebRTC クライアントの構成設定を含む JSON オブジェクト。
    notifyConfig.autoLoadScriptResource ブーリアン ベンダークライアントが必要とするコア JS ライブラリーのロード方法を示すフラグ。
    • false：デフォルト。ベンダー固有のコードを使用して、必要なベンダー JS ライブラリーをロードします (下位互換性を有効にします)。
    • true：notifyClient.js を使用してコア JS ライブラリーをロードします。
    notifyConfig.callerId 数字 使用する登録済みの Notify の番号。この値を直接設定しないでください。この値を設定するには、メソッド notifyClient.setCallerID() を使用します。
    notifyConfig.forceRefreshToken ブーリアン 期限切れのクライアントトークンを自動更新するかどうかを示すフラグ。
    • false：クライアントトークンが期限切れになったときに自動的に更新しない。
    • true：デフォルト。クライアントトークンが期限切れになったときに自動的に更新する。
    notifyConfig.skipParentId ブーリアン 着信コールの onIncoming 発信者をすぐに呼び出すかどうかを示すフラグ。
    • false：デフォルト。onIncoming イベントハンドラーをすぐに呼び出さない。
    • true: onIncoming イベントハンドラーをすぐに呼び出す。別のコールが進行中で、そのコールを発生させたのが <Dial><Client> TwiML であった場合、このフラグを設定するとシステムはバックエンドを自動ポーリングします。この自動ポーリングによって親の notify_call 参照が取得されます。
    notifyConfig.vendor 定数 発信者が属するベンダー。
    • SNC.Notify.Vendor.TWILIO_DIRECT
    • SNC.Notify.Vendor.TWILIO (廃止済みの古い Twilio ドライバー)

    次の例では、NotifyClient コンストラクターを作成し、さまざまなイベントリスナーを登録して、クライアントドライバーを初期化する方法を示します。

    jQuery(function () {

  var notifyConfig = {
    autoLoadScriptResources: true // This will take care of auto loading the JS resources needed by the client (if any)
  };
  var client = new SNC.Notify.Client(notifyConfig, true); // The second argument ensures that the proper vendor for the given number is auto determined
  client.setCallerId('valid_notify_long_number', function () {
    // This is called after the vendor has been determined.

    if (!notifyConfig.vendor) // Means this number has no compatible vendor
      return;

    client.addEventListener(SNC.Notify.STD_EVENTS.ONLINE, function () {
      // Ability to call is available
    });
    client.addEventListener(SNC.Notify.STD_EVENTS.OFFLINE, function () {
      // Ability to call is _not_ available right now
    });
    client.addEventListener(SNC.Notify.STD_EVENTS.ERROR, function (msg, code) {
      // Some error happened
    });
      //... register other event handlers here
      //Show UI elements which can be used to invoke client.call() and other APIs
    client.init(); // This is important to call this.
    });
});

    NotifyClient - addEventListener(文字列 event, 関数 fn)

    Notify クライアントで変更をリスンするイベントハンドラーを登録します。

    このメソッドを使用すると、複数のリスナーを登録できます。各リスナーは個別のメソッド呼び出しである必要があります。

    表 : 2. パラメーター
    名前 タイプ 説明
    イベント 文字列 リスンするイベントの名前。

    文字列を渡す代わりに、SNC.Notify.STD_EVENTS で定義されている定数を使用します。

    • CALL_START：コールが開始され、進行中です。
    • CALL_CANCEL：発信者がコールをキャンセルしました。
    • CALL_INIT：WebRTC がコールに接続されています (着信または発信)。
    • CALL_DISCONNECT：現在のコールが切断されました。
    • ERROR：エラーが発生しました。パラメーター：message(文字列)、errCode(文字列)
      • message：表示するエラーメッセージ。
      • errCode：オプションです。関連するエラーコード。
    • INCOMING_CALL：コールが着信しています。パラメーター：from(文字列)、to(文字列)、callId(文字列)、parentId(文字列)、sysId(文字列)、isFromClient(ブーリアン)
      • from：発信者の電話番号。
      • to：着信した電話番号。
      • callId：コールの SID。
      • parentId：親 notify_call の参照。skipParentId が true に設定されている場合、このパラメーターは渡されません。
      • sysId：WebRTC 間の呼び出しのみ。発信者の一意の識別子 (sys_id)。
      • isFromClient：WebRTC 間の呼び出しのみ。コールが別の WebRTC クライアントからのものかどうかを示すフラグ。
    • CALL_MUTE：クライアントはミュートされています。
    • CALL_UNMUTE：クライアントはミュート解除されています。
    • OFFLINE：WebRTC セッションがアクティブではありません。
    • ONLINE：WebRTC セッションの準備ができています。init() メソッドを呼び出した後に設定する必要があります。
    表 : 3. 返される内容
    タイプ 説明
    関数 リスナーを登録解除するために使用する関数。

    この例では、複数のリスナーを登録する方法を示します。

    jQuery(function () {

  var notifyConfig = {
    autoLoadScriptResources: true // This will take care of auto loading the JS resources needed by the client (if any)
  };
  var client = new SNC.Notify.Client(notifyConfig, true); // The second argument ensures that the proper client for the given number is auto determined
  client.setCallerId('valid_notify_long_number', function () {
    // This is called after the client has been determined.

    if (!notifyConfig.vendor) // Means this number has no compatible client
      return;

    client.addEventListener(SNC.Notify.STD_EVENTS.ONLINE, function () {
      // Ability to call is available
    });
    client.addEventListener(SNC.Notify.STD_EVENTS.OFFLINE, function () {
      // Ability to call is _not_ available right now
    });
    client.addEventListener(SNC.Notify.STD_EVENTS.ERROR, function (msg, code) {
      // Some error happened
    });
      //... register other event handlers here
     
    client.init(); // This is important to call this.
    });
});

    この例では、リスナーを登録解除する方法を示します。

    var dereg = notifyClient.addEventListener(SNC.Notify.STD_EVENTS.ONLINE, function () {
 ... 
 }); 
 dereg(); 
  // The event listener function is no longer triggered.

    NotifyClient - call(オブジェクト identifier)

    指定された電話番号、または指定されたユーザーに関連付けられた電話番号に電話をかけます。

    注:
    コールや接続のステータスを確認するときは必ず、SNC.Notify.Status によって提供される定数と比較してください。
    表 : 4. パラメーター
    名前 タイプ 説明
    identifier オブジェクト 発信先の電話番号と WebRTC ユーザーの sys_id のいずれかを含む JSON オブジェクト。ユーザーの sys_id を渡すと、ブラウザー間通信を介してコールが行われます。

    ユーザーの sys_id は、Notify WebRTC セッションテーブルから取得できます。

    注:
    電話番号とユーザーの sys_id の両方を指定すると、メソッドでは電話番号のみが使用されます。
    表 : 5. 返される内容
    タイプ 説明
    なし

    この例では、関数のパラメーターとして電話番号を渡す方法を示します。

    notifyClient.call({
    phoneNumber: "+18001112223"
});

    この例では、関数のパラメーターとしてユーザーレコードの sys_id を渡す方法を示します。

    notifyClient.call({
    userId: "6816f79cc0a8016401c5a33be04be441"
});

    この例では、ボタンクリックのハンドラーを示します。

    $j("#pickupCallBtn").on("click", function() {
	notifyClient.hangupCall();
});

    この例では、イベントハンドラーを示します。

    onConnect: function(status) {  
  // webRTC receives a call connection event (incoming or outgoing).
  if (status == SNC.Notify.Status.OPEN) {
    setStatus(getTimeStamp() + " -- Successfully established call");
    showHangupButton();
  }
},

    NotifyClient - destroy()

    現在の Notify クライアントを強制終了して使用不可にします。

    表 : 6. パラメーター
    名前 タイプ 説明
    なし
    表 : 7. 返される内容
    タイプ 説明
    なし

    NotifyClient - forwardCall(オブジェクト argument)

    進行中の着信または発信電話を別の電話番号または別の WebRTC クライアントに転送します。

    表 : 8. パラメーター
    名前 タイプ 説明
    argument オブジェクト コールを電話番号または WebRTC クライアント (ユーザーの sys_id) に転送するために必要な情報を含む JSON オブジェクト。この sys_id は、Notify WebRTC セッションテーブルから取得できます。
    表 : 9. 返される内容
    タイプ 説明
    なし

    この例では、コールを別の電話番号に転送する方法を示します。dtmf 属性を使用すると、DTMF ダイヤルトーンを受信番号に送信できます。

    var arg = {
    type: "number",
    id: "+17012345678",
    dtmf: "1234"
}
client.forwardCall(arg);

    この例では、コールを別の Notify クライアントに転送する方法を示します。

    var arg = {
    type: "userId",
    id: "6816f79cc0a8016401c5a33be04be441"
}
client.forwardCall(arg);

    NotifyClient - getAvailableClients(関数 callback)

    コールを受けられるクライアントのリストを返します。

    このメソッドは、現在のクライアントをリストから除外します。同等の Notify-getAvailableClients() メソッドではユーザーをフィルタリングしません。

    表 : 10. パラメーター
    名前 タイプ 説明
    callback 関数 クライアントのリストの解析に使用する関数。この関数は、次の形式の JSON オブジェクトのアレイであるパラメーターを 1 つだけ受け入れます。
    [{
    sys_id: "...",  // user's sys_id
    name: "..." // user's name
}]
    表 : 11. 返される内容
    タイプ 説明
    なし

    NotifyClient - getParentId(文字列 callId, 関数 callback)

    指定されたコール識別子の親コール識別子を返します (存在する場合)。

    電話通信プロバイダーによっては、親コール識別子が返されるまでに遅延が発生する場合があります。そのため、コールバック関数を提供する必要があります。

    表 : 12. パラメーター
    名前 タイプ 説明
    callId 文字列 親コール識別子を返す対象となるコールの一意の識別子。
    callback 関数 数回試行しても識別子を取得できなかった場合に、親コール識別子またはエラーメッセージのいずれかを含む JSON オブジェクトを取得する関数。
    表 : 13. 返される内容
    タイプ 説明
    文字列 親コール識別子。

    この例では、このメソッドを使用して親コール識別子を取得する方法を示します。

    notifyClient.getParentId( callId, function(jsonObj) {} );

    この例は、jsonObj パラメーターの内容を示します。

    {
	parentId: "xyz",
	error: "msg"
}

    NotifyClient - getStatus()

    現在のコールの正規化されたステータスを返します。

    表 : 14. パラメーター
    名前 タイプ 説明
    なし
    表 : 15. 返される内容
    タイプ 説明
    文字列 コールの現在のステータス。電話通信プロバイダーの API によって返された値は、返されたドライバー値を SNC.Notify.Status で定義されている同等の値に置き換えることで正規化されます。

    この例では、現在の Notify クライアントのステータスを取得する方法を示します。

    clientStatus = notifyClient.getStatus();

    NotifyClient - hangupCall()

    現在のコールを終了します。

    表 : 16. パラメーター
    名前 タイプ 説明
    なし
    表 : 17. 返される内容
    タイプ 説明
    なし

    この例では、コールを終了する方法を示します。

    $j("#pickupCallBtn").on("click", function() {
    notifyClient.hangupCall();
});

    NotifyClient - init()

    クライアントドライバーを初期化します。

    たとえば、Twilio クライアントを使用すると、Twilio.Device.setup() メソッドが呼び出されます。このメソッドはユーザーがページを操作した後に呼び出します。この初期化プロセスは非同期であるため、ONLINE イベントハンドラーを提供する必要があります。このハンドラーは、セットアッププロセスが完了し、システムがコールを行う準備ができると呼び出されます。

    表 : 18. パラメーター
    名前 タイプ 説明
    なし
    表 : 19. 返される内容
    タイプ 説明
    なし

    この例では、Notify クライアントを初期化する方法を示します。

    $j(function() {
  notifyClient = new SNC.Notify.Client( notifyConfig );
  notifyClient.setCallerId( '+31858889170' );
  notifyClient.init();
});

    NotifyClient - mute(ブーリアン muted)

    現在のクライアントをミュートまたはミュート解除します。

    表 : 20. パラメーター
    名前 タイプ 説明
    muted ブーリアン 現在のコールをミュートまたはミュート解除します。
    • false：(または true 以外の値) 現在のコールのミュートを解除します。
    • true：現在のコールをミュートします。
    表 : 21. 返される内容
    タイプ 説明
    なし

    この例では、現在のコールをミュート状態にする方法を示します。

    notifyClient.mute( "true" );

    NotifyClient - pickupCall()

    WebRTC クライアントからの着信コールに応答して接続します。

    着信コールが通知されたら、このメソッドを呼び出します。

    表 : 22. パラメーター
    名前 タイプ 説明
    なし
    表 : 23. 返される内容
    タイプ 説明
    なし

    この例では、コールに応答して接続する方法を示します。

    $j("#pickupCallBtn").on("click", function() {
    notifyClient.pickupCall();
});

    NotifyClient - sendDtmf(文字列 digits)

    現在のコールで、1 桁以上の DTMF に対応した数字を送信します。

    表 : 24. パラメーター
    名前 タイプ 説明
    digits 文字列 DTMF に対応した 1 桁以上の数字。
    表 : 25. 返される内容
    タイプ 説明
    なし

    この例では、現在のコールに DTMF シグナルを送信する方法を示します。

    notifyClient.SendDtmf( "1246AF" ) {} );

    NotifyClient - setCallerId(文字列 value, 関数 autoSelectVendorCallback)

    現在のクライアントセッションの発信者 ID を設定します。

    発信者 ID はいつでも変更または更新できますが、発信者 ID は同じベンダーに属している必要があります。

    表 : 26. パラメーター
    名前 タイプ 説明
    value 文字列 コールの発信と受信に使用する電話番号。
    autoSelectVendorCallback 関数 随意。 initializeVendorClientLazily この関数を使用するには、コンストラクタで "true" に設定する必要があります。設定しないと、エラーがスローされます。

    指定された電話番号にベンダーが自動的に設定されたときに呼び出すコールバック関数の名前。このオプションでは、コンストラクター (notifyConfig.vendor) でベンダーを指定する必要はありません。ベンダーの自動選択は非同期操作です。したがって、このメソッドを呼び出す前にベンダーを設定する必要があるため、notifyConfig.init() をいつ安全に呼び出せるかをこのコールバックで示す必要があります。さらに、ベンダーが指定されていることを確認するために notifyConfig.vendor がコールバックに設定されているかどうかも確認する必要があります。
    表 : 27. 返される内容
    タイプ 説明
    なし

    この例では、発信者 ID を設定する方法を示します。この例では、ベンダーがコンストラクターで設定されていることを前提としています。

    $j(function() {
  notifyClient = new SNC.Notify.Client( notifyConfig );
  notifyClient.setCallerId( '+31858889170' );
  notifyClient.init();
});

    NotifyClient - setClientAvailable(ブーリアン available)

    アクティブな WebRTC クライアントのエージェントの空き状況を設定します。

    このタイプの空き状況は、コール中のエージェントのものとは異なります。この場合、アクティブな WebRTC クライアントは、コールの接続の有無にかかわらずコールの受信を望んでいない可能性があります。

    このメソッドを呼び出すと、このクライアントセッションに関連付けられた Notify Client 接続済みセッション [notify_client_session] レコードの [利用可能] フィールドの値が更新されます。getAvailableClients() メソッドを使用して、利用可能なクライアントのリストを取得できます。

    表 : 28. パラメーター
    名前 タイプ 説明
    available ブーリアン アクティブな WebRTC クライアントにコール受信の意思があるかどうかを示すフラグ。
    • false：クライアントにはコール受信の意思がありません。
    • true：クライアントにコール受信の意思があります。
    表 : 29. 返される内容
    タイプ 説明
    なし