04 API (Operations)

Notes:

• This document describes operations initiated via SDK methods.
• All operations return Promises. Determine success/failure by code in the resolved response. Handle local exceptions via try/catch (see 07-Error-Handling.md).
• Types are defined in 06-Types.md and take precedence over any other file if inconsistencies exist.

1. General conventions

1.1 Standard signature

AgentSDK.methodName(params?): Promise<SdkResponse & {...}>

1.2 Standard response fields (summary)

• action: action name (typically aligned with response events / EventType)
• code: 0 success; non-zero failure (commonly -1)
• message: human-readable message
• errorCode?: optional business error code (domain-specific)

See 06-Types.md.

1.3 Two ways to consume results

1. Promise (recommended): await AgentSDK.xxx() to get the operation response

2. Event: subscribe to EventType.XXX_RESP (or xxxResp) to receive the response via events

2. Setup & event handling

2.1 setup(config)

Purpose: set global SDK configuration (recommended once at app startup).

Common parameters:

Example:

AgentSDK.setup({
  baseURL: 'https://api.example.com',
  debug: false,
  webrtc: true,
  webrtcStats: false,
  audio_debug: false,
  observability: false
});

2.2 Event APIs: on/off/once

• Subscribe: AgentSDK.on(eventName, handler)
• Unsubscribe: AgentSDK.off(eventName, handler)
• Subscribe once: AgentSDK.once(eventName, handler)

Example:

const { EventType } = AgentSDK;

const onStatus = (e) => console.log('agentStatus', e);
AgentSDK.on(EventType.AGENT_STATUS, onStatus);

AgentSDK.once(EventType.SESSION_INIT, () => console.log('session init once'));

// Cleanup on unload
AgentSDK.off(EventType.AGENT_STATUS, onStatus);

3. Agent operations (core)

3.1 login(params)

Purpose: agent sign-in (establish session, open WebSocket, subscribe server-pushed events).

Parameters (detailed)

Response (Promise resolve)

In addition to the base SdkResponse, login may return softphone-related fields (softphone only).

Related events

• loginResp (if you consume responses via events)
• agentStatus (continuous agent status updates after login)
• reconnectAttempt (reconnection attempts)

Example

const res = await AgentSDK.login({
  tenantId: 'your_tenantId',
  agentNo: 'your_agentNo',
  sessionKey: 'your_sessionKey',
  bindEndpoint: { endpointType: 1, endpoint: '13600000000' },
  initialStatus: 1
  // initialStatus=2 requires pauseDescription: 'MEETING'
});

if (res.code === 0) {
  console.log('login ok');
} else {
  console.error('login failed:', res.message);
}

3.2 logout(params)

Purpose: sign out / disconnect.

Parameters (detailed)

await AgentSDK.logout({ logoutMode: 1, unbindEndpoint: 0 });

3.3 pause(params) / unpause()

Purpose: set Busy / set Idle.

pause(params) parameters

Response message notes

message may contain (examples): ok, deviceStatus not in idle, exception, fail to get lock, already ready, not logined, no such agent.

await AgentSDK.pause({ pauseType: 1, pauseDescription: 'MEETING' });
await AgentSDK.unpause();

3.4 updateBoundEndpoint(params)

Purpose: change agent’s bound endpoint (phone/extension/etc.).

await AgentSDK.updateBoundEndpoint({
  bindEndpoint: { endpointType: 1, endpoint: '13600000000' }
});

4. Call control (common)

4.1 previewObCall(params)

Purpose: Preview Outbound Call (ring agent endpoint first, then dial customer and bridge).

Softphone note: when bindEndpoint.endpointType=3, place outbound only after the softphone is ready/registered (based on your integration).

Parameters (detailed)

const res = await AgentSDK.previewObCall({
  customerNumber: '13800138000',
  agentAnswerTimeout: 30,
  customerAnswerTimeout: 45
});
if (res.code !== 0) console.error(res.errorCode, res.message);

Related events: previewObCallStart/previewObCallRinging/previewObCallBridge/previewObCallResult (see 05-Events.md, 10-Key-Flows-Sequence-Diagrams.md).

Business error codes (preview outbound call)

When res.code !== 0, errorCode/message may be returned (examples; subject to server):

4.2 cancelPreviewObCall()

Purpose: cancel a Preview Outbound Call (typically while the agent endpoint is ringing).

await AgentSDK.cancelPreviewObCall();

4.3 unlink(params)

Purpose: hang up the current call.

await AgentSDK.unlink({ side: 1 });

4.4 reject(params)

Purpose: reject an inbound call while ringing.

await AgentSDK.reject({ description: 'busy' });

4.5 hold() / unhold()

Purpose: hold / retrieve the call.

await AgentSDK.hold();
await AgentSDK.unhold();

4.6 mute(params) / unmute(params)

Purpose: mute / unmute the call.

await AgentSDK.mute({ direction: 'in' });
await AgentSDK.unmute({ direction: 'in' });

4.7 sendDtmf(params)

Purpose: send DTMF digits during a call.

await AgentSDK.sendDtmf({ digits: '1#', target: 2 });

