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 vladimir@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.
GET: http://api.smartsupp.com/test
Headers: {
"apiKey": "YOUR_API_KEY"
}
HTTP/1.1 200 OK
{
"success": true
}
In case of invalid apiKey (following error) please contact vladimir@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.
POST: http://api.smartsupp.com/accounts/create
{
"title": "Account name (not visible to clients)",
"lang": "en"
}
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.
POST: http://api.smartsupp.com/accounts/:aid/users/create
{
"role": "agent",
"email": "john@doe.com",
"fullname": "John Doe",
"password": "john.doe"
}
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
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."
}]
}
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
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 }
]
}]
}
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 }
]
}]
}