お知らせ:当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の
英語版を参照してください。
Java SDK
はじめに
Zoho Voiceは、通話の発着信ができるクラウド型の電話サービスです。Zoho Voiceでは、開発者が自社のアプリをZoho Voiceと連携するためのSDKも提供しています。
|
|
|
|
ステップ1:https://voice.zoho.com にログインします。 ステップ2:ユーザープロフィールの下にある[java sdk refresh token]ボタンをクリックします。
ステップ3:リフレッシュトークンをDBに保存します。
|
|
|
|
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にあります
|
|
|
|
Java SDK
|
|
|
|
ZohoVoiceSDK zohoVoiceSDK = new ZohoVoiceSDK(DC dc , String refreshToken);
(ZohoVoiceSDKオブジェクトはサーバー起動時にのみ作成されます)
標準のデータセンター:DC.US
利用可能なデータセンター。
DC.US
|
|
|
zohoVoiceSDK.setViaProxy(boolean)
初期値:false
|
Zoho Voice APIオブジェクト
|
|
|
|
ZohoVoiceAPI zohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
zohoVoiceSDKは上記の手順で作成されています。
|
SDKの機能
エージェント
エージェントのインポート
アプリからZoho Voiceにエージェントをインポートします。
- // インポートオブジェクトを作成
- 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とメールアドレスを入力して、ログイン詳細を取得します。
- GetAgentLoginDetail getAgentLoginDetail = new GetAgentLoginDetail();
- // agentIdまたはemailIdを設定します。
- getAgentLoginDetail.setAgentId('agentId');
- getAgentLoginDetail.setEmailId('emailId');
- ZohoVoiceAPI zVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
- GetAgentLoginDetailResponse response = zVoiceAPI.getAgentLoginDetail(getAgentLoginDetail);
- // レスポンスオブジェクト
- String status = response.getStatus();
- String statusCode = response.getStatusCode();
- String errorMessage = response.getErrorMessage();
- JSONObject responseInJSON = response.getJSONObject();
- JSONObject loginDetails = response.getLoginDetail();
- //LoginDetailsにはダイヤラーにログインするための認証情報が含まれています
エージェントの取得
エージェントIDまたは検索キーを入力して、エージェント一覧を取得します。
- 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();
関連番号
関連番号と対応するエージェントの詳細を取得します。
- GetAssociatedNumbersgetAssociatedNumbers = new GetAssociatedNumbers();
- getAssociatedNumbers.setAgentId('agentId');
- ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
- GetAssociatedNumbersResponseresponse =zohoVoiceAPI.getAssociatedNumbers(getAssociatedNumbers);
- // レスポンスオブジェクト
- Stringstatus =response.getStatus();
- StringstatusCode =response.getStatusCode();
- StringerrorMessage =response.getErrorMessage();
- JSONObjectresponseInJSON =response.getJSONObject();
- ArrayList<NumberInfo>outgoingNumbers =response.getOutgoingNumbers();
- ArrayList<NumberInfo>incomingNumbers =response.getIncomingNumbers();
- NumberInfoincomingNumber =incomingNumbers.get(0);
LongnumberId =incomingNumber.getNumberId();
StringdisplayName =incomingNumber.getDisplayName();
StringtelNumber =incomingNumber.getTelNumber();
StringcountryCode =incomingNumber.getCountryCode();
StringdidNumber =incomingNumber.getDidNumber();
キーの再生成
エージェント固有のキーを再生成します。このキーとパスワードは、ダイヤラーへのログインに使用します。
- RegenerateKeyregenerateKey = new RegenerateKey();
- regenerateKey.setAgentId('AgentId');
- regenerateKey.setOldAgentKey('oldAgentPassword');
- ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
- RegenerateKeyResponseresponse =zohoVoiceAPI.regenerateKey(regenerateKey);
- // レスポンスオブジェクト
- Stringstatus =response.getStatus();
- StringstatusCode =response.getStatusCode();
- StringerrorMessage =response.getErrorMessage();
- JSONObjectresponseInJSON =response.getJSONObject();
パスワードの再生成
エージェント固有のパスワードを再生成します。
- RegeneratePasswordregeneratePassword = new RegeneratePassword();
- regeneratePassword.setAgentId('AgentId');
- regeneratePassword.setEmailId('abc@sample.com');
- regeneratePassword.setOldPassword('oldPassword');
- ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
- RegeneratePasswordResponseresponse =zohoVoiceAPI.regeneratePassword(regeneratePassword);
- // レスポンスオブジェクト
- Stringstatus =response.getStatus();
- StringstatusCode =response.getStatusCode();
- StringerrorMessage =response.getErrorMessage();
- JSONObjectresponseInJSON =response.getJSONObject();
メールの再送信
再生成されたパスワードが記載されたメールを再送信します。
- ResendMailresendMail = new ResendMail();
- resendMail.setAgentId('AgentId');
- resendMail.setEmailId('abc@sample.com');
- ZohoVoiceAPIzohoVoiceAPI = new ZohoVoiceAPI(zohoVoiceSDK);
- ResendMailResponseresponse =zohoVoiceAPI.resendMail(resendMail);
- // レスポンスオブジェクト
- Stringstatus =response.getStatus();
- StringstatusCode =response.getStatusCode();
- StringerrorMessage =response.getErrorMessage();
- JSONObjectresponseInJSON =response.getJSONObject();
通話転送 - 担当者またはキューの一覧
通話の転送先となる担当者またはキューの一覧を表示します。
- TransferAgentOrQueuetransferAgentOrQueue = new TransferAgentOrQueue();
- transferAgentOrQueue.setSearchText('searchText');
- transferAgentOrQueue.setFromIndex(2);
- transferAgentOrQueue.setToIndex(10);
- 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から通話ログを取得します。
- GetCallLogsgetCallLogs = new GetCallLogs();
- 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を有効にすると、ログがブラウザーの開発者コンソールに表示されます。
sipDebugを有効にすると、SIPログがブラウザーの開発者コンソールに表示されます。
developmentを有効にすると開発サーバーに接続され、それ以外の場合は本番サーバーに接続されます。
通話の発信/受信の認証に使用されるagentKeyです。
Zoho Voiceへのログイン用ユーザー名です。
Zoho Voiceへのログイン用パスワードです。
この属性は、Zoho Voiceウィジェットの差し込み項目として使用されます。
この属性は、ダイヤルパッドのデフォルトの国として使用されます。
UIでZoho Voiceウィジェットを表示/非表示にするために使用します。
Zoho Voiceサーバーに自動的に登録します。初期値は'true'です。
カスタム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'
}];
通話品質を向上させるため、ユーザーの地域に基づいてMediaServerを使用します。['Mumbai', 'WDC', 'Singapore', 'Sydney', 'Amsterdam', 'Dallas', 'Sanjose'];
ユーザーが発信通話を行うために購入した番号の一覧です。
エージェントステータスの表示/非表示を設定します。デフォルト値はfalseです。
有効にすると、ダイヤルパッドをより速く読み込むためにプロフィールの詳細がlocalStorageに保存されます。
{
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のメソッド
対応しているメソッドは次のとおりです
varzohovoice = ZohoVoice({
apiKey:'xxxx-xxxx-xxx-xxx'
})
zohovoice.makeCall({
number:130000,
name:'Zoho Voice',
photo:'URL'
})
(または)
zohovoice.makeCall('123456');
//通常の通話切断
zohovoice.endCall({callId:'xxxxxx-xxx-xxx'});
//転送通話の担当者の切断
zohovoice.endCall({transferId:'xxxxxx-xxx-xxx'});
zohovoice.answerCall({callId:'xxxxxx-xxx-xxx'});
zohovoice.dtmf(digit, {callId:'xxxxxx-xxx-xxx'});
zohovoice.setMute(true|false, {callId:'xxxxxx-xxx-xxx'});
zohovoice.setHold(true|false, {callId:'xxxxxx-xxx-xxx'});
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);
{
number:'123456789',
numberId:'123456789',
isDefault:true
}
zohovoice.setDefaultCountry('us')
zohovoice.holdAndAccept({callId:'xxxxxx-xxx-xxx'})
zohovoice.endAndAccept({callId:'xxxxxx-xxx-xxx'})
zohovoice.switchCall({callId:'xxxxxx-xxx-xxx'})
zohovoice.whisper({callId:'xxxxxx-xxx-xxx'})
zohovoice.threeway({callId:'xxxxxx-xxx-xxx'})
zohovoice.threeway({callId:'xxxxxx-xxx-xxx'})
(transferAgent/Queue), callId
zohovoice.transfer({
'departmentName':'US Sales',
'number':'xxxxx-xxxxxx',
'拡張機能':12345,
'onlineStatus':'Available',
'name':'Zyleker',
'emailid':'ジルカー@zohotest.com',
'serviceName':'ZohoVoice'
}, {callId;'xxxxx-xxxxxx'})
{callId:'xxxxxx-xxx-xxx-xx'}
zohovoice.merge({callId;'xxxxx-xxxxxx'})
zohovoice.updateCallerInfo({
'name':'Zyleker',
'メール':'ジルカー@zohotest.com',
'company':'ジルカー',
'infoUrl':'https://zoho.com',
'appName':'zoho_voice'
})