Sparkcentral Messenger SDK

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. 

Create your 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.
    Note: This information is only displayed once, so it’s important to record it now.

Implement Messenger on your website

Latest version

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

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

The previous version can be found here: Sparkcentral Messenger SDK 1.25.7

Get started

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

  1. Paste the following code the end of the <head> section. (Make sure to copy it all!)

    <script>

    !function(s,c,o,i){var a,p,u,d=[],f=[];function e(){var n="2.1.0";try{if(!i)throw new Error(n);var e,t="https://cdn.sparkcentral.com/rtm/web/2.1.0/",r="sparkcentral";if((e="string"==typeof this.response?JSON.parse(this.response):this.response).url){var s=c.getElementsByTagName("script")[0],o=c.createElement("script");o.async=!0;var a=i.match(/([0-9]+)\.?([0-9]+)?\.?([0-9]+)?/),p=a&&a[1];if(a&&a[3])o.src=t+r+"."+i+".min.js";else{if(!(1<=p&&e["v"+p]))throw new Error(n);o.src=e["v"+p]}s.parentNode.insertBefore(o,s)}}catch(e){e.message===n&&console.error(e)}}s[o]={init:function(){a=arguments;var n={then:function(e){return f.push({type:"t",next:e}),n},catch:function(e){return f.push({type:"c",next:e}),n}};return n},on:function(){d.push(arguments)},render:function(){p=arguments},destroy:function(){u=arguments}},s.__onWebMessengerHostReady__=function(e){if(delete s.__onWebMessengerHostReady__,s[o]=e,a)for(var n=e.init.apply(e,a),t=0;t<f.length;t++){var r=f[t];n="t"===r.type?n.then(r.next):n.catch(r.next)}p&&e.render.apply(e,p),u&&e.destroy.apply(e,u);for(t=0;t<d.length;t++)e.on.apply(e,d[t])};var n=new XMLHttpRequest;n.addEventListener("load",e),n.open("GET","https://cdn.sparkcentral.com/rtm/web/2.1.0/loader.json",!0),n.responseType="json",n.send()}(window,document,"Sparkcentral","2");

    </script>

  2. Paste the init call code below toward the end of the <body> section. This initializes a basic Web Messenger without any special customizations. (Optional customizations are described in the next section.)
    • On the third line, insert your specific channel Integration ID. This is one of the pieces of text that is generated on channel creation.
    • The region field must be set according to your Sparkcentral instance. Sparkcentral is available in the following regions:
      Region Region identifier
      United States Leave unspecified
      European Union eu-1

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

Options

The following general settings can be changed.

Option Optional? Default value Description
integrationID No - Your app/integration ID
region Yes - The target region in which the app is located
jwt Yes - The token to authenticate your communication with the server
userId Yes - The user’s ID
authCode Yes - An auth code for linking to an existing conversation
locale Yes en-US

The locale used for date formatting using the `-` 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 not supported, it will fall back to 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 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 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 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.

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 calls-to-action 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.

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 options

Menu items can be enabled or disabled.

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 option

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'
}
]
}
]
}
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’
}
]

Embedded mode option

You have the option to set up the Web Messenger in an embedded mode. This lets you choose where you want the widget to be visible.

The following example illustrates what you need to set it up.

Note that for embedded mode to work, you must set the parameter of embedded to true and call the Sparkcentral.render() function manually.

Copy
Sparkcentral.init({
integrationId: 'INTEGRATION_ID_HERE',
embedded: true,
region: 'eu-1'
}).then(() => {
// Your code after init is complete
}
Sparkcentral.render(document.getElementById('chat-container'));
JavaScript

This sample embeds the Sparkcentral messenger within a DOM element with the id “chat-container”. If you open the web page, you will notice that it is no longer showing a button on the bottom right, but it is visible in the container element.

Use Contact Attributes to save specific messenger data

You can store information about the webpage and the user by using the Contact Attributes feature. To enable this, do the following:

  1. On the Settings tab, expand Agent Workspace and select Contact Attributes.
  2. Find one of the premade Contact Attributes in the list and toggle it to Enabled.

Now, when a client contacts you via the Sparkcentral Messenger plugin, that specific data will be stored inside of a Contact Attribute.

Available Contact Attributes for the Web Messenger plugin

  • Browser Language
  • First Name
  • Last Name
  • Page Domain
  • Page Title
  • Page URL
  • User Id

Use shortcodes to create a rich messaging experience

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

Available 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 shortcodes 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

Get started

iOS

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

Install the SDK dependency

First, 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, tell Xcode you are 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"

Objective-C

The first function to run is the following . Your app id should be changed 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

Download the class references for iOS and Android: 

https://www.hootsuite.com/uploads/downloadable-assets/sparkcentral-API-mobile-class-references.11.28.2020.zip

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'
}

Use 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

Download the class references for iOS and Android: 

https://www.hootsuite.com/uploads/downloadable-assets/sparkcentral-API-mobile-class-references.11.28.2020.zip