Dimelo Class Reference

Inherits from NSObject
Declared in Dimelo.h

Overview

Dimelo is a central object to access Dimelo API.

You instantiate Dimelo with an API key, configure the delegate, information about the current user and use it to display a chat view controller.

There are two modes in which API instance can be configured: a secure and less secure one.

Recommended mode: with server-signed authentication token.

``` // Instantiate dimelo with public api key and an optional hostname. Dimelo* dimelo = [[Dimelo sharedInstance] initWithApiKey:@“public api key” hostname:@“api.example.com” delegate:self];

// Assign optional properties to include in authenticated JWT token. dimelo.userIdentifier = @“optional user account ID”; dimelo.authenticationInfo = @{ }

// Retrieve a dictionary to be signed by your server within a JWT token: NSDictionary* dict = dimelo.jwtDictionary;

// Send dict to your server and receive a signed JWT token in response. // Token must be signed with a secret key corresponding to public API key that you use in your app.

// Assign a token to dimelo.jwt so it can be used in all communications. dimelo.jwt = jwtFromServer; ```

Now Dimelo will be able to make requests to Dimelo servers, send and receive chat messages etc.

Unsafe mode which does not require signing a JWT token by your server:

``` // Instantiate dimelo with secret api key and an optional hostname. Dimelo* dimelo = [[Dimelo sharedInstance] initWithApiSecret:@“secret api key” hostname:@“api.example.com” delegate:self];

// Assign optional properties to include in authenticated JWT token. dimelo.userIdentifier = @“optional user account ID”; dimelo.authenticationInfo = @{ }

// Dimelo will compute and sign a valid JWT token automatically each time you change one of the properties above. // All communications will include the signed JWT token as if they were signed by your server. ```

WARNING: Note that anyone who extracts your secret API key will be able to impersonate any user if they know their userIdentifier. User’s data is relatively safe if userIdentifier is not well-known or cannot be easily guessed.

Other Methods

+ disableLibraryAttachment

disable state of individual attachment category or all of them

+ (void)disableLibraryAttachment

Declared In

Dimelo.h

+ disableCameraAttachment

+ (void)disableCameraAttachment

+ disableLocationAttachment

+ (void)disableLocationAttachment

+ disableAttachments

+ (void)disableAttachments

+ isLibraryAttachmentEnabled

Get state of individual attachment category or all of them

+ (bool)isLibraryAttachmentEnabled

Declared In

Dimelo.h

+ isCameraAttachmentEnabled

+ (bool)isCameraAttachmentEnabled

+ isLocationAttachmentEnabled

+ (bool)isLocationAttachmentEnabled

+ isAttachmentsEnabled

+ (bool)isAttachmentsEnabled

Setting up an API client

+ sharedInstance

Returns a shared API client initialized with config from DimeloConfig.plist

+ (instancetype)sharedInstance

Discussion

For correct operation you will have to provide a valid signed JWT token via jwt property. To do so, fill in userIdentifier, authenticationInfo and send the resulting jwtDictionary to your server.

This is a recommended way to access Dimelo API.

Declared In

Dimelo.h

– initWithApiKey:delegate:

Initializes a new API client with a public API key and a delegate.

- (id)initWithApiKey:(NSString *)apiKey delegate:(id<DimeloDelegate>)delegate

Parameters

apiKey

public hex-encoded API key, typically specific to your app.

delegate

an instance conforming to DimeloDelegate protocol.

Discussion

Delegate must not be nil as it is needed to correctly show the chat in various usage scenarios.

For correct operation you will have to provide a valid signed JWT token via jwt property. To do so, fill in userIdentifier, authenticationInfo and send the resulting jwtDictionary to your server.

This is a recommended way to access Dimelo API.

Declared In

Dimelo.h

– initWithApiKey:hostname:delegate:

Initializes a new API client with a public API key, custom hostname and a delegate.

- (id)initWithApiKey:(NSString *)apiKey hostname:(NSString *)hostname delegate:(id<DimeloDelegate>)delegate

Parameters

