NAV Navbar
shell ruby
  • Introduction
  • Authentication
  • Users
  • Messages
  • Errors
  • Introduction

    Welcome to the SignalZen API! You can use our API to access SignalZen API endpoints, which can get read-only information about your widget users and messages. This is a version number 1 of the API, later we will add more endpoints to make your API experience wider.

    We have language bindings in Shell and Ruby! 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.

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

    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.