Zoho Voice SDKの詳細と設定

Zoho Voice SDKの詳細と設定

お知らせ:当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

Java SDK

はじめに


Zoho Voiceは、通話の発着信ができるクラウド型の電話サービスです。Zoho Voiceでは、開発者が自社のアプリをZoho Voiceと連携するためのSDKも提供しています。

SDKの詳細と設定


リフレッシュトークンのダウンロード


ステップ1:https://voice.zoho.com にログインします。
ステップ2:ユーザープロフィールの下にある[java sdk refresh token]ボタンをクリックします。

ステップ3:リフレッシュトークンをDBに保存します。


ZohoVoiceSDKの構成


SDKのソースjar

(jarをlibディレクトリーにコピーする必要があります)


ZohoVoiceSDK.jar

lib/ZohoVoiceSDK.jarにあります


SDKに必要なライブラリー

(Dependenciesフォルダーを製品のzipファイルにコピーする必要があります)


httpcore-4.4.5.jar, json, httpclient-4.5.2.jar, commons-logging-1.1.1.jar

lib/thirdParty_Jarsにあります


SDKのJavaドキュメント




Java SDK

SDKオブジェクト


SDKオブジェクトの作成 

(必須)


ZohoVoiceSDK zohoVoiceSDK = new ZohoVoiceSDK(DC dc , String refreshToken);

(ZohoVoiceSDKオブジェクトはサーバー起動時にのみ作成されます)


標準のデータセンター:DC.US

利用可能なデータセンター。

DC.US


プロキシの設定


zohoVoiceSDK.setViaProxy(boolean)


初期値:false

Zoho Voice APIオブジェクト

Zoho Voice APIオブジェクト 

APIオブジェクトの作成

(必須)


ZohoVoiceAPI zohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);


zohoVoiceSDKは上記の手順で作成されています。




SDKの機能

エージェント

エージェントのインポート