apiKey

public hex-encoded API key, typically specific to your app.

hostname

a Dimelo API hostname specific to your app.

delegate

an instance conforming to DimeloDelegate protocol.

Discussion

Delegate must not be nil as it is needed to correctly show the chat in various usage scenarios.

For correct operation you will have to provide a valid signed JWT token via jwt property. To do so, fill in userIdentifier, authenticationInfo and send the resulting jwtDictionary to your server.

This is a recommended way to access Dimelo API.

Declared In

Dimelo.h

– initWithApiSecret:delegate:

Initializes a new API client with a secret API key and a delegate.

- (id)initWithApiSecret:(NSString *)apiSecret delegate:(id<DimeloDelegate>)delegate

Parameters

apiSecret

a hex-encoded API secret key, typically specific to your app.

delegate

an instance conforming to DimeloDelegate protocol.

Discussion

Delegate must not be nil as it is needed to correctly show the chat in various usage scenarios.

This mode is less secure than initWithApiKey:delegate: because shared secret is stored inside the app.

Declared In

Dimelo.h

– initWithApiSecret:hostname:delegate:

Initializes a new API client with a secret API key, custom hostname and a delegate.

- (id)initWithApiSecret:(NSString *)apiSecret hostname:(NSString *)hostname delegate:(id<DimeloDelegate>)delegate

Parameters

apiSecret

a hex-encoded API secret key, typically specific to your app.

hostname

a Dimelo API hostname specific to your app.

delegate

an instance conforming to DimeloDelegate protocol.

Discussion

Delegate must not be nil as it is needed to correctly show the chat in various usage scenarios.

This mode is less secure than initWithApiKey:hostname:delegate: because shared secret is stored inside the app.

Declared In

Dimelo.h

– setApiSecret:

Per-application API secret key, typically specific to your app.

- (void)setApiSecret:(NSString *)apiSecret

Discussion

API secret is always represented in hex format, e.g. @"ab12d1a2a9349797b807589e7e1635cb760d69de3a8241070b1682a1bdbd6d70".

Declared In

Dimelo.h

  delegate

Delegate object to present a chat view controller and react to various optional notifications.

@property (nonatomic, weak) id<DimeloDelegate> delegate

See Also

Declared In

Dimelo.h

  apiKey

Per-application public API key that identifies all requests to Dimelo.

@property (nonatomic, copy) NSString *apiKey

Discussion

API Key is always represented in hex format, e.g. @"ab12d1a2a9349797b807589e7e1635cb760d69de3a8241070b1682a1bdbd6d70".

Declared In

Dimelo.h

  hostname

Per-application hostname used to connect to Dimelo backend.

@property (nonatomic, copy) NSString *hostname

Declared In

Dimelo.h

  installationIdentifier

Per-installation identifier generated when the component is instantiated for the first time within the app.

@property (nonatomic, readonly) NSString *installationIdentifier

Declared In

Dimelo.h

  userIdentifier

Per-user unique identifier used to link messages sent from different devices to a single person.

@property (nonatomic, copy) NSString *userIdentifier

Discussion

User identifier could be an arbitrary string that makes sense in your application: an email, an account number or a UUID.

You can initialize and use Dimelo before user is logged-in, but after he has logged in, set the userIdentifier to let Dimelo know the real identity of the user.

If userIdentifier is nil, user will be uniquely identified on the server by the installationIdentifier.

Declared In

Dimelo.h

  authenticationInfo

Additional fields to be added to the JWT dictionary under “extra” key.

@property (nonatomic, copy) NSDictionary *authenticationInfo

Discussion

You must make sure only PropertyList-compatible items a present inside this dictionary.

Declared In

Dimelo.h

  userName

Optional name of the person to be sent to Dimelo.

@property (nonatomic, copy) NSString *userName

Declared In

Dimelo.h

  jwt

Complete serialized JWT token.

@property (nonatomic, copy) NSString *jwt

Discussion

If you use instantiation with public API key and your server signs JWT token, set this property with a JWT provided by your server.

If you instantiate Dimelo with a secret API key, this property is computed automatically.

Declared In

Dimelo.h

  jwtDictionary

JWT dictionary to be signed. Computed out of apiKey, installationIdentifier, userIdentifier, authenticationInfo.

@property (nonatomic, readonly) NSDictionary *jwtDictionary

Discussion

Send this dictionary to your app’s server to sign with a shared secret corresponding to API key.

If you instantiate Dimelo with API secret, this dictionary will be used to compute jwt property automatically.

Declared In

Dimelo.h

  messageContextInfo

Arbitrary contextual info attached to a message.

@property (nonatomic, copy) NSDictionary *messageContextInfo

Discussion

Attached only to the first message after a new value was specified.

Example: user selects a category of a problem (“Technical” or “Sales”) and then contacts the support. First message indicates what type of the problem user is talking about.

Declared In

Dimelo.h

Displaying Chat View

– displayChatView

Asks delegate to display the chat view.

- (void)displayChatView

Discussion

This method is called internally, but it is also available for you to display the chat from a single convenient place.

Declared In

Dimelo.h

– chatViewController

Creates a new instance of a chat view controller.

- (UIViewController *)chatViewController

Return Value

A UIViewController containing a chat view.

Discussion

Use standard -presentViewController:animated:completion: and —dismissViewController messages to show/hide it.

You can present it modally or in UITabViewController.

Use transitioningDelegate for custom presentation.

Declared In

Dimelo.h

Remote Notifications

  deviceToken

Device token for remote notifications. Optional.

@property (nonatomic, copy) NSData *deviceToken

Discussion

Override -application:didRegisterForRemoteNotificationsWithDeviceToken: and set this property to a provided deviceToken.

Declared In

Dimelo.h

  developmentAPNS

Flag to tell Dimelo server to send push notifications using development channel.

@property (nonatomic) BOOL developmentAPNS

Discussion

Set this to YES in order to receive notifications on development builds. By default, Dimelo server will send notifications to production environment and development builds will not receive such notifications.

Default is NO.

Declared In

Dimelo.h

– consumeReceivedRemoteNotification:

Attempts to process the remote notification.

- (BOOL)consumeReceivedRemoteNotification:(NSDictionary *)dictionary

Parameters

dictionary

a userInfo dictionary provided by the OS.

Return Value

YES if notification is consumed by Dimelo and should not be processed by your app.

NO if notification does not belong to Dimelo and should be processed by your app.

Discussion

Returns YES if this notification belongs to this Dimelo instance and user. Otherwise returns NO.

If the app was activated due to this notification, delegate is asked to display the chat.

If the app was active already, it displays the notification on top of the screen. When user taps it, delegate is asked to display the chat.

If it returns YES do not pass the notification data to the rest of your app.

