tencent cloud

Last updated: 2025-01-09 15:41:52
iOS
Last updated: 2025-01-09 15:41:52
This article mainly introduces common APIs for the agent side of the Cloud Contact Center (TCCC). On iOS, we provide Swift, Objective-C, and C++ APIs for developer choice. We recommend iOS developers use Swift for application development.

Creating Instances and Event Callbacks

API
Description
Creates an ITCCCWorkstation instance (singleton).
Destroys an ITCCCWorkstation instance (singleton).
Adds an ITCCCWorkstation event callback.
Removes an ITCCCWorkstation event callback.

Sample Code for Creating Instances and Setting Event Callbacks

Swift
Objective-C
C++
import TCCCSDK

let tcccSDK: TCCCWorkstation = {
// Create an instance.
return TCCCWorkstation.sharedInstance()
}()

// Set the TCCC event callback
tcccSDK.addTcccListener(self)

// Remove the TCCC event callback
tcccSDK.removeTCCCListener(self)
// Destroy the instance
TCCCWorkstation.destroySharedIntance()
// Import the OC header file
#import "TCCCSDK/tccc/platform/apple/TCCCWorkstation.h"

@property (strong, nonatomic) TCCCWorkstation *tcccSDK;

- (TCCCWorkstation*)tcccSDK {
if (!_tcccSDK) {
// Create an instance.
_tcccSDK = [TCCCWorkstation sharedInstance];
}
return _tcccSDK;
}
// Set the TCCC event callback
[self.tcccSDK addTcccListener:self];

// Remove the TCCC event callback
[self.tcccSDK removeTCCCListener:self];
// Destroy the instance
[TCCCWorkstation destroySharedIntance];
_tcccSDK = nil;
#include "TCCCSDK/tccc/include/ITCCCWorkstation.h"
using namespace tccc;
// Create an instance and set an event callback
ITCCCWorkstation* tcccSDK = getTCCCShareInstance();
// Set the callback. TCCCCallbackImpl needs to be derived from ITCCCCallback
class TCCCCallbackImpl:public ITCCCCallback {
public:
TCCCCallbackImpl() {}
~TCCCCallbackImpl() {}

void onError(TCCCError errCode, const char* errMsg, void* extraInfo) {}
void onWarning(TCCCCWarning warningCode, const char* warningMsg, void* extraInfo) {}

void onNewSession(TCCCSessionInfo info) {}

void onEnded(EndedReason reason, const char* reasonMessage, const char* sessionId) {}
};
TCCCCallbackImpl* tcccCallback = new TCCCCallbackImpl();
tcccSDK->addCallback(tcccCallback);
// Destroy the instance
destroyTCCCShareInstance();
tcccSDK = nullptr;

Login-related APIs

API
Description
SDK login
Checks whether the SDK is already logged in.
SDK logout

Login and logout sample code

Swift
Objective-C
C++
import TCCCSDK

let param = TXLoginParams()
// The agent ID for login, which is usually an email address
param.userId = "";
// The login ticket, required for the Agent login mode. For details, see Creating SDK Login
// Token](https://www.tencentcloud.com/document/product/679/49227?from_cn_redirect=1)
param.token = "";
// Cloud Contact Center application ID, which usually starts with 1400
param.sdkAppId = 0;
// Set to agent mode
param.type = .Agent;
// Login
tcccSDK.login(param) { info in
// Login succeeded
} fail: { code, message in
// Login failed
}

// Check login status
tcccSDK.checkLogin {
// Logged in
} fail: { code, message in
// Not logged in or kicked out
}

// Logout
tcccSDK.logout {
// Exit succeeded
} fail: { code, message in
// Exit exception
}
// Import the OC header file
#import "TCCCSDK/tccc/platform/apple/TCCCWorkstation.h"

TXLoginParams *param = [[TXLoginParams alloc] init];
// The agent ID for login, which is usually an email address
param.userId = @"";
// The login ticket, required for the Agent login mode. For details, see Creating SDK Login
// Token](https://www.tencentcloud.com/document/product/679/49227?from_cn_redirect=1)
param.token = @"";
// Cloud Contact Center application ID, which usually starts with 1400
param.sdkAppId = 0;
// Set to agent mode
param.type = Agent;
[self.tcccSDK login:param succ:^(TXLoginInfo * _Nonnull info) {
// Login succeeded
} fail:^(int code, NSString * _Nonnull desc) {
// Login failed
}];

// Check login status
[self.tcccSDK checkLogin:^{
// Logged in
} fail:^(int code, NSString * _Nonnull desc) {
// Not logged in or kicked out
}];

