Sparkcentral Messenger SDK 1.25.7

The Sparkcentral Messenger SDK enables you to implement a customizable, fully-featured messenger on your website or inside your mobile app. This allows any customer who visits your website or uses your app to contact your support team directly, eliminating the need for your users to use Facebook, WhatsApp, or any other messaging platform. 

Implementing Messenger on your website

Latest version

The latest version of our Web Messenger SDK can be found here:

https://cdn.sparkcentral.com/rtm/web/1.25.7/loader.json

Get started

Create a channel

  1. On the Settings tab, expand Channels & Business Hours and select Channels.
  2. Select Add Channel, and then select Sparkcentral Messenger.
  3. In the window that appears, enter a name for your messenger channel. This name should be unique and specific to the location of your messenger, such as a specific web page or your mobile app. Select Next.
    Note: If the window doesn't appear, make sure your browser allows pop-ups from Sparkcentral.
  4. Save the information provided in the window that appears. This information will only be displayed once, so it’s important to record it now.

Implement the Web Messenger on your website

The following steps are required to get the Web Messenger to appear on your website.

At the end of your <head> tag, paste the following code. (Make sure to copy it all).

<script>

var loaderUrl = 'https://cdn.sparkcentral.com/rtm/web/1.25.7/loader.json'

!function(e,n,t,r){function s(){try{var e;if((e="string"==typeof this.response?JSON.parse(this.response):this.response).url){var t=n.getElementsByTagName("script")[0],r=n.createElement("script");r.async=!0,r.src=e.url,t.parentNode.insertBefore(r,t)}}catch(e){}}var o,p,a,c=[],i=[];e[t]={init:function(){o=arguments;var e={then:function(n){return i.push({type:"t",next:n}),e},catch:function(n){return i.push({type:"c",next:n}),e}};return e},on:function(){c.push(arguments)},render:function(){p=arguments},destroy:function(){a=arguments}},e.__onWebMessengerHostReady__=function(n){if(delete e.__onWebMessengerHostReady__,e[t]=n,o)for(var r=n.init.apply(n,o),s=0;s<i.length;s++){var u=i[s];r="t"===u.type?r.then(u.next):r.catch(u.next)}p&&n.render.apply(n,p),a&&n.destroy.apply(n,a);for(s=0;s<c.length;s++)n.on.apply(n,c[s])};var u=new XMLHttpRequest;u.addEventListener("load",s),u.open("GET",loaderUrl,!0),u.responseType="json",u.send()}(window,document,"Sparkcentral");

</script>

Paste the init call code below toward the end of the <body> section to initialize Messenger without any special customizations. On the third line, insert your specific channel App ID. This is one of the pieces of text that is generated on channel creation.

Copy
<script>
//TODO Sparkcentral APP_ID, replace this with your own to run this demo.
var appId = 'YOUR APP ID HERE';
//function to initialise Sparkcentral, this will also register all our events we want to listen on.
//this function will be called when the document finishes loading. (event in the end of this script tag)
function initialiseSparkcentral() {
 
//Display a message that there are unread messages
Sparkcentral.on('unreadCount', function(unreadCount) {
//create a message based on the unread messages count
var message = 'There are ' + unreadCount + ' unread messages.';
if(unreadCount == 1) {
message = 'There is one unread message.';
}
});
//Initialise Sparkcentral,
//Add your custom options here
Sparkcentral.init({
appId: appId,
businessName: 'Your business name here',
customText: {
headerText: 'Your header text here',
inputPlaceholder: 'Your input-placeholder here',
introductionText: 'Your introduction text here',
messageSending: 'Sending...',
messageDelivered: 'Delivered',
sendButtonText: 'Send',
},
customColors: {
brandColor: '000000',
conversationColor: '4690DC',
actionColor: '4690DC',
},
menuItems: {
imageUpload: 'true',
},
}).then(function() {
});
}
//when our document is finished loading, we'll initialisze our sparkcentral instance.
window.addEventListener('load', function() {
initialiseSparkcentral();
});
</script>

Customize your Web Messenger options

Several options are available for customizing your Web Messenger. The following is an example of a fully customized Web Messenger. Every option used is documented following the code snippet.

Adjust your region

The region field must be set according to your Sparkcentral instance. In the following initialization code, there is a field called region: 'eu-1'. This initializes the European version of the messenger. To access the United States messenger, leave the field unspecified.

Table of region identifiers
Region Region identifier
United States Leave unspecified
European Union eu-1

Options

The following general settings can be changed.

