Article updated: September 21, 2021
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
- On the Settings tab, expand Channels & Business Hours and select Channels.
- Select Add Channel, and then select Sparkcentral Messenger.
- 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.
- 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 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.
<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.
| Region | Region identifier |
|---|---|
| United States | Leave unspecified |
| European Union | eu-1 |
Expand for codeSparkcentral.init({
appId: '<app-id>',
// Leave unspecified for US region (default)
region: 'eu-1',
// For authenticated mode
jwt: 'your_jwt',
userId: 'user_id',
locale: 'en-US',
customColors: {
brandColor: '65758e',
conversationColor: '65758e',
actionColor: '65758e',
},
menuItems: {
imageUpload: true,
fileUpload: true,
shareLocation: true
},
fixedIntroPane: false,
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'
}
]
}
]
},
customText: {
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...',
fileTooLargeError: 'Max file size limit exceeded ({size})',
fileTypeError: 'Unsupported file type.',
headerText: 'How can we help?',
imageClickToReload: 'Click to reload image.',
imageClickToView: 'Click to view {size} image.',
imagePreviewNotAvailable: 'Preview not available.',
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',
prechatCaptureGreetingText: 'Hi there \nTo start off, we\'d like to know a little bit more about you:',
prechatCaptureConfirmationText: 'Thanks for that! What can we help you with?',
sendButtonText: 'Send',
settingsHeaderText: 'Settings',
shareLocation: 'Share location',
tapToRetry: 'Message not delivered. Tap to retry.',
unsupportedMessageType: 'Unsupported message type.',
unsupportedActionType: 'Unsupported action type.',
uploadDocument: 'Upload document',
uploadInvalidError: 'Invalid file',
uploadPhoto: 'Upload photo',
}
}).then(function() {
// Your code after init is complete
});
initPromise.then(function() {
// do something
});
// pass it around...
initPromise.then(function() {
//do something else
});Options
The following general settings can be changed.
| 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 the following Embedded section) |
| 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 following section | Colors used in the Web Messenger UI. |
| customText | Yes | See 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. |
| menuItems | Yes | See following section | |
| prechatCapture | Yes | See following section |
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 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.
| 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.
| 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.
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 |
|---|---|
| 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
| 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 | ![]() |  |
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 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)
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
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:
project 'Location of your .xcproj file'
target 'YourApp' do
pod 'Sparkcentral'
endNow 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.
<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.
[Sparkcentral initWithSettings:[SKCSettings settingsWithAppId:@"YOUR_APP_ID"] completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
// Your code after init is complete
}];Swift
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.6.30.2021.zip.
Android
Link the SDK dependency
Include the following code in your Gradle file:
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:
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.6.30.2021.zip.