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 portal, 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',
  }
};
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.

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.

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.

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>

Sometimes our clients put the code from "Additional customisation" section of this guide into webpages and use "name" and "email" variables as in the code snippet. This means that you preset the name and email instead allowing for your visitors to fill in by themselves. To avoid that, please don't use "name" and "email" variable names in the "Additional customisation" code section.

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

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"

The above command returns JSON structured like this:

{
  "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

Invisibility

Hiding on mobile

Positioning

CSS for trigger button

Expand and Suspend

Events

signalzen.collapse

signalzen.messageReceived

signalzen.messageSent

Real world example

Troubleshooting

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

2. I enabled "Ask visitors for email and name before displaying live chat" but can't see the form in the widget.

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