Table of general options
Option Optional? Default value Description
appId No Your app ID
region Yes The target region in which the app is located
jwt Yes Token to authenticate your communication with the server
userId Yes User’s ID
authCode Yes An auth code for linking to an existing conversation
locale Yes en-US Locale used for date formatting using the <language>-<COUNTRY> format. Language codes can be found here and country codes here.**Note 1 : ** The country part is optional, and if a country is either not recognized or supported, it will fallback to using the generic language. If the language isn’t supported, it will fallback to en-US.Note 2: this is only used for date formatting and doesn’t provide built-in translations for Web Messenger.
soundNotificationEnabled Yes TRUE Enables the sound notification for new messages
imageUploadEnabled Yes TRUE Enables the image upload feature.
embedded Yes FALSE Tells the widget it will be embedded. (see Embedded section below)
displayStyle Yes button Choose how the messenger will appear on your website. Must be either button or tab.
buttonIconUrl Yes When the displayStyle is button, you have the option of selecting your own button icon. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format.
buttonWidth Yes 58px When the displayStyle is button, you have the option of specifying the button width.
buttonHeight Yes 58px When the displayStyle is button, you have the option of specifying the button height.
businessName Yes A custom business name.
businessIconUrl Yes A custom business icon url. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format.
backgroundImageUrl Yes A background image url for the conversation. Image will be tiled to fit the window.
customColors Yes See below. Colors used in the Web Messenger UI.
customText Yes See the example below Strings used in the Web Messenger UI. You can use these to either customize the text or translate it. Note: Some strings include variables (surrounded by {}) which must remain in your customized text.
menuItems Yes See below.  
prechatCapture Yes See below.  

Color options

You can give your Web Messenger a custom look by editing the following settings.

Table of color options
Option Optional? Default value Description
brandColor Yes 65758e This color will be used in the messenger header and the button or tab in idle state. Must be a 3 or 6-character hexadecimal color.
conversationColor Yes 0099ff This color will be used for customer messages, quick replies and actions in the footer. Must be a 3 or 6-character hexadecimal color.
actionColor Yes 0099ff This color will be used for call-to-actions inside your messages. Must be a 3 or 6-character hexadecimal color.

Text options

Web Messenger has many text options to choose from. Here are a few examples.

Table of text options
Option Default value if not used
actionPostbackError An error occurred while processing your action. Please try again.
clickToRetry Message not delivered. Click to retry.
connectNotificationText Be notified inside your other apps when you get a reply.
connectNotificationSingleText Be notified when you get a reply.
connectNotificationSingleButtonText Turn on <name> notifications
connectNotificationOthersText others
conversationTimestampHeaderFormat MMMM D YYYY, h:mm A
fetchHistory Load more
fetchingHistory Retrieving history…
headerText How can we help?
inputPlaceholder Type a message…
introductionText We’re here to talk, so ask us anything!
invalidFileError Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).
locationNotSupported Your browser does not support location services or it’s been disabled. Please type your location instead.
locationSecurityRestriction This website cannot access your location. Please type your location instead.
locationSendingFailed Could not send location
locationServicesDenied This website cannot access your location. Allow access in your settings or type your location instead.
messageError An error occured while sending your message. Please try again.
messageIndicatorTitlePlural ({count}) New messages
messageIndicatorTitleSingular ({count}) New message
messageRelativeTimeDay {value}d ago
messageRelativeTimeHour {value}h ago
messageRelativeTimeJustNow Just now
messageRelativeTimeMinute {value}m ago
messageTimestampFormat h:mm A
messageSending Sending…
messageDelivered Delivered
sendButtonText Send
settingsHeaderText Settings
tapToRetry Message not delivered. Tap to retry.
unsupportedMessageType Unsupported message type.
unsupportedActionType Unsupported action type.
uploadDocument Upload document.
uploadInvalidError Invalid file.
uploadPhoto Upload photo.

Menu items

Menu items can be enabled or disabled.

Table of menu options
Option Optional? Default value Description
imageUpload Yes TRUE Enables the image upload menu item
fileUpload Yes TRUE Enables the file upload menu item
shareLocation Yes TRUE Enables the share location menu item

Prechat capture

This option allows you to have the Web Messenger automatically post a message to the user. You can implement a variety of messages. The following code snippet is the same as the one used in the earlier example.

