Introduction
Welcome to the SignalZen API! You can use our Frontend (JavaScript) API to do advanced integration on your website or use backend API to access SignalZen API endpoints, which can get read-only information about your widget users and messages. This page includes a version number 1 Frontend (JavaScript) API and a version number 1 of the Backend API, later we will add more endpoints to make your API experience wider.
You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
JS API
<script type="text/javascript">
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
As stated in the Integration page of your website inside the Console, you need to initialize our widget by a simple command which looks like on the right side of this page.
However, there are more advanced options to initialize and work with the widget. We separated the concerns of working with the widget into a few sections (see below).
Language
<script type="text/javascript">
var _sz = {
language: 'danish'
};
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
Usually by creating translations of the widget, we determine the language that the visitors see by their browser settings. There is an alternative way for this purpose, you can set the language by the integration code which takes precedence over the browser language. See the code example on the right how to do this.
Metadata about a visitor
<script type="text/javascript">
var _sz = {
userData: {
reference: "your-visitor-user-id",
email: 'your-visitor@email.com',
name: 'Your visitor name',
'some custom attribute': 'your visitor custom attribute'
}
};
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
Some websites have login area, where you have certain context which you want to be visible in a chat page in order to recognise the chat owner in more comfortable way. It's possible to set that data by JS configuration and send each time the chat owner sends a message. See the code example on the right how to do this.
Widget colors
<script type="text/javascript">
var _sz = {
colors: {
primary: '#046ee5',
secondary: '#f5f7f8',
footer: '#ffffff',
error: '#cccccc',
popup: '#ffffff',
popupClose: '#ffffff',
popupCloseSymbol: '#9c9c9c',
popupFormInputBorder: '#9c9c9c',
badge: '#c30606',
footerEmojisPopup: '#ffffff',
footerOptions: '#b2b3b4',
operatorMessages: '#ebeff0',
formInput: '#ffffff',
formInputBorder: '#ffffff',
formButton: '#0fc306',
formPlaceholder: '#949595',
textPrimary: '#ffffff',
textError: '#ffffff',
textTime: '#b5b7b8',
textTimeSeparator: '#8e9192',
textUserMessage: '#ffffff',
textFormInput: '#000000',
textFormTitle: '#8e9192',
textFormButton: '#ffffff',
onlineIndicator: '#0fc306'
}
};
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
You might not like the default color palette of the widget, so you can configure it yourself by a big variety of settings which are self explanatory and you can experiment with the colors of your choice. See the code example on the right how to do this.
Chat icon
<script type="text/javascript">
var _sz = {
chatIcon: {
width: 200,
height: 50,
closed: 'https://your-image-address.com/widget-still.gif',
open: 'https://your-image-address.com/widget-open.gif',
loading: 'https://your-image-address.com/widget-loading.gif'
}
};
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
Changing the icon image for the widget is possible and requires 5 settings under namespace chatIcon
to be injected into your widget's code.
The width
setting should contain your images of the icon width.
The height
setting should contain your images of the icon height.
The 3 other settings (closed
, open
and loading
) should contain the URL addresses to your widget icon images.
Each image should represent different states of the chat widget. When the widget is closed, SignalZen will show closed
image URL as the chat button. When the widget is opened, SignalZen will show open
image URL as the chat button. When the widget is in loading state, SignalZen will show loading
image URL as the chat button.
Invisibility
<script type="text/javascript">
var _sz = {
invisible: true
};
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
Depending on your needs, you can start the widget in invisibility mode, which means that all the widget will be hidden until the point you decide differently. See the code example on the right how to start the widget invisible.
In order to make the widget visible, just call SignalZen.show()
or SignalZen.hide()
if you want to hide it again.
Hiding on mobile
<script type="text/javascript">
var _sz = {
hideOnMobile: true
};
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
You may want to disable your chat widget on mobile devices in order not to make your webpage too stuffy. Achieving that is simple as a flag to pass into the widget's initialization options.
Positioning
<script type="text/javascript">
var _sz = {
layout: {
horizontalOffset: 100, // Allows to tune the position your chat box to right or left in pixels
verticalOffset: 100, // Allows to tune the position your chat box to top or bottom in pixels
horizontalPosition: 'left', // Possible values: 'left', 'right'
verticalPosition: 'top', // Possible values: 'top', 'bottom'
}
};
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
Depending on your needs, you can change position of the chat widget trigger button and chat box.
Just add the layout
options that should be sufficient to position SignalZen widget at the right part of your website.
Embeding in a div
<script type="text/javascript">
var _sz = {
renderInContainerId: 'my_widget_container_id'
};
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
There might be cases, when you want to embed the live chat box directly in a desired div element. We support this need by renderInContainerId
attribute.
All what you need to do is to create a div in your HTML code with your desired id and point SignalZen code snippet to use it for rendering the chat box inside. You should set that div's height and width by CSS because the chat box will use that sizes for the layout which will be 100% of your defined sizes of the div.
When renderInContainerId
is used, no closing options of the chat widget will be visible for visitors. However, by using SignalZen.show()
and SignalZen.hide()
you can control that from your JavaScript code.
That means, that you could even go further and develop your custom open/close chat widget button.
CSS for trigger button
<style>
// Changing the size of the button:
#signalzen_widget__root a {
width: 50px !important;
height: 50px !important;
}
</style>
<script type="text/javascript">
var _sz=_sz||{};_sz.appId="YOUR_APP_ID",function(){var e=document.createElement("script");e.src="https://cdn.signalzen.com/signalzen.js",e.setAttribute("async","true"),document.documentElement.firstChild.appendChild(e);var t=setInterval(function(){"undefined"!=typeof SignalZen&&(clearInterval(t),new SignalZen(_sz).load())},10)}();
</script>
Sometimes you may want to change the widget trigger button CSS. You can do that by using #signalzen_widget__root a
CSS selector.
Please don't forget to use !important
declaration for each of your new style settings.
Expand and Suspend
The command SignalZen.expand()
will open the widget chat window instead of showing just the chat circle with the chat icon.
The command SignalZen.suspend()
will minimise the chat window to display only chat circle with the chat icon.
Events
We support multiple events that come with metadata about each of them. This could be used for an advanced integration if you want to know in your JavaScript implementation when the chat is opened, a message is received or sent. Let's start with the events list and wrap up with a single example how to catch an event.
signalzen.collapse
This event is called when the chat is expanded or suspended and by capturing it, you can get an object with key status
which will return the action nature. Currently, the status value can be opened
or closed
.
signalzen.messageReceived
This event is called when a visitor receives a chat message not depending on the message nature, it means it can be even an auto invitation message. The event metadata contains message information which you can check yourself while dealing with the implementation.
signalzen.messageSent
This event is called when a visitor sends a chat message. The event metadata contains message information which you can check yourself while dealing with the implementation.
signalzen.chatStarted
This event is called when a visitor is created on our system, just after the first message. The event metadata contains user information which you can check yourself while dealing with the implementation.
Real world example
window.addEventListener('signalzen.collapse', function (e) {
if (e.detail.status === 'opened') {
alert('The chat is opened!');
} else {
alert('The chat is closed!');
}
}, false);
Let's say you have a webpage where you need to react somehow when the widget collapse event happens. In this case, you need to put an event listener in your code and wait for the event to happen. Once the event happens, you can execute appropriate your own JS code. See the example on the right of this page. Be aware, that the metadata is contained in the listener function argument, under the .detail
scope.
Troubleshooting
Please don't hesitate to contact us directly, but before doing that, take a look to these mostly common questions.
1. The widget icon stucks at the loading state forever.
Double check if your integration code is placed correctly according to our guidance in the Integration Wizard page. It might be that our integration implementation is conflicting with your other JavaScript libraries used in your website. The best known case is Pace library which is incompatible with our service, so if you have it or other libraries dependent on it installed, please add this (right side of the screen) before SignalZen integration snippet in your webpage:
<script type="text/javascript">
window.paceOptions = {
ajax: {
trackWebSockets: false,
ignoreURLs: [/signalzen/]
}
};
</script>
Authentication
To authorize, use this code:
require 'httparty'
api_secret = 'YOUR_API_SECRET'
response = HTTParty.get('https://api.signalzen.com/external/users', headers: { 'Authorization' => "Bearer #{api_secret}", 'Accept' => 'application/vnd.signalzen.v1+json' })
result = JSON.parse(response.body)
# With shell, you can just pass the correct headers with each request
curl "https://api.signalzen.com/external/users" \
-H "Authorization: Bearer YOUR_API_SECRET" \
-H "Accept: application/vnd.signalzen.v1+json"
Make sure to replace
YOUR_API_SECRET
with your API secret key.
SignalZen uses API Secret Keys to allow access to the Backend API. You can register a new API Secret Key for your website at our sign up page.
SignalZen expects for the API Secret Key to be included in all API requests to the server in a header that looks like the following:
Authorization: Bearer YOUR_API_SECRET
We also expect for the Accept header to be included in all API requests to the server:
Accept: application/vnd.signalzen.v1+json
Both headers MUST be sent together with each request, otherwise you can not access the resources.
Users
Get Users
require 'httparty'
api_secret = 'YOUR_API_SECRET'
response = HTTParty.get('https://api.signalzen.com/external/users', headers: { 'Authorization' => "Bearer #{api_secret}", 'Accept' => 'application/vnd.signalzen.v1+json' })
result = JSON.parse(response.body)
curl "https://api.signalzen.com/external/users" \
-H "Authorization: Bearer YOUR_API_SECRET" \
-H "Accept: application/vnd.signalzen.v1+json"
The above command returns JSON structured like this:
{
"limit":50,
"offset":0,
"total":1,
"users":[
{
"id":1,
"name":"John Smith",
"email":"john.smith@gmail.com",
"reference":"123",
"created_at":"2017-11-25T20:27:42.000Z",
"updated_at":"2017-11-25T20:27:42.000Z",
"online_at":"2017-11-25T20:27:42.000Z",
"last_url":"https://google.com",
"user_attributes":[
{"name":"company","value":"John limited"}
]
}
]
}
This endpoint retrieves users.
HTTP Request
GET https://api.signalzen.com/external/users
Query Parameters
Parameter | Default | Description |
---|---|---|
offset | 0 | Use it to scroll through all users list |
limit | 50 | Greater than 0 and lower than 100 |
Get a Specific User
require 'httparty'
api_secret = 'YOUR_API_SECRET'
user_id = 123
response = HTTParty.get("https://api.signalzen.com/external/users/#{user_id}", headers: { 'Authorization' => "Bearer #{api_secret}", 'Accept' => 'application/vnd.signalzen.v1+json' })
result = JSON.parse(response.body)
curl "https://api.signalzen.com/external/users/123" \
-H "Authorization: Bearer YOUR_API_SECRET" \
-H "Accept: application/vnd.signalzen.v1+json"
{
"id":123,
"name":"John Smith",
"email":"john.smith@gmail.com",
"reference":"123",
"created_at":"2017-11-25T20:27:42.000Z",
"updated_at":"2017-11-25T20:27:42.000Z",
"online_at":"2017-11-25T20:27:42.000Z",
"last_url":"https://google.com",
"user_attributes":[
{"name":"company","value":"John limited"}
]
}
This endpoint retrieves a specific user.
HTTP Request
GET https://api.signalzen.com/external/users/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the user to retrieve |
Messages
Get Messages
require 'httparty'
api_secret = 'YOUR_API_SECRET'
user_id = 123
response = HTTParty.get("https://api.signalzen.com/external/users/#{user_id}/messages", headers: { 'Authorization' => "Bearer #{api_secret}", 'Accept' => 'application/vnd.signalzen.v1+json' })
result = JSON.parse(response.body)
curl "https://api.signalzen.com/external/users/123/messages" \
-H "Authorization: Bearer YOUR_API_SECRET" \
-H "Accept: application/vnd.signalzen.v1+json"
The above command returns JSON structured like this:
{
"limit": 50,
"offset": 0,
"total": 2,
"messages": [
{
"id": 1,
"body": "test chat message",
"read_by_user": true,
"created_at": "2018-02-09T17:18:50.000Z",
"file_url": null,
"auto_invitation": false,
"sender_type": "user",
"read_by_operator": true,
"sender": {
"id": 1,
"name": "David Smith",
"email": "visitor@gmail.com"
}
},
{
"id": 2,
"body": "test response from operator",
"read_by_user": false,
"created_at": "2018-02-09T18:18:38.000Z",
"file_url": null,
"auto_invitation": false,
"sender_type": "operator",
"read_by_operator": true,
"sender": {
"id": 1,
"forename": "John",
"surname": "Smith",
"email": "operator@gmail.com",
"picture_thumb_url": null
}
}
]
}
This endpoint retrieves messages of a user chat.
HTTP Request
GET https://api.signalzen.com/external/users/<USER_ID>/messages
Query Parameters
Parameter | Default | Description |
---|---|---|
USER_ID | - | User id which owns the chat |
offset | 0 | Use it to scroll through all messages list |
limit | 50 | Greater than 0 and lower than 100 |
Get a Specific Message
require 'httparty'
api_secret = 'YOUR_API_SECRET'
user_id = 123
message_id = 1234
response = HTTParty.get("https://api.signalzen.com/external/users/#{user_id}/messages/#{message_id}", headers: { 'Authorization' => "Bearer #{api_secret}", 'Accept' => 'application/vnd.signalzen.v1+json' })
result = JSON.parse(response.body)
curl "https://api.signalzen.com/external/users/123/messages/1234" \
-H "Authorization: Bearer YOUR_API_SECRET" \
-H "Accept: application/vnd.signalzen.v1+json"
The above command returns JSON structured like this:
{
"id": 1234,
"body": "test chat message",
"read_by_user": true,
"created_at": "2018-02-09T17:18:50.000Z",
"file_url": null,
"auto_invitation": false,
"sender_type": "user",
"read_by_operator": true,
"sender": {
"id": 1,
"name": "David Smith",
"email": "visitor@gmail.com"
}
}
This endpoint retrieves a specific message of a user chat.
HTTP Request
GET https://api.signalzen.com/external/users/<USER_ID>/messages/<ID>
URL Parameters
Parameter | Description |
---|---|
USER_ID | The ID of the user |
ID | The ID of the message to retrieve |
Errors
The SignalZen API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API secret key is wrong. |
403 | Forbidden -- The request is forbidden. |
404 | Not Found -- The specified resource could not be found. |
405 | Method Not Allowed -- You tried to access a resurce with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
410 | Gone -- The resource requested has been removed from our servers. |
429 | Too Many Requests -- You're making too many requests! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |