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, the current user is the determine in the login by the token

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=getUser, nullable) NXMUser *user;

    Swift

    var user: NXMUser? { 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.

Conversation

  • 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.

Call

  • 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

Push Notifications

  • 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 true

    Declaration

    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 true

    Declaration

    Objective-C

    - (nullable NXMPushPayload *)processNexmoPushPayload:
    (nonnull NSDictionary *)pushInfo;

    Swift

    func processNexmoPushPayload(_ pushInfo: [AnyHashable : Any]) -> NXMPushPayload?

    Parameters

    pushInfo

    The pushInfo