Recommended usage:

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { if ([self.dimelo consumeReceivedRemoteNotification:userInfo]) { return; } // You app's handling of this notification... }

Declared In

Dimelo.h

Accessing Unread Count

  unreadCount

Number of unread messages or other events to which user hasn’t reacted yet.

@property (nonatomic, readonly) NSInteger unreadCount

Discussion

You can display this as a badge on a button that opens the chat.

Default value is 0.

Declared In

Dimelo.h

  updateAppBadgeNumber

Whether the app’s icon badge is automatically updated with unreadCount value.

@property (nonatomic) BOOL updateAppBadgeNumber

Discussion

If YES, updates app’s icon badge automatically to reflect unreadCount.

Set it to NO to fully control app’s badge number.

The badge is updated also by push notifications. To avoid Dimelo notifications changing your app’s badge number, disable automatic badge update on the Dimelo administration website.

Default is YES.

Declared In

Dimelo.h

– noteUnreadCountDidChange

Sends notifications to NSNotificationCenter and notifies the delegate about unreadCount change. Does not affect the value itself.

- (void)noteUnreadCountDidChange

Discussion

This method is called automatically when unreadCount is changed due to new data received from the server. It may be useful to call it manually when you want to refresh counters after the views are presented without them having explicit references to Dimelo instance (NSNotification object will store reference to Dimelo instance).

Declared In

Dimelo.h

– fetchUnreadCountWithCompletionHandler:

Fetch unreadCount.

- (void)fetchUnreadCountWithCompletionHandler:(void ( ^ ) ( NSInteger unreadCount , NSError *error ))completion

Discussion

In case of error completion will be called with NSNotFound value and the corresponding error. Completion is called on main thread.

NSErrors of domain DimeloHTTPErrorDomain will mirror the HTTP code from Dimelo backend’s response in their own code property. You may want to handle special HTTP code responses like 429 Too many requests for example.

Declared In

Dimelo.h

Application language

  language

@property (nonatomic) NSString *language

Basic Customization

  tintColor

Tint color for aux controls: Close button, Send button, cursor etc.

@property (nonatomic) UIColor *tintColor

Declared In

Dimelo.h

  navigationBarTintColor

Bar tint color for navigation bar (sets barTintColor property).

@property (nonatomic) UIColor *navigationBarTintColor

Declared In

Dimelo.h

  navigationBarColor

Background color for navigation bar (sets backgroundColor property).

@property (nonatomic) UIColor *navigationBarColor

Declared In

Dimelo.h

  title

Title for the chat.

@property (nonatomic, copy) NSString *title

Discussion

Used only if titleView is nil.

Declared In

Dimelo.h

  titleView

Title view for the chat.

@property (nonatomic) UIView *titleView

Discussion

If not nil, overrides title value.

Declared In

Dimelo.h

  backgroundView

Background view of the chat.

@property (nonatomic, readonly) UIView *backgroundView

Discussion

You may customize its backgroundColor or place arbitrary views inside it.

Declared In

Dimelo.h

  messageFont

Font for user and agent messages.

@property (nonatomic) UIFont *messageFont

Declared In

Dimelo.h

  systemMessageFont

Font for system messages.

@property (nonatomic) UIFont *systemMessageFont

Declared In

Dimelo.h

  userMessageTextColor

Foreground color for user’s message text.

@property (nonatomic) UIColor *userMessageTextColor

Declared In

Dimelo.h

  agentMessageTextColor

Foreground color for agent’s message text.

@property (nonatomic) UIColor *agentMessageTextColor

Declared In

Dimelo.h

  systemMessageTextColor

Foreground color for system notification message text.

@property (nonatomic) UIColor *systemMessageTextColor

Declared In

Dimelo.h

  userMessageBackgroundColor

Background color for user message bubbles.

@property (nonatomic) UIColor *userMessageBackgroundColor

Discussion

This color is applied when userMessageBubbleImage has template rendering mode (see UIImageRenderingMode). Default image is configured this way.

Declared In

Dimelo.h

  agentMessageBackgroundColor

Background color for agent message bubbles.

@property (nonatomic) UIColor *agentMessageBackgroundColor

Discussion

This color is applied when agentMessageBubbleImage has template rendering mode (see UIImageRenderingMode). Default image is configured this way.

Declared In

Dimelo.h

  systemMessageBackgroundColor

Background color for system message bubbles.

@property (nonatomic) UIColor *systemMessageBackgroundColor

Discussion

This color is applied when systemMessageBubbleImage has template rendering mode (see UIImageRenderingMode). Default image is configured this way.

Declared In

Dimelo.h

  dateFont

Font for the date label.

@property (nonatomic) UIFont *dateFont

Declared In

Dimelo.h

  dateTextColor

Text color for the date label.

@property (nonatomic) UIColor *dateTextColor

Declared In

Dimelo.h

  dateFormatter

Date formatter instance used to format the date label.

@property (nonatomic) NSDateFormatter *dateFormatter

Declared In

Dimelo.h

  errorIconColor

Color for the error icon.

@property (nonatomic) UIColor *errorIconColor

Declared In

Dimelo.h

  agentNameFont

Font for agent’s name.

@property (nonatomic) UIFont *agentNameFont

Declared In

Dimelo.h

  agentNameColor

Text color for agent’s name.

@property (nonatomic) UIColor *agentNameColor

Declared In

Dimelo.h

  loadMoreMessagesButtonTextColor

Text color for the button “load more messages”.

@property (nonatomic) UIColor *loadMoreMessagesButtonTextColor

Discussion

If this property is nil (default), this button is colored using tintColor.

Declared In

Dimelo.h

  disabledSendButtonColor

Color for the button “send” in the disabled state.

@property (nonatomic) UIColor *disabledSendButtonColor

Discussion

If this property is nil (default), this button is colored into [UIColor grayColor].

Declared In

Dimelo.h

  messageFieldFont

Font for the message field input

@property (nonatomic) UIFont *messageFieldFont

Discussion

If this property is nil (default), default font is used

Declared In

Dimelo.h

  defaultFont

Default font

@property (nonatomic) UIFont *defaultFont

Discussion

If this property is nil (default), default system font is used

Declared In

Dimelo.h

Advanced Customization

  agentNameInsets

Insets for agent name label placed under the message bubble.

@property (nonatomic) UIEdgeInsets agentNameInsets

Discussion

These insets should be in sync with agentMessageBubbleImage.

Declared In

Dimelo.h

  userMessageBubbleImage

Resizable (9-part) image to decorate user text bubble.

@property (nonatomic) UIImage *userMessageBubbleImage

Declared In

Dimelo.h

  agentMessageBubbleImage

Resizable (9-part) image to decorate agent text bubble.

@property (nonatomic) UIImage *agentMessageBubbleImage

Declared In

Dimelo.h

  systemMessageBubbleImage

Resizable (9-part) image to decorate system text bubble.

@property (nonatomic) UIImage *systemMessageBubbleImage

Declared In

Dimelo.h

  userMessageBubbleInsets

Insets for text in user’s message bubble.

@property (nonatomic) UIEdgeInsets userMessageBubbleInsets

Declared In

Dimelo.h

  agentMessageBubbleInsets

Insets for text in agent’s message bubble.

@property (nonatomic) UIEdgeInsets agentMessageBubbleInsets

Declared In

Dimelo.h

  systemMessageBubbleInsets

Insets for text in system message bubble.

@property (nonatomic) UIEdgeInsets systemMessageBubbleInsets

Declared In

Dimelo.h

  userAttachmentBubbleImage

Resizable (9-part) image to mask user’s attachment (alpha channel is used as a mask).

@property (nonatomic) UIImage *userAttachmentBubbleImage

Discussion

By default, the same as userMessageBubbleImage.

Declared In

Dimelo.h

  agentAttachmentBubbleImage

Resizable (9-part) image to mask agent’s attachment (alpha channel is used as a mask).

@property (nonatomic) UIImage *agentAttachmentBubbleImage

Discussion

By default, the same as agentMessageBubbleImage.

Declared In

Dimelo.h

  userAttachmentBubbleInsets

Insets for user’s attachment preview bubble.

@property (nonatomic) UIEdgeInsets userAttachmentBubbleInsets

Declared In

Dimelo.h

  agentAttachmentBubbleInsets

Insets for agent’s attachment preview bubble.

@property (nonatomic) UIEdgeInsets agentAttachmentBubbleInsets

Declared In

Dimelo.h

  inputBarTintColor

Bar tint color of the input bar.

@property (nonatomic) UIColor *inputBarTintColor

Declared In

Dimelo.h

  inputBarBackgroundColor

Background color of the input bar.

@property (nonatomic) UIColor *inputBarBackgroundColor

Declared In

Dimelo.h

  attachmentIcon

Icon to be displayed on “attach” button in the input bar.

@property (nonatomic) UIImage *attachmentIcon

Declared In

Dimelo.h

  keyboardAppearance

Keyboard appearance for a system keyboard.

@property (nonatomic) UIKeyboardAppearance keyboardAppearance

Discussion

Default is UIKeyboardAppearanceDefault.

Declared In

Dimelo.h