4.8 performSatisfactionSurvey()

Purpose: start a customer satisfaction survey. On success, the agent-side call ends and the customer enters the survey flow.

await AgentSDK.performSatisfactionSurvey();

4.9 InternalCall(params)

Purpose: internal call to another agent or an IP phone extension within the same tenant.

await AgentSDK.InternalCall({
  targetType: 0,
  target: '0000',
  agentAnswerTimeout: 30,
  customerAnswerTimeout: 45
});

4.10 prolongWrapup(params)

Purpose: extend wrap-up time.

await AgentSDK.prolongWrapup({ wrapupTime: 300 });

4.11 startAutoObCallTask(params)

Purpose: start an agent auto outbound task.

await AgentSDK.startAutoObCallTask({ taskId: '11', callParams: '{"key":"value"}' });

4.12 pauseAutoObCallTask(params)

Purpose: pause an agent auto outbound task.

await AgentSDK.pauseAutoObCallTask({ taskId: '11' });

4.13 changeObCallMode(params)

Purpose: change agent outbound working mode.

await AgentSDK.changeObCallMode({ workMode: 0 });

5. Consult & transfer (call transfer features)

5.1 startAtxfer(params) / cancelAtxfer() / resumeAtxfer()

Purpose: start consult / cancel consult / resume from consult.

startAtxfer(params) parameters

await AgentSDK.startAtxfer({ targetType: 0, target: '13800138000' });
await AgentSDK.cancelAtxfer();
await AgentSDK.resumeAtxfer();

5.2 completeAtxfer(params)

Purpose: complete consult transfer.

Optional parameters:

await AgentSDK.completeAtxfer();

5.3 threewayAtxfer(params)

Purpose: consult three-way conference.

Optional parameters:

await AgentSDK.threewayAtxfer();

5.4 blxfer(params)

Purpose: blind transfer (to customer number / agent / extension / IVR node).

await AgentSDK.blxfer({ targetType: 0, target: '13800138000' });

See 09-Transfer-Parameters-blxferVariables.md for details.

5.5 transferIvr(params)

Purpose: transfer to IVR for interaction and receive return variables in interactReturn.

await AgentSDK.transferIvr({
  ivrTarget: { ivrId: 1, ivrNode: '1.1' }
});

Related event: interactReturn (see 05-Events.md).

6. Softphone (WebRTC)

6.1 sipLink() / sipUnlink()

Purpose: answer/hang up for softphone (bindEndpoint.endpointType=3).

await AgentSDK.sipLink();
await AgentSDK.sipUnlink();

Related events: sipSessionInit/sipSessionTerminate/sipDisconnected/webrtcStats (see 05-Events.md).

7. Supervisor / Monitoring operations

Supervisor typically needs queue binding (e.g., qids) at login and appropriate permissions.

7.1 setPause(params) / setUnpause(params)

Purpose: supervisor sets a target agent to Busy/Idle.

await AgentSDK.setPause({ agentNo: '0000' });
await AgentSDK.setUnpause({ agentNo: '0000' });

7.2 spy(params) / unspy()

Purpose: start/stop call monitoring (silent monitoring).

await AgentSDK.spy({ agentNo: '0000' });
await AgentSDK.unspy();

7.3 performThreeway(params) / cancelThreeway(params)

Purpose: supervisor three-way / cancel three-way on a target agent’s call.

await AgentSDK.performThreeway({ agentNo: '0000' });
await AgentSDK.cancelThreeway({ agentNo: '0000' });

7.4 whisper(params) / unWhisper()

Purpose: start/stop whisper coaching on a target agent’s call.

await AgentSDK.whisper({ agentNo: '0000' });
await AgentSDK.unWhisper();

7.5 barge(params) / disconnect(params)

Purpose: barge-in / force disconnect for a target agent’s call.

await AgentSDK.barge({ agentNo: '0000' });
await AgentSDK.disconnect({ agentNo: '0000' });

7.6 pickup(params)

Purpose: call pickup (answer a ringing call on behalf of a target agent).

await AgentSDK.pickup({ agentNo: '0000' });

7.7 setOnline(params) / setOffline(params)

Purpose: force an agent online/offline.

setOnline(params)

await AgentSDK.setOnline({
  agentNo: '0000',
  bindEndpoint: { endpointType: 1, endpoint: '1354*******' }
});

setOffline(params)

await AgentSDK.setOffline({ agentNo: '0000', unbindEndpoint: 0 });

7.8 getQueueStatus(params)

Purpose: query queue status (supervisor).

Response (summary):

• action: queueStatus
• queueStatus: a map of queueNo → data (see 06-Types.md)

await AgentSDK.getQueueStatus({ queueNos: [0, 1, 2], fields: 'queueParams,agentStatuses,queueEntries' });

7.9 ListPreviewDialingTask()

Purpose: list preview dialing tasks.

Note: the source doc indicates the return payload is not fully specified yet. This doc only states the API exists and follows standard response shape; confirm the concrete return fields with the server contract.

await AgentSDK.ListPreviewDialingTask();