// Logout
[self.tcccSDK logout:^{
// Exit succeeded
} fail:^(int code, NSString * _Nonnull desc) {
// Exit exception
}];
#include "TCCCSDK/tccc/include/ITCCCWorkstation.h"
using namespace tccc;
// Callback class for login
class TCCCLoginCallbackImpl : public ITXValueCallback<TCCCLoginInfo> {
public:
TCCCLoginCallbackImpl() {
}
~TCCCLoginCallbackImpl() override {}
void OnSuccess(const TCCCLoginInfo &value) override {
// Login succeeded
}
void OnError(TCCCError error_code, const char *error_message) override {
// Login failed
}
};
TCCCLoginCallbackImpl* loginCallBackImpl = nullptr;
if (nullptr == loginCallBackImpl) {
loginCallBackImpl = new TCCCLoginCallbackImpl();
}
TCCCLoginParams param;
/// The agent ID for login, which is usually an email address
param.userId = "";
/// The login ticket, required for the Agent login mode. For details, see Creating SDK Login.
/// Token](https://www.tencentcloud.com/document/product/679/49227?from_cn_redirect=1)
param.token = "";
/// Cloud Contact Center application ID, which usually starts with 1400
param.sdkAppId = 0;
// Set to agent mode
param.type = TCCCLoginType::Agent;
// Login
tcccSDK->login(param,loginCallBackImpl);
// Logout
tcccSDK->logout(nullptr);

Call-related API Functions

API
Description
Initiates a call.
Answers a call.
Ends a call.
Sends Dual Tone Multi-Frequency (DTMF) signals.
Mutes.
Unmutes.

Sample Code for Initiating and Ending a Call

Swift
Objective-C
C++
import TCCCSDK

let callParams = TXStartCallParams()
// Called phone number
callParams.to = "";
// Number remarks, which will replace the number displayed in the call bar (optional)
callParams.remark = "";
// Initiate an outbound call
tcccSDK.call(callParams) {
// Call initiated successfully
} fail: { code, message in
// Call initiation failed
}
// End the call
tcccSDK.terminate()
// Import the OC header file
#import "TCCCSDK/tccc/platform/apple/TCCCWorkstation.h"

TXStartCallParams *callParams = [[TXStartCallParams alloc] init];
// Called phone number
callParams.to = TO;
// Number remarks, which will replace the number displayed in the call bar (optional)
callParams.remark = @"testByIos";
// Initiate an outbound call
[self.tcccSDK call:callParams succ:^{
// Call initiated successfully
} fail:^(int code, NSString * _Nonnull desc) {
// Call initiation failed
}];

// End the call
[self.tcccSDK terminate];
#include "TCCCSDK/tccc/include/ITCCCWorkstation.h"
using namespace tccc;
class TCCCCommonCallback : public ITXCallback {
private:
NSString* mFunName;
public:
TCCCCommonCallback(NSString* funName) {
mFunName = funName;
}
~TCCCCommonCallback() override {
}
void OnSuccess() override {
// Succeeded
}
void OnError(TCCCError error_code, const char *error_message) override {
std::string copyErrMsg = makeString(error_message);
// Failed
}
};
TCCCCommonCallback* startCallCallbackImpl = nullptr;
if (nullptr == startCallCallbackImpl) {
startCallCallbackImpl = new TCCCCommonCallback(@"startCall");
}
TCCCStartCallParams callParams;
// Phone number for the call
callParams.to = "";
// Initiate an outbound call
tcccSDK->call(callParams, startCallCallbackImpl);
// End the call
tcccSDK->terminate();

Audio Device API Functions

API
Description
Sets the local audio capture volume.
Obtains the local audio capture volume.
Sets the remote audio playback volume.
Obtains the remote audio playback volume.
Sets audio routing.

Switching Audio Route Sample Code

Swift
Objective-C
C++
import TCCCSDK

// Switch to speaker
tcccSDK.getDeviceManager().setAudioRoute(.TCCCAudioRouteSpeakerphone)
// Mute
tcccSDK.mute()
// Unmute
tcccSDK.unmute()
// Import the OC header file
#import "TCCCSDK/tccc/platform/apple/TCCCWorkstation.h"

// Switch to speaker
[[self.tcccSDK getDeviceManager] setAudioRoute:TCCCAudioRouteSpeakerphone];
// Mute
[self.tcccSDK mute];
// Unmute
[self.tcccSDK unmute];
#include "TCCCSDK/tccc/include/ITCCCWorkstation.h"
using namespace tccc;

// Switch to speaker
tcccSDK->getDeviceManager()->setAudioRoute(TCCCAudioRoute::TCCCAudioRouteSpeakerphone);
// Mute
tcccSDK->mute();
// Unmute
tcccSDK->unmute();

Debugging APIs

API
Description
Obtains the SDK version.
Sets the log output level.
Enables/Disables console log print.
Calls an experimental API.

Sample Code for Obtaining SDK Version

