NXMClient
Objective-C
@interface NXMClient : NSObject
Swift
class NXMClient : NSObject
You use a NXMClient instance to utilise the services provided by the Conversation API in your app.
A session is the period during which your app is connected to NexmoConversation API. Sessions are established for the length of time given when the authToken was created.
Tokens also have a lifetime and can optionally be one-shot which will allow a single login only, before the authToken becomes invalid for another login attempt. If the authToken is revoked while a session is active the session may be terminated by the server. It is only possible to have a single session active over a socket.io connection at a time. Session multiplexing is not supported.
Note
The connection uses socket.io for both web and mobile clients. Upon a successful socket.io connection the client needs to authenticate itself. This is achieved by sending a login request via -[NXMClient loginWithAuthToken:]
and get the answer in the delegate -[NXMClient setDelegate:]
.
Warning
Unless otherwise specified, all the methods invoked by this client are executed asynchronously.
For the security of your Nexmo account, you should not embed directly your credentials authToken as strings in the app you submit to the App Store.
Remember to logout when needed in order to remove current user and disconnect from the underlying connection. Example usage:
[myClient logout];
-
Shared instance of the NXMClient object
Declaration
Objective-C
@property (class, nonatomic, readonly, nonnull) NXMClient *shared;
Swift
class var shared: NXMClient { get }
-
Get the current connection state
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readonly, getter=getConnectionStatus) NXMConnectionStatus connectionStatus;
Swift
var connectionStatus: NXMConnectionStatus { get }
-
Get the current user authToken
Declaration
Objective-C
@property (nonatomic, readonly, getter=getToken, nullable) NSString *authToken;
Swift
var authToken: String? { get }
-
Get NXMClient.shared configuration
Declaration
Objective-C
@property (nonatomic, readonly, getter=getConfiguration, nullable) NXMClientConfig *configuration;
Swift
var configuration: NXMClientConfig? { get }
-
Set shared NXMClient configuration. Must be called before [NXMClient shared].
Declaration
Objective-C
+ (void)setConfiguration:(nonnull NXMClientConfig *)configuration;
Swift
class func setConfiguration(_ configuration: NXMClientConfig)
Parameters
configuration
NXMClient configuration object.
-
Set NXMClient delegate
Declaration
Objective-C
- (void)setDelegate:(nonnull id<NXMClientDelegate>)delegate;
Swift
func setDelegate(_ delegate: NXMClientDelegate)
Parameters
delegate
a
NXMClientDelegate
object. -
Check if the login connection status is connected
Declaration
Objective-C
- (BOOL)isConnected;
Swift
func isConnected() -> Bool
Return Value
YES if connected.
-
Login with current authToken the response in NXMClientDelegate:didChangeConnectionStatus
Declaration
Objective-C
- (void)loginWithAuthToken:(nonnull NSString *)authToken;
Swift
func login(withAuthToken authToken: String)
Parameters
authToken
user authentication authToken
-
Refresh the current user authToken
Declaration
Objective-C
- (void)updateAuthToken:(nonnull NSString *)authToken;
Swift
func updateAuthToken(_ authToken: String)
-
Logout the current user, the response in NXMClientDelegate:didChangeConnectionStatus
Declaration
Objective-C
- (void)logout;
Swift
func logout()
-
Returns the registered device ID. If the device ID is not yet registered, it is created and stored before being returned.
Declaration
Objective-C
- (nonnull NSString *)getDeviceId;
Swift
func getDeviceId() -> String
Return Value
Device ID.
-
Get a conversation object by id
Declaration
Objective-C
- (void)getConversationWithUuid:(nonnull NSString *)conversationId completion:(void (^_Nullable)(NSError *_Nullable, NXMConversation *_Nullable)) completion;
Swift
func getConversationWithUuid(_ conversationId: String, completion: ((Error?, NXMConversation?) -> Void)? = nil)
Parameters
conversationId
Conversation id
completion
A completion block with an error object if one occurred.
-
Create a new conversation with specific name: it is a unique per nexmo application
Declaration
Objective-C
- (void)createConversationWithName:(nonnull NSString *)name completionHandler: (void (^_Nullable)(NSError *_Nullable, NXMConversation *_Nullable)) completionHandler;
Swift
func createConversation(withName name: String, completionHandler: ((Error?, NXMConversation?) -> Void)? = nil)
Parameters
name
Conversation name
completionHandler
A completion block with an error object if one occurred.
-
Deprecated
use getConversationsPageWithSize:(NSInteger) order:(NXMPageOrder) filter:(NSString*) completionHandler instead
Get conversations page
Declaration
Objective-C
- (void)getConversationsPageWithSize:(NSInteger)size order:(NXMPageOrder)order completionHandler: (void (^_Nullable)(NSError *_Nullable, NXMConversationsPage *_Nullable)) completionHandler;
Swift
func getConversationsPage(withSize size: Int, order: NXMPageOrder, completionHandler: ((Error?, NXMConversationsPage?) -> Void)? = nil)
Parameters
size
Page size
order
Page order
completionHandler
A completion block with an error object if one occurred.
-
Get conversations page
Declaration
Objective-C
- (void)getConversationsPageWithSize:(NSInteger)size order:(NXMPageOrder)order filter:(NSString *_Nullable)filter completionHandler: (void (^_Nullable)(NSError *_Nullable, NXMConversationsPage *_Nullable)) completionHandler;
Swift
func getConversationsPage(withSize size: Int, order: NXMPageOrder, filter: String?, completionHandler: ((Error?, NXMConversationsPage?) -> Void)? = nil)
Parameters
size
Page size
order
Page order
filter
“LEFT”, “INVITED” or “JOINED”
completionHandler
A completion block with an error object if one occurred.
-
Uploads an attachment message to Vonage Media Service.
Declaration
Objective-C
- (void)uploadAttachmentWithType:(NXMAttachmentType)type name:(nonnull NSString *)name data:(nonnull NSData *)data completionHandler:(void (^_Nullable)(NSError *_Nullable, NSDictionary *_Nullable)) completionHandler;
Swift
func uploadAttachment(with type: NXMAttachmentType, name: String, data: Data, completionHandler: ((Error?, [AnyHashable : Any]?) -> Void)? = nil)
Parameters
type
The type of the attachment following NXMAttachmentType enum.
name
A name identifier of the attachment.
data
The data of the attachment in a NSData representation.
completionHandler
A completion block with an error object if one occurred.
-
Deprecated
Use inAppCallWithCallee:completionHandler: or serverCallWithCallee:customData:completionHandler: instead
Create a new call to user
Declaration
Objective-C
- (void)call:(nonnull NSString *)callee callHandler:(NXMCallHandler)callHandler completionHandler:(void (^_Nullable)(NSError *_Nullable, NXMCall *_Nullable))completionHandler;
Swift
func call(_ callee: String, callHandler: NXMCallHandler, completionHandler: ((Error?, NXMCall?) -> Void)? = nil)
Parameters
callee
The user id, name or PSTN numbers to call
callHandler
The type of the call (InApp/Server)
completionHandler
A completion block with an error object if one occurred
-
Create a new in-app call to user
Declaration
Objective-C
- (void)inAppCallWithCallee:(nonnull NSString *)callee completionHandler: (void (^_Nullable)(NSError *_Nullable, NXMCall *_Nullable))completionHandler;
Swift
func inAppCall(withCallee callee: String, completionHandler: ((Error?, NXMCall?) -> Void)? = nil)
Parameters
callee
User id or name to call
completionHandler
A completion block with an error object if one occurred
-
Create a new server call to user
Declaration
Objective-C
- (void)serverCallWithCallee:(nonnull NSString *)callee customData:(nullable NSDictionary *)customData completionHandler: (void (^_Nullable)(NSError *_Nullable, NXMCall *_Nullable))completionHandler;
Swift
func serverCall(withCallee callee: String, customData: [AnyHashable : Any]?, completionHandler: ((Error?, NXMCall?) -> Void)? = nil)
Parameters
callee
User id, name or PSTN number to call
customData
Optional custom data
completionHandler
A completion block with an error object if one occurred
-
Reconnect a call
Declaration
Objective-C
- (void)reconnectCallWithConversationId:(nonnull NSString *)conversationId andLegId:(nonnull NSString *)legId completionHandler:(void (^_Nullable)(NSError *_Nullable, NXMCall *_Nullable)) completionHandler;
Swift
func reconnectCall(withConversationId conversationId: String, andLegId legId: String, completionHandler: ((Error?, NXMCall?) -> Void)? = nil)
Parameters
conversationId
The conversation id
legId
The leg id
completionHandler
A completion block with an error object if one occurred or a call if it successfully reconnected
-
Enable push notification for specific device
Declaration
Objective-C
- (void)enablePushNotificationsWithPushKitToken:(nullable NSData *)pushKitToken userNotificationToken: (nullable NSData *)userNotificationToken isSandbox:(BOOL)isSandbox completionHandler: (void (^_Nullable)(NSError *_Nullable)) completionHandler;
Swift
func enablePushNotifications(withPushKitToken pushKitToken: Data?, userNotificationToken: Data?, isSandbox: Bool, completionHandler: ((Error?) -> Void)? = nil)
Parameters
pushKitToken
The PushKit token
userNotificationToken
The User Notifications token
isSandbox
Toggle Apple sandbox environment
completionHandler
A completion block with an error object if one occurred.
-
Disable push notification for current device
Declaration
Objective-C
- (void)disablePushNotifications: (void (^_Nullable)(NSError *_Nullable))completionHandler;
Swift
func disablePushNotifications(_ completionHandler: ((Error?) -> Void)? = nil)
Parameters
completionHandler
A completion block with an error object if one occurred.
-
Check if a push notification is a NexmoPush, Call this method on incoming push
Declaration
Objective-C
- (BOOL)isNexmoPushWithUserInfo:(nonnull NSDictionary *)userInfo;
Swift
func isNexmoPush(userInfo: [AnyHashable : Any] = [:]) -> Bool
Parameters
userInfo
The pushInfo
Return Value
YES if it is a nexmo push.
-
Deprecated
Use processNexmoPushPayload instead.
Process Nexmo push, Call this method when
-[NXMClient isNexmoPushWithUserInfo:]
returns trueDeclaration
Objective-C
- (void)processNexmoPushWithUserInfo:(nonnull NSDictionary *)userInfo completionHandler: (void (^_Nullable)(NSError *_Nullable))completionHandler;
Swift
func processNexmoPush(userInfo: [AnyHashable : Any] = [:], completionHandler: ((Error?) -> Void)? = nil)
Parameters
userInfo
The pushInfo
completionHandler
A completion block with an error object if one occurred.
-
Process Nexmo push, Call this method when
-[NXMClient isNexmoPushWithUserInfo:]
returns trueDeclaration
Objective-C
- (nullable NXMPushPayload *)processNexmoPushPayload: (nonnull NSDictionary *)pushInfo;
Swift
func processNexmoPushPayload(_ pushInfo: [AnyHashable : Any]) -> NXMPushPayload?
Parameters
pushInfo
The pushInfo