Copy
prechatCapture: {
enabled: true,
fields: [
{
type: 'email',
name: 'email',
label: 'Email',
placeholder: 'your@email.com'
},
{
type: 'text',
name: 'company-website',
label: 'Company website',
placeholder: 'mycompany.com'
},
{
type: 'select',
name: 'company-size',
label: 'Company size',
placeholder: 'Choose a number...',
options: [
{
name: '1-10',
label: '1-10 employees'
},
{
name: '11-50',
label: '11-50 employees'
},
{
name: '51+',
label: '51+ employees'
}
]
}
]
}
Table of prechat options
Field Information
Email name: ‘Name of the field’,label: ‘Label name’,placeholder: ‘Placeholder text here'”
Text name: ‘Name of the field’,label: ‘Label name’,placeholder: ‘Placeholder text here'”
Select This is the format in which multiple options are added:options: [{name: ‘Name of the first option’,label: ‘Label of the first option’},{name: ‘Name of the second option’,label: ‘Label of the second option’},{name: ‘Name of the third option’,label: ‘Label of the third option’}]

Use shortcodes to create a rich messaging experience

Shortcodes are a useful way to create a beautiful messaging interface.

Available shortcodes

Table of shortcodes
Element Syntax Example
Link button %[]() %[Button label](http://anyurl.com)
Reply button %[](reply:) %[Button label](reply:PAYLOAD)
Location request button %[](location) %[Button label](location)
Image ![]() ![](http://url-of.the/image.jpg)

Link button

By using multiple Link button shortcodes, you can send the user multiple links in one message. An example:

%[Link to Facebook](https://facebook.com)

%[Link to Twitter](https://twitter.com)

%[Link to LinkedIn](https://linkedin.com)

multiple-links.png

Reply button

By using multiple Reply button short codes under each other in one message, you can offer the user a choice. For example:

%[Sales](reply:Sales)

%[Support](reply:Support)

%[Engineering](reply:Engineering)

reply-buttons.png

Location sharing button

This code allows you to ‘invite’ the user to share their location with you.

sharing-button.png

Images

You can send images and gifs using this shortcode.

gifs-shortcode.png

Implement Messenger in your mobile app

A great way to integrate Sparkcentral into your processes is by incorporating our In-App Messenger. This is an SDK we created that our clients can implement on their apps.

Available platforms

  • iOS
  • Android

Getting started

iOS

To use our SDK with your iOS application, you will need to add it to your Xcode project.

Installing the SDK dependency

The first thing to do is install CocoaPods. CocoaPods is a dependency manager for Swift and Objective C Cocoa projects.

To install it, run the following command in your terminal.

gem install cocoapods

Next, ell Xcode you will be using this pod/dependancy. To do so, create a file called “podfile” in the source folder of your project. In it, enter the following and save it:

Copy
project 'Location of your .xcproj file'
target 'YourApp' do
pod 'Sparkcentral'
end

Now run a command to tell Xcode to install the pod so you can use it. In your terminal, navigate to the source folder of your project. Type the following command in the terminal:

pod install

Navigate to your source folder and open Info.plist file. In it, add the following keys and values and save it.

Copy
<key>NSPhotoLibraryUsageDescription</key>
<string>${PRODUCT_NAME} will read your photo library to gather additional information</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>${PRODUCT_NAME} will write to your photo library to gather additional information</string>
<key>NSCameraUsageDescription</key>
<string>${PRODUCT_NAME} will use your camera to gather additional information</string>

Use the framework in your project

Objective C

Import the framework in your source code.

#import "Sparkcentral/Sparkentral.h"

The first function to run is the following. Your app ID should be change accordingly.

Copy
[Sparkcentral initWithSettings:[SKCSettings settingsWithAppId:@"YOUR_APP_ID"] completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
// Your code after init is complete
}];

Swift

Copy
Sparkcentral.initWith(SKCSettings(appId: "YOUR_APP_ID")) { (error: Error?, userInfo: [AnyHashable : Any]?) in
// Your code after init is complete
}

Class reference

The entire class reference can be found here: https://help.sparkcentral.com/class-references/ios/.

Android

Link the SDK dependency

Include the following code in your Gradle file:

Copy
repositories {
maven {
url "https://sparkc.bintray.com/rtm"
}
}
dependencies {
compile 'com.sparkcentral:core:latest.release'
compile 'com.sparkcentral:ui:latest.release'
}

Using the SDK

Initialize from your Application class. Add the following lines of code to your onCreate method on your Application class:

Copy
Sparkcentral.init(this, new Settings("YOUR_APP_ID"), new SparkcentralCallback() {
@Override
public void run(Response response) {
// Your code after init is complete
}
});

Make sure to replace YOUR_APP_ID with the app ID you generate when adding a new Web Messenger channel.

If you don’t have an Application class, you must create one to make sure Sparkcentral is always initialized properly.

Class reference

The entire class reference can be found here: https://help.sparkcentral.com/class-references/android/.