アプリからZoho Voiceにエージェントをインポートします。
  1.  // インポートオブジェクトを作成
  2.  ImportAgents importAgents = new ImportAgents();

  •  // agentsinfoオブジェクトを作成
  •  AgentsInfo agentsInfo = new AgentsInfo();
  •  agentsInfo.setName('ZohoVoice');
  •  agentsInfo.setEmailId('abc@sample.com');
  •  agentsInfo.setDepartmentName('ZVoice');
  •  // 関連番号APIを使用すると、電話番号を関連付けることができます。
  •  JSONArray associatedNumber = new JSONArray(); // 電話番号のコレクション
  •  agentsInfo.setAssociatedNumbers(associatedNumber);

  •  // 複数のagentsInfoオブジェクト
  •  ArrayList<AgentsInfo> agentsInfos = new ArrayList<AgentsInfo>();
  •  agentsInfos.add(agentsInfo);

  •  importAgents.setAgentsInfo(agentsInfos);

  •  ZohoVoiceAPI zohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
  •  ImportAgentsResponse response = zohoVoiceAPI.importAgents(importAgents);

  •  // レスポンスオブジェクト
  •  String status = response.getStatus();
  •  String statusCode = response.getStatusCode();
  •  String errorMessage = response.getErrorMessage();
  •  JSONObject responseInJSON = response.getJSONObject();
  •  ArrayList<Agents> agents = response.getAgents();
  •  Agents agent = agents.get(0);
  •  agent.getAgentId();
  •  agent.getAgentNumber();
  •  agent.getDepartmentName();
  •  agent.getEmailId();
  •  agent.getExtension();
  •  agent.getName();
  •  agent.getOnlineStatus();

  • ログイン詳細の取得

    担当者IDとメールアドレスを入力して、ログイン詳細を取得します。
    1.  GetAgentLoginDetail getAgentLoginDetail = new GetAgentLoginDetail();
    2.  // agentIdまたはemailIdを設定します。
    3.  getAgentLoginDetail.setAgentId('agentId');
    4.  getAgentLoginDetail.setEmailId('emailId');

    5.  ZohoVoiceAPI zVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
    6.  GetAgentLoginDetailResponse response = zVoiceAPI.getAgentLoginDetail(getAgentLoginDetail);

    7.  // レスポンスオブジェクト
    8.  String status = response.getStatus();
    9.  String statusCode = response.getStatusCode();
    10.  String errorMessage = response.getErrorMessage();
    11.  JSONObject responseInJSON = response.getJSONObject();
    12.  JSONObject loginDetails = response.getLoginDetail();
    13. //LoginDetailsにはダイヤラーにログインするための認証情報が含まれています


    エージェントの取得

    エージェントIDまたは検索キーを入力して、エージェント一覧を取得します。
    1.  GetAgentsgetAgents = new GetAgents();
  •  getAgents.setAgentId('agentId');
  •  getAgents.setSearchKey('searchKey');
  •  getAgents.setFromIndex(2);
  •  getAgents.setToIndex(10);

  •  ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK,);
  •  GetAgentsResponseresponse =zohoVoiceAPI.getAgents(getAgents);

  •  // レスポンスオブジェクト
  •  Stringstatus =response.getStatus();
  •  StringstatusCode =response.getStatusCode();
  •  StringerrorMessage =response.getErrorMessage();
  •  JSONObjectresponseInJSON =response.getJSONObject();
  •  ArrayList<Agents>agents =response.getAgents();
  •  Agentsagent =agents.get(0);
  •  agent.getAgentId();
  •  agent.getAgentNumber();
  •  agent.getDepartmentName();
  •  agent.getEmailId();
  •  agent.getExtension();
  •  agent.getName();
  •  agent.getOnlineStatus();

  • 関連番号

    関連番号と対応するエージェントの詳細を取得します。

    1.  GetAssociatedNumbersgetAssociatedNumbers = new GetAssociatedNumbers();
    2.  getAssociatedNumbers.setAgentId('agentId');

    3.  ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
    4.  GetAssociatedNumbersResponseresponse =zohoVoiceAPI.getAssociatedNumbers(getAssociatedNumbers);

    5.  // レスポンスオブジェクト
    6.  Stringstatus =response.getStatus();
    7.  StringstatusCode =response.getStatusCode();
    8.  StringerrorMessage =response.getErrorMessage();
    9.  JSONObjectresponseInJSON =response.getJSONObject();
    10.  ArrayList<NumberInfo>outgoingNumbers =response.getOutgoingNumbers();
    11.  ArrayList<NumberInfo>incomingNumbers =response.getIncomingNumbers();
    12.  NumberInfoincomingNumber =incomingNumbers.get(0);
  •  LongnumberId =incomingNumber.getNumberId();
  •  StringdisplayName =incomingNumber.getDisplayName();
  •  StringtelNumber =incomingNumber.getTelNumber();
  •  StringcountryCode =incomingNumber.getCountryCode();
  •  StringdidNumber =incomingNumber.getDidNumber();

  • キーの再生成

    エージェント固有のキーを再生成します。このキーとパスワードは、ダイヤラーへのログインに使用します。

    1.  RegenerateKeyregenerateKey = new RegenerateKey();
    2.  regenerateKey.setAgentId('AgentId');
    3.  regenerateKey.setOldAgentKey('oldAgentPassword');

    4.  ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
    5.  RegenerateKeyResponseresponse =zohoVoiceAPI.regenerateKey(regenerateKey);

    6.  // レスポンスオブジェクト
    7.  Stringstatus =response.getStatus();
    8.  StringstatusCode =response.getStatusCode();
    9.  StringerrorMessage =response.getErrorMessage();
    10.  JSONObjectresponseInJSON =response.getJSONObject();


    パスワードの再生成

    エージェント固有のパスワードを再生成します。

    1.  RegeneratePasswordregeneratePassword = new RegeneratePassword();
    2.  regeneratePassword.setAgentId('AgentId');
    3.  regeneratePassword.setEmailId('abc@sample.com');
    4.  regeneratePassword.setOldPassword('oldPassword');

    5.  ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
    6.  RegeneratePasswordResponseresponse =zohoVoiceAPI.regeneratePassword(regeneratePassword);

    7.  // レスポンスオブジェクト
    8.  Stringstatus =response.getStatus();
    9.  StringstatusCode =response.getStatusCode();
    10.  StringerrorMessage =response.getErrorMessage();
    11.  JSONObjectresponseInJSON =response.getJSONObject();

    メールの再送信

    再生成されたパスワードが記載されたメールを再送信します。

    1.  ResendMailresendMail = new ResendMail();
    2.  resendMail.setAgentId('AgentId');
    3.  resendMail.setEmailId('abc@sample.com');

    4.  ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
    5.  ResendMailResponseresponse =zohoVoiceAPI.resendMail(resendMail);

    6.  // レスポンスオブジェクト
    7.  Stringstatus =response.getStatus();
    8.  StringstatusCode =response.getStatusCode();
    9.  StringerrorMessage =response.getErrorMessage();
    10.  JSONObjectresponseInJSON =response.getJSONObject();

    通話転送 - 担当者またはキューの一覧

    通話の転送先となる担当者またはキューの一覧を表示します。

    1.  TransferAgentOrQueuetransferAgentOrQueue = new TransferAgentOrQueue();
    2.  transferAgentOrQueue.setSearchText('searchText');
    3.  transferAgentOrQueue.setFromIndex(2);
    4.  transferAgentOrQueue.setToIndex(10);
    5.  transferAgentOrQueue.setIncludeQueues(true);

  •  ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
  •  TransferAgentOrQueueResponseresponse =zohoVoiceAPI.transferAgentOrQueue(transferAgentOrQueue);

  •  // レスポンスオブジェクト
  •  StringstatusCode =response.getStatusCode();
  •  StringerrorMessage =response.getErrorMessage();
  •  JSONObjectresponseInJSON =response.getJSONObject();
  •  ArrayList<Agents>agents =response.getAgents();
  •  Agentsagent =agents.get(0);
  •  agent.getAgentId();
  •  agent.getAgentNumber();
  •  agent.getDepartmentName();
  •  agent.getEmailId();
  •  agent.getExtension();
  •  agent.getName();
  •  agent.getOnlineStatus();

  • ログ

    通話ログの取得

    Zoho Voiceから通話ログを取得します。

    1.  GetCallLogsgetCallLogs = new GetCallLogs();
    2.  getCallLogs.setFromIndex(1);
  •  getCallLogs.setToIndex(20);
  •  getCallLogs.setFromDate('2021-09-27');
  •  getCallLogs.setToDate('2021-09-30');
  •  getCallLogs.setAllCountry(true);
  •  getCallLogs.setMinCredits(1.0);
  •  getCallLogs.setMaxCredits(10.0);
  •  getCallLogs.setMinDuration(20); // 最小通話時間(秒)
  •  getCallLogs.setMaxDuration(30);// 最大通話時間(秒)
  •  // エージェントIDの取得元:エージェントの取得
  •  ArrayList<String>agnetIds = new ArrayList<String>();
  •  agnetIds.add('615000001010123');
  •  getCallLogs.setAgnetIds(agnetIds);
  •  // 通話タイプ
  •  ArrayList<String>callTypes = new ArrayList<String>();
  •  callTypes.add('incoming');
  •  callTypes.add('outgoing');
  •  callTypes.add('missed');
  •  callTypes.add('forward');
  •  callTypes.add('bridged');
  •  getCallLogs.setCallType(callTypes);

  •  ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
  •  GetLogsResponsegetLogsResponse =zVoiceAPI.getCallLogs(getCallLogs);

  •  // レスポンス
  •  Stringstatus =getLogsResponse.getStatus();
  •  StringstatusCode =getLogsResponse.getStatusCode();
  •  StringerrorMessage =getLogsResponse.getErrorMessage();
  •  JSONObjectresponseInJSON =getLogsResponse.getJSONObject();
  •  ArrayList<CallLog>logs =getLogsResponse.getCallLogs();
  •  CallLogcallLog =logs.get(0);
  •  StringagentName =callLog.getAgentName();
  •  StringcallDuration =callLog.getCallDuration();
  •  StringcallerIdName =callLog.getCallerIdName();
  •  StringcallerIdNumber =callLog.getCallerIdNumber();
  •  StringcallType =callLog.getCallType();
  •  StringdestinationNumber =callLog.getDestinationNumber();
  •  StringendTime =callLog.getEndTime();
  •  StringstartTime =callLog.getStartTime();
  •    varoptions = { 
    development:false,
    debug:false,
    draggable:true,
               }] //Zoho発信リスト
       }
       varzohovoice = new ZohoVoice(options);
       
       //アカウントセッション経由で認証
    zohovoice.ajaxOpts.domain = 'http://app.zoho.com';  // ドメイン名に置き換えてください
    zohovoice.ajaxOpts.csrf = {key:'CSRF_KEY',value:'zvtpname'}; //キー名をCSRF Cookie名に置き換えてください


       //OAuthトークン経由で認証
    zohovoice.ajaxOpts.isOAuth = true;
    zohovoice.ajaxOpts.oAuthCallBack = (callBack) => {
           callBack(token)
       }

    zohovoice.initialize();
       

    イベント登録

    SDKから生成されるイベントに関数参照を渡します。ここで、UI操作により各種通話フローを処理します。

    コールバックイベント

     
    regState
       

    // 登録状態が変更されたときにトリガーされます
       on('regState', function(regObject) {})
       //regObjectのレスポンス
       {
    status:'connecting',    //No I18N
    username:self.opts.username
       }
       //regStateのステータス(connecting,registered,failed,error,disconnected,websocket closed,unregistered)
           
    callState
       // 通話状態が変更されたときにトリガーされます
       on('callState', function(callerObject) {})
       //callerObjectのレスポンス
       /*
    {
    callId: '6d2bcd2a-e87a-4518-91dc-52ed3caee986'
    callStatus: 'connected'
    didName: 'Direct Agent'
    didNumber: '14695016096'
    duration: '00:00'
    id: '14695016095-1625564868881'
    isAccepted: true
    isCallStarted: true
    isConf: false
    isConnecting: true
    isExtension: false
    isInCall: true
    isMissed: false
    isOutgoing: false
    isSecondCall: false
    name: 'Unknown'
    number: '14695016095'
    startTime: 1625564868881
    }
    */
       //callStateのcallStatus(incoming,connecting,ringing,connected,callend)

    error
       // エラーが発生したときにトリガーされます
       on('error', function(errorObject) {})
       //errorObjectのレスポンス
       /*
    {
    code: 1,
    desc:'Error message'
    }
    */

    login
       // ログイン時にトリガーされます
       on('login', function() {})

    logout
       // logout時に実行されます
       on('logout', function() {})

    ready
       //要素の作成時に実行されます
       on('ready', function() {})

    ready
       //要素の作成時に実行されます
       on('ready', function() {})

    voiceProfile
       //voiceProfileの更新時に実行されます
       on('voiceProfile', function() {})

       //通話中に通話時間を更新するために実行されます
       on('timer', function(tObj) {})

       //mediaDeviceChange時に実行されます
       on('mediaDeviceChange', function(tObj) {})
       
       //microphoneChange時に実行されます
       on('microphoneChange', function(tObj) {})

       //Voice SDKの破棄時に実行されます
       on('destroy', function(tObj) {})

       //updateCallerInfoのために実行されます
       on('updateCallerInfo', function(cInfo) {})

    transferStaus
       on('transferStaus', function(transferObj){});
       //transferObjのレスポンス
       {
    callerNumber: 'xxxxxxxx',
    callerName: 'xxxxxxxx',
    callId: '6d2bcd2a-e87a-4518-91dc-52ed3caee986',
    callTransfered: true,
    departmentName: 'AlarmsOne',
    duration: '00:00',
    emailid: 'brindha.r+101@zohotest.com',
    拡張機能: 98750,
    name: 'brindha 101 Tech',
    number: '58421713_4501000000516029',
    isTransferCall: true, //発信者Cの場合
    onlineStatus: 'Available',
    serviceName: 'ZohoVoice',
    transferId: 1625564926802,
    status: {type: 'caller',status: 'unhold'}
       }
       //statusのレスポンス
       {type:'transfer',status:'dialing'} //転送通話でエージェント/キューに発信中
       {type:'transfer',status:'ringing'} //転送通話でエージェント/キューを呼び出し中
       {type:'transfer',status:'bridged'} //転送通話でエージェントが切断済み
       {type:'transfer',status:'unavailable'} //転送通話でエージェントが応答不可
       {type:'threeway',status:'bridged'} //転送通話で通話が結合済み
       {type:'caller',status:'hold'}  //転送時に発信者Aが保留中
       {type:'caller',status:'unhold'} //転送時に発信者Aの保留を解除
       {type:'caller',status:'hangup'} //転送時に発信者Aが通話を切断済み

       //イベント監視の例
       varzohovoice= new ZohoVoice(options);
    zohovoice.on('regState', function({
         //必要な処理を作成します
       });

    SDKリファレンス

    設定パラメーターは次のとおりです。

    属性

    データ型

    説明

    debug

    真偽値

    debugを有効にすると、ログがブラウザーの開発者コンソールに表示されます。

    true|false

    sipDebug

    真偽値

    sipDebugを有効にすると、SIPログがブラウザーの開発者コンソールに表示されます。

    true|false

    development

    真偽値

    developmentを有効にすると開発サーバーに接続され、それ以外の場合は本番サーバーに接続されます。

    true|false

    agentKey

    文字列

    通話の発信/受信の認証に使用されるagentKeyです。


    name

    文字列

    登録済みの名前が発信者ID名として使用されます。


    username

    文字列

    Zoho Voiceへのログイン用ユーザー名です。


    password

    文字列

    Zoho Voiceへのログイン用パスワードです。


    element

    文字列

    この属性は、Zoho Voiceウィジェットの差し込み項目として使用されます。


    defaultCountry

    文字列

    この属性は、ダイヤルパッドのデフォルトの国として使用されます。


    show

    真偽値

    UIでZoho Voiceウィジェットを表示/非表示にするために使用します。


    autoRegister

    真偽値

    Zoho Voiceサーバーに自動的に登録します。初期値は'true'です。

    true|false

    isDarkMode

    真偽値

    ダークモードを有効にします。

    true|false

    callHeaders

    配列

    SIP Invite用のカスタムヘッダー。


    turnServers

    配列

    カスタムTURNサーバー。

    [{
    urls: ['stun:us-relay2.zohovoice.com:9090', 'turn:us-relay2.zohovoice.com:9090?transport=tcp', 
       'turn:us-relay2.zohovoice.com:9090?transport=udp'],
    username: 'xxxxxx',  
    credential: 'xxxxxxx'   
    }];
                               


    clientRegion

    String

    通話品質を向上させるため、ユーザーの地域に基づいてMediaServerを使用します。['Mumbai', 'WDC', 'Singapore', 'Sydney', 'Amsterdam', 'Dallas', 'Sanjose'];


    outgoingNumberList

    JSONArray

    ユーザーが発信通話を行うために購入した番号の一覧です。


    outgoingNumber

    JSONObject

    デフォルトの発信番号です。


    enableAgentStatus

    Boolean

    エージェントステータスの表示/非表示を設定します。デフォルト値はfalseです。

    true|false

    numberSuggestions

    Boolean

    番号候補を有効または無効にします。

    true|false

    enableCallSchedule

    Boolean

    通話スケジュールの表示を有効または無効にします。

    true|false

    callNotes

    真偽値

    通話メモの表示を有効または無効にします

    true|false

    extensions

    真偽値

    内線通話を有効または無効にします

    true|false

    menuList

    配列

    ログ、設定用のカスタムメニューリスト

    ['logs','settings']

    showLauncherIcon

    真偽値

    ランチャーアイコンを有効または無効にします

    true|false

    launcherIcon

    文字列

    ランチャーアイコンのURL


    profileCache

    真偽値

    有効にすると、ダイヤルパッドをより速く読み込むためにプロフィールの詳細がlocalStorageに保存されます。

    true/false

    widgetStyle

    オブジェクト

    {
    pos: {
    top: 'auto', //No I18N
    bottom: '10px', //No I18N
    right: '10px', //No I18N
    left: 'auto' //No I18N
       },
    width: '100%', //No I18N
    height: '100%', //No I18N
       'max-width': '300px', //No I18N
       'max-height': '520px' //No I18N
    }




    Zoho Voiceのメソッド

    対応しているメソッドは次のとおりです

    名前

    パラメーター

    説明

    makeCall

    varzohovoice = ZohoVoice({
    apiKey:'xxxx-xxxx-xxx-xxx'
       })
    zohovoice.makeCall({
    number:130000,
    name:'Zoho Voice',
    photo:'URL'
       }) 
       または 
    zohovoice.makeCall('123456');


    endCall

    //通常の通話切断
    zohovoice.endCall({callId:'xxxxxx-xxx-xxx'});

    //転送通話の担当者の切断
    zohovoice.endCall({transferId:'xxxxxx-xxx-xxx'});
                           


    answerCall


    zohovoice.answerCall({callId:'xxxxxx-xxx-xxx'});
                           


    dtmf


    zohovoice.dtmf(digit, {callId:'xxxxxx-xxx-xxx'});
                           


    setMute


    zohovoice.setMute(true|false, {callId:'xxxxxx-xxx-xxx'});
                           


    setHold


    zohovoice.setHold(true|false, {callId:'xxxxxx-xxx-xxx'});
                           


    show

    true/false


    unRegisterServer



    registerServer



    showDialer



    destroy



    setAgentStatus

    (対応可能/休憩中/通話中/オフライン)


    setTurnServerList

    varzohovoice = ZohoVoice({
    apiKey:'xxxx-xxxx-xxx-xxx'
    })
    varturnservers = [{
    urls: ['stun:us-relay2.zohovoice.com:9090', 
       'turn:us-relay2.zohovoice.com:9090?transport=tcp', 
       'turn:us-relay2.zohovoice.com:9090?transport=udp'],
    username: 'xxxxxx',  
    credential: 'xxxxxxx'   
    }]
    zohovoice.setTurnServerList(turnservers); 


    setOutgoingNumber

    {
    number:'123456789',
    numberId:'123456789',
    isDefault:true
    }


    setDefaultCountry

    zohovoice.setDefaultCountry('us')


    holdAndAccept

    zohovoice.holdAndAccept({callId:'xxxxxx-xxx-xxx'})


    endAndAccept

    zohovoice.endAndAccept({callId:'xxxxxx-xxx-xxx'})


    switchCall

    zohovoice.switchCall({callId:'xxxxxx-xxx-xxx'})


    whisper

    zohovoice.whisper({callId:'xxxxxx-xxx-xxx'})


    threeway

    zohovoice.threeway({callId:'xxxxxx-xxx-xxx'})


    barge

    zohovoice.threeway({callId:'xxxxxx-xxx-xxx'})


    transfer

    (transferAgent/Queue), callId

    zohovoice.transfer({
       'departmentName':'US Sales',
       'number':'xxxxx-xxxxxx',
       '拡張機能':12345,
       'onlineStatus':'Available',
       'name':'Zyleker',
       'emailid':'ジルカー@zohotest.com',
       'serviceName':'ZohoVoice'
    }, {callId;'xxxxx-xxxxxx'})

    着信通話を担当者/キューに転送します

    merge

    {callId:'xxxxxx-xxx-xxx-xx'}

    zohovoice.merge({callId;'xxxxx-xxxxxx'})

    転送された通話を(三者間で)結合します

    updateCallerInfo

    zohovoice.updateCallerInfo({
                                   'name':'Zyleker',
                                   'メール':'ジルカー@zohotest.com',
                                   'company':'ジルカー',
                                   'infoUrl':'https://zoho.com',
                                   'appName':'zoho_voice'
                               })

    ダイヤルパッドの発信者情報を更新するには