Skip to main content

  Article updated: January 04, 2022

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:

Get started

Create a channel

  1. Go to Admin settings, 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).


var loaderUrl = ''

!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(}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),"GET",loaderUrl,!0),u.responseType="json",u.send()}(window,document,"Sparkcentral");


Paste the following init call code 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.

//TODO Sparkcentral APP_ID, replace this with your own to run this demo.
var appId = 'YOUR APP ID HERE';
//function to initialize 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
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 initialize our sparkcentral instance.
window.addEventListener('load', function() {

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
RegionRegion identifier
United StatesLeave unspecified
European Unioneu-1


The following general settings can be changed.

Table of general options
OptionOptional?Default valueDescription
appIdNoYour app ID
regionYesThe target region in which the app is located
jwtYesToken to authenticate your communication with the server
userIdYesUser’s ID
authCodeYesAn auth code for linking to an existing conversation
localeYesen-USLocale 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.
soundNotificationEnabledYesTRUEEnables the sound notification for new messages
imageUploadEnabledYesTRUEEnables the image upload feature.
embeddedYesFALSETells the widget it will be embedded. (see the following Embedded section)
displayStyleYesbuttonChoose how the messenger will appear on your website. Must be either button or tab.
buttonIconUrlYesWhen 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.
buttonWidthYes58pxWhen the displayStyle is button, you have the option of specifying the button width.
buttonHeightYes58pxWhen the displayStyle is button, you have the option of specifying the button height.
businessNameYesA custom business name.
businessIconUrlYesA custom business icon URL. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format.
backgroundImageUrlYesA background image URL for the conversation. Image will be tiled to fit the window.
customColorsYesSee following sectionColors used in the Web Messenger UI.
customTextYesSee the following example 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.
menuItemsYesSee following section 
prechatCaptureYesSee following section 

Color options

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

Table of color options
OptionOptional?Default valueDescription
brandColorYes65758eThis 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.
conversationColorYes0099ffThis color will be used for customer messages, quick replies and actions in the footer. Must be a 3 or 6-character hexadecimal color.
actionColorYes0099ffThis 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
OptionDefault value if not used
actionPostbackErrorAn error occurred while processing your action. Please try again.
clickToRetryMessage not delivered. Click to retry.
connectNotificationTextBe notified inside your other apps when you get a reply.
connectNotificationSingleTextBe notified when you get a reply.
connectNotificationSingleButtonTextTurn on <name> notifications
conversationTimestampHeaderFormatMMMM D YYYY, h:mm A
fetchHistoryLoad more
fetchingHistoryRetrieving history…
headerTextHow can we help?
inputPlaceholderType a message…
introductionTextWe’re here to talk, so ask us anything!
invalidFileErrorOnly images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).
locationNotSupportedYour browser does not support location services or it’s been disabled. Please type your location instead.
locationSecurityRestrictionThis website cannot access your location. Please type your location instead.
locationSendingFailedCould not send location
locationServicesDeniedThis website cannot access your location. Allow access in your settings or type your location instead.
messageErrorAn error occurred while sending your message. Please try again.
messageIndicatorTitlePlural({count}) New messages
messageIndicatorTitleSingular({count}) New message
messageRelativeTimeDay{value}d ago
messageRelativeTimeHour{value}h ago
messageRelativeTimeJustNowJust now
messageRelativeTimeMinute{value}m ago
messageTimestampFormath:mm A
tapToRetryMessage not delivered. Tap to retry.
unsupportedMessageTypeUnsupported message type.
unsupportedActionTypeUnsupported action type.
uploadDocumentUpload document.
uploadInvalidErrorInvalid file.
uploadPhotoUpload photo.

Menu items

Menu items can be enabled or disabled.

Table of menu options
OptionOptional?Default valueDescription
imageUploadYesTRUEEnables the image upload menu item
fileUploadYesTRUEEnables the file upload menu item
shareLocationYesTRUEEnables 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.

prechatCapture: {
enabled: true,
fields: [
type: 'email',
name: 'email',
label: 'Email',
placeholder: ''
type: 'text',
name: 'company-website',
label: 'Company website',
placeholder: ''
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
Emailname: ‘Name of the field’,label: ‘Label name’,placeholder: ‘Placeholder text here'”
Textname: ‘Name of the field’,label: ‘Label name’,placeholder: ‘Placeholder text here'”
SelectThis 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
Link button%[]()%[Button label](
Reply button%[](reply:)%[Button label](reply:PAYLOAD)
Location request button%[](location)%[Button label](location)

Link button

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

%[Link to Facebook](

%[Link to Twitter](

%[Link to LinkedIn](

A sample message with three button links

Reply button

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




A sample message with three reply buttons

Location sharing button

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

A sample message with a button reading, Share your location with us


You can send images and gifs using this shortcode.

A sample message with a GIF

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


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:

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

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.

<string>${PRODUCT_NAME} will read your photo library to gather additional information</string>
<string>${PRODUCT_NAME} will write to your photo library to gather additional information</string>
<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.

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


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

Class reference

Download the class references for iOS and Android:


Link the SDK dependency

Include the following code in your Gradle file:

repositories {
maven {
url ""
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:

Sparkcentral.init(this, new Settings("YOUR_APP_ID"), new SparkcentralCallback() {
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

Download the class references for iOS and Android:


Can't find what you're looking for? We're here to help