Skip to main content

  Article updated: September 21, 2021

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 will only be 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 following init call code 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:
      RegionRegion identifier
      United StatesLeave unspecified
      European Unioneu-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 valueDescription
integrationIDNo-Your app/integration ID
regionYes-The target region in which the app is located
jwtYes- The token to authenticate your communication with the server
userIdYes-The user’s ID
authCodeYes-An auth code for linking to an existing conversation
localeYesen-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.

soundNotificationEnabledYesTRUEEnables the sound notification for new messages
imageUploadEnabledYesTRUEEnables the image upload feature
embeddedYesFALSETells the widget it will be embedded (see following Embedded section)
displayStyleYesbuttonHow the messenger will appear on your website. Must be either button or tab.
buttonIconUrlYes-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.
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.
businessNameYes-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.
backgroundImageUrlYes-A background image URL for the conversation. Image will be tiled to fit the window.
customColors YesSee following sectionColors used in the Web Messenger UI.
customTextYesSee the following exampleStrings 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 the following section 
prechatCaptureYesSee the following section 

Color options

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

Option Optional? Default valueDescription
brandColor Yes65758eThis 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 Yes0099ff 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 Yes0099ff 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.

OptionDefault 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.
connectNotificationSingleTextBe notified when you get a reply.
connectNotificationSingleButtonText Turn on <name> notifications
connectNotificationOthersTextothers
conversationTimestampHeaderFormatMMMM D YYYY, h:mm A
fetchHistory Load more
fetchingHistory Retrieving history…
headerText How can we help?
inputPlaceholder Type a message…
introductionTextWe’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.
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 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.
uploadPhotoUpload photo.

Menu options

Menu items can be enabled or disabled.

OptionOptional?Default valueDescription
imageUpload YesTRUEEnables the image upload menu item
fileUpload YesTRUEEnables the file upload menu item
shareLocationYesTRUEEnables 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'
}
]
}
]
}
FieldInformation
Email

name: ‘Name of the field’,
label: ‘Label name’,
placeholder: ‘Placeholder text here'”

Textname: ‘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

ElementSyntaxExample
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)

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)

Location sharing button

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

Images

You can send images and gifs using this shortcode.

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

  1. Install CocoaPods.

    CocoaPods is a dependency manager for Swift and Objective C Cocoa projects.

  2. Run the following command in your terminal:

    gem install cocoapods

  3. 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
  4. 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

  5. Navigate to your source folder and open Info.plist. 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 integration ID should be changed accordingly.

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

Swift

Copy
Sparkcentral.initWith(SKCSettings(integrationId: "YOUR_INTEGRATION_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.6.30.2021.zip.

Android

Link the SDK dependency using Gradle. You can find the Sparkcentral SDK dependency on mavencentral (https://repo.maven.apache.org/maven2).

For more information about Gradle and declaring publicly-available repositories, see https://docs.gradle.org/current/userguide/declaring_repositories.html#sec:declaring_public_repository

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_INTEGRATION_ID"), new SparkcentralCallback() {
@Override
public void run(Response response) {
// Your code after init is complete
}
});

Make sure to replace YOUR_INTEGRATION_ID with the integration 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.6.30.2021.zip.