REST API Guide

Allows automated creation of Smartsupp accounts, users, triggers (auto-messages) and more. It's useful if you want to create and setup Smartsupp accounts and users in high volume. You might want to use REST API if you are a developer, Smartsupp partner or a big company handling large number of accounts. Check out REST API PHP wrapper on Github.

Resource types

Account

Account is typically created for one company. Every account has unique account ID, which is returned when account is created. You can use Smartsupp on unlimited number of domains under one account. For an account you can create users, triggers, offline emails and hooks. By default account is created empty, with no users and no triggers (auto-messages). lang defines the language of chat box and transactional emails.

User

User is a person responsible for chat communication with web visitors. User is created under an account. User can either use a web dashboard or a XMPP IM client to communicate with visitors. User can have 2 roles. agent can only chat with visitors. admin can access all features. Admin can modify chat box design, add other agents and admins, access billing and more.

Trigger

Trigger is an automated message sent to visitors based on predefined rules (e.g. if visitor is on pricing page for more than 3 minutes, send text "Hello, can I help you select the right plan?"). You can target visitor by country, city, time spent on site and more. More about triggers.

Hook

Hooks allow you to export chat statistics or chat conversations to 3rd party systems (helpdesk, CRM or your own internal system).

Get Started

Smartsupp REST API uses only GET and POST methods. POST method is used to create or update resources. Parameters are transferred via JSON data. Other calls like delete or get resources, use GET method and parameters are transferred via http query parameters. All responses is in JSON format or without content. We are respecting HTTP response codes. Success response has code 2xx. Error response has code 4xx. Every error response contains error type and error message

REST API testing

To test your API calls we recommend to use postman chrome extension. You can configure headers, get params, see responses, states, errors and more.

Authentication

Unique and private apiKey is used for authentication. Please contact tomas@smartsupp.com to get one. Your apiKey must be used with every API call. It's possible to set apiKey in request header or send it as GET parameter (using request header is recommended).

To test your apiKey call this URL with request header apiKey: You can simulate call with postman chrome extension.

Request

GET: http://api.smartsupp.com/test
Headers: {
	"apiKey": "YOUR_API_KEY"
}

Response

HTTP/1.1 200 OK
{
	"success": true
}

In case of invalid apiKey (following error) please contact tomas@smartsupp.com

HTTP/1.1 401 Unauthorized
{
	"error": "AuthError",
	"message": "No account found for apiKey xxxx."
}

Create an account

You can create a Smartsupp account with mandatory parameters listed in documentation.

Account creation will return 2 values. id is a unique number of the account, use it in API calls to modify given account. accountKey - to be inserted in the chat code (shown lower). Title is an internal account name and lang is the default language of dashboard.

Request

POST: http://api.smartsupp.com/accounts/create
{
	"title": "Account name (not visible to clients)",
	"lang": "en"
}

Response

HTTP/1.1 200 OK
{
	"id": "1234",
	"title": "Account name (not visible to clients)",
	"lang": "en",
	"accountKey": "14dcb138dae8a700612b39bbc5f5572377f167"
}

You can preview chat box design of a created Smartsupp account on following link. It takes the account ID as a parameter.

http://www.smartsupp.com/widget?accountKey=ACCOUNT_KEY

You need to implement this chat code on the website(s) where you want to use Smartsupp. Insert the chat code between tags <head> and </head>. (Put your accountKey instead of YOUR_ACCOUNT_KEY)

<script type="text/javascript">
var _smartsupp = _smartsupp || {};
_smartsupp.key = "YOUR_ACCOUNT_KEY";
window.smartsupp||(function(d) {
	var s,c,o=smartsupp=function(){ o._.push(arguments)};o._=[];
	s=d.getElementsByTagName('script')[0];c=d.createElement('script');
	c.type='text/javascript';c.charset='utf-8';c.async=true;
	c.src='//www.smartsuppchat.com/loader.js';s.parentNode.insertBefore(c,s);
})(document);
</script>

Create a user

For every account you need to create at least one user, who will be communicating with web visitors. User email has to be unique and is used along with password as login credentials. User's name is shown in chat box, visible to web visitors. User must be given one of two roles. agent can only chat with visitors. admin can access all features. Admin can modify chat box design, add other agents and admins, access billing and more.

User can start chatting with visitors using dashboard on Smartsupp.com or a 3rd-party XMPP IM client.

Request

POST: http://api.smartsupp.com/accounts/:aid/users/create
{
	"role": "agent",
	"email": "john@doe.com",
	"fullname": "John Doe",
	"password": "john.doe"
}

Response

HTTP/1.1 200 OK
{
	"id": "3434",
	"role": "agent",
	"email": "john@doe.com",
	"fullname": "John Doe",
	"avatar": "",
	"note": ""
}

XMPP login

For login to 3rd-party XMPP client use uidXXXX@smartsupp.com as login email, where XXXX is user id (e.g. uid1234@smartsupp.com). Password is the same as user password. Don't use your user email for login to XMPP client as it won't work!

FAST login

With your apiKey and your user id you can login into Smartsupp dashboard using this link:

http://dashboard.smartsupp.com/sign/in?apiKey=API_KEY&uid=USER_ID&lang=en&status=online

Create trigger

You can create triggers (auto-messages) to automatically engage web visitors based on predefined rules. How to correctly define a trigger is explained in this article. You can deactivate triggers to keep them for later use by setting the active parameter to false

Request

POST: http://api.smartsupp.com/accounts/:aid/triggers/create
{
	"active": true,
	"name": "1st visit greeting",
	"description": "Greeting message to a visitor who visits your website for the 1st time",
	"event": "onload",
	"conditions": [
		{ "name": "delay_site", "value": 60 },
		{ "name": "is_visitor_send_message", "value": false },
		{ "name": "is_visitor_served", "value": false },
		{ "name": "number_of_visits", "value": 1 }
	],
	"actions": [{
		"name": "message",
		"agent_nick": "Support",
		"message": "Hello, we have noticed you are here for the 1st time. If you have any questions, do not hesitate to get in touch."
	}]
}

Response

HTTP/1.1 200 OK
{
	"id": "758",
	"active": true,
	"name": "1st visit greeting",
	"description": "Greeting message to a visitor who visits your website for the 1st time",
	"event": "onload",
	"only_once": true,
	"constraints": "all",
	"conditions": [
		{ "name": "delay_site", "value": 60 },
		{ "name": "is_visitor_send_message", "value": false },
		{ "name": "is_visitor_served", "value": false },
		{ "name": "number_of_visits", "value": 1 }
	],
	"actions": [{
		"name": "message",
		"agent_nick": "Support",
		"message": "Hello, we have noticed you are here for the 1st time. If you have any questions, do not hesitate to get in touch."
	}]
}

Configure office hours

Request

POST: http://api.smartsupp.com/accounts/:aid/officehours/update
{
	"active": true
	"days": [1,2,6,0],
	"timezone": 1,
	"config": [{
		"dow": 1,
		"times": [
			{ "from": 480, "to": 705 },
			{ "from": 780, "to": 1020 }
		]
	}, {
		"dow": 2,
		"times": [
			{ "from": 480, "to": 705 }
		]
	}]
}

Response

HTTP/1.1 200 OK
{
	"active": true
	"days": [1,2,6,0],
	"timezone": 1,
	"config": [{
		"dow": 1,
		"times": [
			{ "from": 480, "to": 705 },
			{ "from": 780, "to": 1020 }
		]
	}, {
		"dow": 2,
		"times": [
			{ "from": 480, "to": 705 }
		]
	}]
}

API resources doc