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.

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

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.

You must replace YOUR_API_SECRET with your API secret key that belongs to your website. You can find the API secret key in the Integrations page of your website while logged in as admin of your website at our Console.

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.

Introduction

JS API

Language

Metadata about a visitor

Widget colors

Chat icon

Invisibility

Hiding on mobile

Positioning

Embeding in a div

CSS for trigger button

Expand and Suspend

Events

signalzen.collapse

signalzen.messageReceived

signalzen.messageSent

signalzen.chatStarted

Real world example

Troubleshooting

1. The widget icon stucks at the loading state forever.

Authentication

Users

Get Users

HTTP Request

Query Parameters

Get a Specific User

HTTP Request

URL Parameters

Messages

Get Messages

HTTP Request

Query Parameters

Get a Specific Message

HTTP Request

URL Parameters

Errors