Swift
Objective-C
C++
import TCCCSDK

// Obtain SDK version number
let version = TCCCWorkstation.getSDKVersion()
// Import the OC header file
#import "TCCCSDK/tccc/platform/apple/TCCCWorkstation.h"

// Obtain SDK version number
NSString* version = [TCCCWorkstation getSDKVersion];
#include "TCCCSDK/tccc/include/ITCCCWorkstation.h"
using namespace tccc;

// Obtain SDK version number
tcccSDK->getSDKVersion();

Error and Warning Events

API
Description
Error event callback
Warning event callback

Sample Code for Handling Error Event Callbacks

Swift
Objective-C
C++
import TCCCSDK

func onError(_ errCode: TCCCErrorCode, errMsg: String, extInfo: [AnyHashable : Any]?) {
// Error event callback
}
func onWarning(_ warningCode: TCCCCWarningCode, warningMsg: String, extInfo: [AnyHashable : Any]?) {
// Warning event callback
}

// Set the TCCC event callback
tcccSDK.addTcccListener(self)
// Import the OC header file
#import "TCCCSDK/tccc/platform/apple/TCCCWorkstation.h"

#pragma mark - TCCCDelegate
- (void)onError:(TCCCErrorCode)errCode errMsg:(NSString * _Nonnull)errMsg extInfo:(nullable NSDictionary *)extInfo {
// Error event callback
}
- (void)onWarning:(TCCCCWarningCode)warningCode warningMsg:(NSString *_Nonnull)warningMsg extInfo:(nullable NSDictionary *)extInfo {
// Warning event callback
}

// Set the TCCC event callback
[self.tcccSDK addTcccListener:self];
#include "TCCCSDK/tccc/include/ITCCCWorkstation.h"
using namespace tccc;

// Set the callback. TCCCCallbackImpl needs to be derived from ITCCCCallback
class TCCCCallbackImpl:public ITCCCCallback {
public:
TCCCCallbackImpl() {}
~TCCCCallbackImpl() {}
// Error event callback
void onError(TCCCError errCode, const char* errMsg, void* extraInfo) {}
// Warning event callback
void onWarning(TCCCCWarning warningCode, const char* warningMsg, void* extraInfo) {}
};
TCCCCallbackImpl* tcccCallback = new TCCCCallbackImpl();
tcccSDK->addCallback(tcccCallback);

Call Event Callback

API
Description
New session event, including inbound and outbound calls
Session end event
Callback for volume feedback
Real-time statistics callback of network quality

Sample Code for Answer and Agent Hang-up Event Callbacks

Swift
Objective-C
C++
import TCCCSDK

func onNewSession(_ info: TXSessionInfo) {
// New session event, including inbound and outbound calls
}
func onAccepted(_ sessionId: String) {
// Remote party answered event
}
func onEnded(_ reason: TXEndedReason, reasonMessage: String, sessionId: String) {
// Call end event
}

// Set the TCCC event callback
tcccSDK.addTcccListener(self)
// Import the OC header file
#import "TCCCSDK/tccc/platform/apple/TCCCWorkstation.h"

- (void)onNewSession:(TXSessionInfo *)info {
// New session event, including inbound and outbound calls
}
- (void)onEnded:(TXEndedReason)reason reasonMessage:(NSString *_Nonnull)reasonMessage sessionId:(NSString *_Nonnull)sessionId {
// Call end event
}
- (void)onAccepted:(NSString *_Nonnull)sessionId {
// Remote party answered event
}
// Set the TCCC event callback
[self.tcccSDK addTcccListener:self];
#include "TCCCSDK/tccc/include/ITCCCWorkstation.h"
using namespace tccc;

// Set the callback. TCCCCallbackImpl needs to be derived from ITCCCCallback
class TCCCCallbackImpl:public ITCCCCallback {
public:
TCCCCallbackImpl() {}
~TCCCCallbackImpl() {}
// New session event, including inbound and outbound calls
void onNewSession(TCCCSessionInfo info) {}
// Session end event
void onEnded(EndedReason reason, const char* reasonMessage, const char* sessionId) {}
};
TCCCCallbackImpl* tcccCallback = new TCCCCallbackImpl();
tcccSDK->addCallback(tcccCallback);

Event Callback of Connection with Cloud

API
Description
The connection between the SDK and the cloud has been disconnected.
The SDK is trying to reconnect to the cloud.
The connection between the SDK and the cloud has been restored.

Sample Code for Event Callback of Connection with Cloud

Swift
Objective-C
C++
import TCCCSDK

func onConnectionLost(_ serverType: TXServerType) {
// The connection between the SDK and the cloud has been disconnected
}
func onConnectionRecovery(_ serverType: TXServerType) {
// The SDK's connection with the cloud has been restored
}
func onTry(toReconnect serverType: TXServerType) {
// The SDK is trying to reconnect to the cloud
}

// Set the TCCC event callback
tcccSDK.addTcccListener(self)
// Import the OC header file
#import "TCCCSDK/tccc/platform/apple/TCCCWorkstation.h"

- (void)onConnectionLost:(TXServerType)serverType {
// The connection between the SDK and the cloud has been disconnected
}
- (void)onTryToReconnect:(TXServerType)serverType {
// The SDK is trying to reconnect to the cloud
}
- (void)onConnectionRecovery:(TXServerType)serverType {
// The SDK's connection with the cloud has been restored
}
// Set the TCCC event callback
[self.tcccSDK addTcccListener:self];
#include "TCCCSDK/tccc/include/ITCCCWorkstation.h"
using namespace tccc;

// Set the callback. TCCCCallbackImpl needs to be derived from ITCCCCallback
class TCCCCallbackImpl:public ITCCCCallback {
public:
TCCCCallbackImpl() {}
~TCCCCallbackImpl() {}
// The connection between the SDK and the cloud has been disconnected
void onConnectionLost(TCCCServerType serverType) {}
// The SDK is trying to reconnect to the cloud
void onTryToReconnect(TCCCServerType serverType) {}
// The SDK's connection with the cloud has been restored
void onConnectionRecovery(TCCCServerType serverType) {}
};
TCCCCallbackImpl* tcccCallback = new TCCCCallbackImpl();
tcccSDK->addCallback(tcccCallback);

API Error Codes

Basic Error Codes

Symbol
Value.
Meaning
ERR_SIP_SUCCESS
200
Execution succeeded.
ERR_UNRIGIST_FAILURE
20001
Login failed.
ERR_ANSWER_FAILURE
20002
Failed to answer the call, usually because the TRTC failed to enter the room.
ERR_SIPURI_WRONGFORMAT
20003
URI format error.
ERR_HTTP_REQUEST_FAILURE
-10001
HTTP request failed. Please check your network connection.
ERR_HTTP_TOKEN_ERROR
-10002
The token login ticket is incorrect or has expired.
ERR_HTTP_GETSIPINFO_ERROR
-10003
Failed to obtain the agent configuration. Please contact us.

SIP Error Codes

Symbol
Value.
Meaning
ERR_SIP_BAD_REQUEST
400
Error request.
ERR_SIP_UNAUTHORIZED
401
Unauthorized (username or password is incorrect).
ERR_SIP_AUTHENTICATION_REQUIRED
407
Proxy authentication required. Please check whether the login API has been called.
ERR_SIP_REQUESTTIMEOUT
408
Request timeout (network timeout).
ERR_SIP_REQUEST_TERMINATED
487
Request termination (network error, in case of network interruption).
ERR_SIP_SERVICE_UNAVAILABLE
503
Service not available.
ERR_SIP_SERVER_TIMEOUT
504
Service timeout.

Audio Device Error Codes

Symbol
Value.
Meaning
ERR_MIC_START_FAIL
-1302
Failed to start the microphone. The device's microphone configuration program (driver) is abnormal. Please disable and re-enable the device, restart the device, or update the configuration program.
ERR_MIC_NOT_AUTHORIZED
-1317
No access to the microphone. This usually occurs on mobile devices and may be because the user denied the access.
ERR_MIC_SET_PARAM_FAIL
-1318
Failed to set microphone parameters.
ERR_MIC_OCCUPY
-1319
The microphone is occupied. This occurs when, for example, the user is currently having a call on the mobile device.
ERR_MIC_STOP_FAIL
-1320
Failed to stop the microphone.
ERR_SPEAKER_START_FAIL
-1321
Failed to start the speaker, for example, on Windows or Mac.
ERR_SPEAKER_SET_PARAM_FAIL
-1322
Failed to set speaker parameters.
ERR_SPEAKER_STOP_FAIL
-1323
Failed to stop the speaker.
ERR_UNSUPPORTED_SAMPLERATE
-1306
Unsupported audio sample rate.

Network Error Codes

Symbol
Value.
Meaning
ERR_RTC_ENTER_ROOM_FAILED
-3301
Failed to enter the room. Please view -3301 in onError to confirm the message for the reason of the failure.
ERR_RTC_REQUEST_IP_TIMEOUT
-3307
Request for IP and Sig timed out. Please check whether your network is functioning properly and whether UDP is unblocked in your network firewall.
ERR_RTC_CONNECT_SERVER_TIMEOUT
-3308
Request for room entry timed out. Please check your network connection or whether you are on a VPN. You can also try switching to 4G for confirmation.
ERR_RTC_ENTER_ROOM_REFUSED
-3340
Room entry request was denied. Please check whether you are continually calling enterRoom to enter the room of the same ID.

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback