API Documentation
REST API Reference
By using the REST API, you can integrate our Co-browsing technology into your own application or build a thin layer around our technology. You can completely customize Surfly and automate the management of client and agent creation through the REST API.
The Surfly REST API allows you to integrate the functionality of our dashboard in a programmatic manner. With our API you can do the following things:
-
Agents - Manage your agents
-
Sessions - Get an overview of all your sessions
-
Screenshots - Create screenshots of your co-browsing sessions
-
Clients - Create new clients (reseller only)
-
Servers - Get a list of all available Surfly public cloud servers
-
History - Get an overview of sessions history
-
Webhooks - Manage your webhooks
Below you can find detailed code examples illustrating how to make the REST calls. You will need your REST API key (which can be found in the integration panel, just below the widget code).
Note: The rate limit for making REST API calls is 100 req/min/IP address
Agents ¶
Agents Collection ¶
Headers
Content-Type: application/json
Body
[
{
"agent_id": 1,
"agent_name": "Peter Pan",
"agent_email": "peter@neverland.net",
"last_login": "2020-02-03T11:03:39.323310Z",
"role": "agent",
"available": true
}
]
List all agentsGET/agents/?api_key={API_KEY}
List all AGENTS
cURL example:
curl --include \
'https://surfly.com/v2/agents/?api_key=API_KEY&free=true'
Response Body:
A list of objects containing the following parameters:
Name | Description | Example |
---|---|---|
agent_id | ID of the agent | 1 |
agent_name | name of the agent | Peter Pan |
agent_email | email address of the agent | peter@neverland.net |
last_login | date and time when user logged in or agent token has been generated | 2020-02-03T11:03:39.323310Z |
role | agent role. Possible roles: admin , manager and agent |
agent |
available | agent availability status (boolean: true or false ) |
true |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- free
boolean
(optional) Example: trueagents that are ready to take a call. Depends on
available
field value and online status. Takestrue
orfalse
.
Headers
Content-Type: application/json
Body
{
"username": "Peter Pan",
"agent_email": "peter@neverland.net",
"password": "Pass@123",
"role": "admin"
}
Headers
Content-Type: application/json
Body
{
"agent_id": "1"
}
Create a new agentPOST/agents/?api_key={API_KEY}
Create a new AGENT
cURL example:
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{
\"username\": \"Peter Pan\",
\"agent_email\": \"peter@neverland.net\",
\"password\": \"Pass@123\"
}" \
'https://surfly.com/v2/agents/?api_key=API_KEY'
Request Body:
Name | Description | Example |
---|---|---|
username | username of the agent | Peter Pan |
agent_email | email address of the agent | peter@neverland.net |
password | password | Pass@123 |
role | role of the agent, defaults to None which will create a regular agent. Other available roles: admin , manager . |
admin |
Response Body:
Name | Description | Example |
---|---|---|
agent_id | ID of the agent | 1 |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- free
boolean
(optional) Example: trueagents that are ready to take a call. Depends on
available
field value and online status. Takestrue
orfalse
.
Agent information ¶
Headers
Content-Type: application/json
Body
{
"agent_id": 2,
"agent_name": "John Doe",
"agent_email": "john.doe@example.com",
"last_login": "2020-02-03T11:03:39.323310Z",
"role": "agent",
"available": true
}
Get Agent InformationGET/agents/{AGENT_ID}/?api_key={API_KEY}
Get information about a certain AGENT by AGENT_ID
cURL example:
curl --include \
'https://surfly.com/v2/agents/AGENT_ID/?api_key=API_KEY'
Response Body:
Name | Description | Example |
---|---|---|
agent_id | ID of the agent | 2 |
agent_name | name of the agent | John Doe |
agent_email | email address of the agent | john.doe@example.com |
last_login | date and time when user logged in or agent token has been generated | 2020-02-03T11:03:39.323310Z |
role | agent role. Possible roles: admin , manager and agent |
agent |
available | agent availability status (boolean: true or false ) |
true |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- AGENT_ID
string
(required) Example: 2
Headers
Content-Type: application/json
Body
{
"username": "Peter",
"agent_email": "peter@neverland.com",
"available": true
}
Headers
Content-Type: application/json
Body
{
"agent_name": "Peter",
"agent_id": 2,
"agent_email": "peter@neverland.com",
"available": true
}
Update an agentPUT/agents/{AGENT_ID}/?api_key={API_KEY}
Update an AGENT by AGENT_ID
cURL example:
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary "{
\"username\": \"Peter\",
\"agent_email\": \"peter@neverland.com\"
}" \
'https://surfly.com/v2/agents/AGENT_ID/?api_key=API_KEY'
Request Body:
Name | Description | Example |
---|---|---|
username (optional) | username of the agent | Peter Pan |
agent_email (optional) | email address of the agent | peter@neverland.net |
available (optional) | agent availability status (boolean: true or false ) |
false |
Response Body:
Name | Description | Example |
---|---|---|
agent_name | name of the agent | Peter |
agent_id | ID of the agent | 2 |
agent_email | email address of the agent | peter@neverland.net |
available | agent availability status (boolean: true or false ) |
true |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- AGENT_ID
string
(required) Example: 2
Headers
Content-Type: application/json
Body
{
"response": "Agent has been removed successfully"
}
Delete an agentDELETE/agents/{AGENT_ID}/?api_key={API_KEY}
Remove an AGENT by AGENT_ID
cURL example:
curl --include \
--request DELETE \
'https://surfly.com/v2/agents/AGENT_ID/?api_key=API_KEY'
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- AGENT_ID
string
(required) Example: 2
Embed Access Tokens ¶
Headers
Content-Type: application/json
Body
{
"email": "agent@neverland.net",
"name": "Ethan Hunt",
"role": "agent"
}
Headers
Content-Type: application/json
Body
{
"user_created": true,
"agent_token": "t0aae2b2454c64b9a87b83ec09647dd9e",
"expires_in": 86400,
"agent_id": 1337,
"agent_role": "agent"
}
Headers
Content-Type: application/json
Body
{
"errors": {
"agent_id": [
"Agent was not found"
]
}
}
Generate an access tokenPOST/agents/access-token/?api_key={API_KEY}
Generate a temporary access token for a given agent.
Surfly generates a unique access token for the specified user and returns it in a response. The token expires automatically 24 hours after it is first created. Within that period, it can be used to construct Embed API links, but after that a new token has to be generated. Note that unless force_new
parameter is set, Surfly will try to return an existing token. If the existing token is due to expire in less than 5 minutes, the new token will be generated even if force_new
is set to false.
Note that 24 hours expiration time is mainly for performance optimization: the integrating app doesn’t have to generate a token on each page load. Instead, it can generate it (for example) when user logs in, and cache it for a day.
cURL example:
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{
\"email\": \"agent@neverland.net\",
\"name\": \"Ethan Hunt\",
\"role\": \"agent\"
}" \
'https://surfly.com/v2/agents/access-token/?api_key=API_KEY'
Request Body:
Name | Type | Description | Required or optional |
---|---|---|---|
agent_id | integer | ID of an existing agent, if it was created before | Optional |
string | agent email | Required when agent_id is not provided |
|
name | string | agent name | Required when agent_id is not provided |
role | string | user role. Ignored if the user already exists. If specified, must be one of “agent”, “manager”, or “admin”. By default, “agent” is assumed. | Optional |
force_new | boolean | Force generating a new token, even if the old one is not yet expired. Note that a user can only have one active access token at a time, previous token associated with the user will be invalidated | Optional |
Response Body:
Name | Type | Description |
---|---|---|
user_created | boolean | indicates whether a new user object was created |
agent_token | string | the generated access token |
expires_in | integer | seconds before the agent_token expires |
agent_id | integer | ID of the agent, useful when the call creates a new agent |
agent_role | string | agent role |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Sessions ¶
Sessions Collection ¶
Headers
Content-Type: application/json
Body
[
{
"id": "fvFkrL4saf52nuFh4GP9oQw",
"session_id": "fvFkrL4saf52nuFh4GP9oQw",
"formatted_id": "123-123-123",
"agent_id": null,
"follower_link": "https://surfly.com/123-123-123",
"cobro_server_name": "session.surfly.com",
"start_time": "2017-04-21T13:55:08.251918Z",
"duration": null,
"participant_num": 0,
"end_time": null,
"successful_start": null,
"queue_id": 0,
"pin": null,
"queued": false,
"waiting_time": null,
"start_url": "https://surfly.com.com/test/widget/?widget_key=3b57bd2db21c46d2875508b982968d26&autohide_button=false&hide_until_agent_joins=false",
"meta": "{}",
"tags": [],
"opentok_archive_id": null,
"options": {
"enable_sounds": true,
"videochat": true,
"allowlist": "[]",
"agent_can_end_session": false,
"auto_restore": true,
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"agent_can_request_control": false,
"widget_key": 0,
"cookie_transfer_proxying": false,
"store_chat_logs": false,
"allow_control_switching": true,
"start_muted": false,
"format_session_id": true,
"disable_end_redirect": false,
"agent_can_take_control": false,
"cookie_transfer_urls": [],
"splash": true,
"theme_font_size": 14,
"theme_font_color": "#FFFFFF",
"verbose_console": false,
"newurl": true,
"end_of_session_popup_url": "",
"start_docked": false,
"autohide_button": false,
"white_label": false,
"blocklist": "[]",
"position": "bottomleft",
"filesharing": true,
"hide_until_agent_joins": false,
"hidden": false,
"allow_original_file_download": false,
"docked_only": false,
"ui_off": false,
"sharing_button": true,
"auto_start": false,
"theme_font_background": "#cc0000",
"block_until_agent_joins": false,
"follower_redirect_url": "",
"only_embedded_sessions": false,
"stealth_mode": true,
"leader_redirect_url": ""
}
}
]
List all SessionsGET/sessions/?api_key={API_KEY}
List all sessions
cURL example:
curl --include \
'https://surfly.com/v2/sessions/?api_key=API_KEY'
Response Body:
A list of objects containing the following parameters:
Name | Description | Example |
---|---|---|
session_id | unique ID of the session | fOBg4dXAPTHSoil6LywgfYA |
formatted_id | unique formatted ID of the session | 123-456-789 |
agent_id | ID of the agent | 2 |
follower_link | the link that must be opened in a follower browser | https://surfly.com/123-456-789 |
start_time | time the session started | 2016-06-17T14:30:44.026111Z |
duration | length of the session (in seconds) | 123 |
participant_num | number of session participants | 3 |
end_time | time the session finished | 2016-06-17T15:30:44.026111Z |
successful_start | Whether the session was technically successful or not | true |
pin | 4-digit PIN code that can be used to join the session | 3927 |
queued | Whether the session has been put in a waiting queue | false |
waiting_time | time the session waited to start when it was in queue. will be null if it’s never been in queue |
00:00:56 |
start_url | page the session started from | https://example.com/ |
meta | additional data attached to joining user | {} |
tags | array of attached session tags | [“tag1”, “tag2”] |
options | options the session was created with | {“ui_off”: false, “block_until_agent_joins”: true} |
cobro_server_name | server name for multi-server installations | session12.surfly.com |
opentok_archive_id | Opentok archive ID | b40ef09b-3811-4726-b508-e41a0f96c68f |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Headers
Content-Type: application/json
Body
{
"url": "http://www.surfly.com/",
"tags": [
"tag1",
"tag2"
]
}
Headers
Content-Type: application/json
Body
{
"id": "fvFkrL4saf52nuFh4GP9oQw",
"session_id": "fvFkrL4saf52nuFh4GP9oQw",
"formatted_id": "123-123-123",
"agent_id": null,
"follower_link": "https://surfly.com/123-123-123",
"leader_link": "https://surfly.com/mUBRJyslQStVXPEwUwFyQ",
"cobro_server_name": "session.surfly.com",
"start_time": "2017-04-21T13:55:08.251918Z",
"duration": null,
"end_time": null,
"queue_id": 0,
"pin": null,
"queued": false,
"waiting_time": null,
"start_url": "https://example.com",
"meta": "{}",
"tags": [],
"options": {
"enable_sounds": true,
"videochat": true,
"allowlist": "[]",
"agent_can_end_session": false,
"auto_restore": true,
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"agent_can_request_control": false,
"widget_key": 0,
"cookie_transfer_proxying": false,
"store_chat_logs": false,
"allow_control_switching": true,
"start_muted": false,
"format_session_id": true,
"disable_end_redirect": false,
"agent_can_take_control": false,
"cookie_transfer_urls": [],
"splash": true,
"theme_font_size": 14,
"theme_font_color": "#FFFFFF",
"verbose_console": false,
"newurl": true,
"end_of_session_popup_url": "",
"start_docked": false,
"autohide_button": false,
"white_label": false,
"blocklist": "[]",
"position": "bottomleft",
"filesharing": true,
"hide_until_agent_joins": false,
"hidden": false,
"allow_original_file_download": false,
"docked_only": false,
"ui_off": false,
"sharing_button": true,
"auto_start": false,
"theme_font_background": "#cc0000",
"block_until_agent_joins": false,
"follower_redirect_url": "",
"only_embedded_sessions": false,
"stealth_mode": true,
"leader_redirect_url": ""
}
}
Create a sessionPOST/sessions/?api_key={API_KEY}
Create a new session
cURL example:
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{
\"url\": \"http://www.surfly.com/\",
\"tags\": [\"tag1\", \"tag2\"],
\"ui_off\": true
}" \
'https://surfly.com/v2/sessions/?api_key=API_KEY'
Request Body:
You can also pass any session option(s) in the request body. Note that ui_off
above is just an example.
Name | Description | Example |
---|---|---|
url | url to co-browse | http://www.google.com |
agent_id (optional) | ID of the agent | 2 |
tags (optional) | session tags | tag1, tag2 |
skip_queue (optional) | Prevents queueing the session when using a widget key (false by default) | false |
ui_off (optional) | Pass ANY option when creating the session (ui_off is an example) | true |
Response Body:
Response will contain a JSON object with the same fields as in list endpoint, and the following extra fields:
Name | Description | Example |
---|---|---|
leader_link | the link that must be opened in a leader (controlling) browser. It has a 2 minute time out attached to it, if not used within that time, the session will be closed. | https://surfly.com/mUBRJyslQStVXPEwUwFyQ |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Filtering Sessions Collection ¶
Headers
Content-Type: application/json
Body
[
{
"id": "fvFkrL4saf52nuFh4GP9oQw",
"session_id": "fvFkrL4saf52nuFh4GP9oQw",
"formatted_id": "123-123-123",
"agent_id": null,
"follower_link": "https://surfly.com/123-123-123",
"cobro_server_name": "session.surfly.com",
"start_time": "2017-04-21T13:55:08.251918Z",
"duration": null,
"participant_num": 0,
"end_time": null,
"successful_start": null,
"queue_id": 0,
"pin": null,
"queued": false,
"waiting_time": null,
"start_url": "https://example.com",
"meta": "{}",
"tags": [],
"opentok_archive_id": null,
"options": {
"enable_sounds": true,
"videochat": true,
"allowlist": "[]",
"agent_can_end_session": false,
"auto_restore": true,
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"agent_can_request_control": false,
"widget_key": 0,
"cookie_transfer_proxying": false,
"store_chat_logs": false,
"allow_control_switching": true,
"start_muted": false,
"format_session_id": true,
"disable_end_redirect": false,
"agent_can_take_control": false,
"cookie_transfer_urls": [],
"splash": true,
"theme_font_size": 14,
"theme_font_color": "#FFFFFF",
"verbose_console": false,
"newurl": true,
"end_of_session_popup_url": "",
"start_docked": false,
"autohide_button": false,
"white_label": false,
"blocklist": "[]",
"position": "bottomleft",
"filesharing": true,
"hide_until_agent_joins": false,
"hidden": false,
"allow_original_file_download": false,
"docked_only": false,
"ui_off": false,
"sharing_button": true,
"auto_start": false,
"theme_font_background": "#cc0000",
"block_until_agent_joins": false,
"follower_redirect_url": "",
"only_embedded_sessions": false,
"stealth_mode": true,
"leader_redirect_url": ""
}
}
]
Filter sessionsGET/sessions/?api_key={api_key}&active_session={active_session}&agent_id={agent_id}&year={year}&month={month}&pin={pin}&tags={tags}
For example, list all active sessions
cURL example:
curl 'https://surfly.com/v2/sessions/?api_key=API_KEY&active_session=true'
- api_key
string
(required) Example: 3b57bd2db21c46d2875508b982968d26REST API key of a company
- active_session
boolean
(optional) Example: trueFilter active or inactive sessions
- agent_id
number
(optional) Example: 1Filter by ID of the agent who joined/started a session
- year
number
(optional) Example: 2020Filter by year
- month
number
(optional) Example: 10Filter by month
- pin
number
(optional) Example: 1234Filter by PIN number (useful in combination with
active_session
)- tags
string
(optional) Example: tag1,tag2Filter by tag. Supports multiple comma separated tags at once
Session Information ¶
Headers
Content-Type: application/json
Body
{
"id": "fvFkrL4saf52nuFh4GP9oQw",
"session_id": "fvFkrL4saf52nuFh4GP9oQw",
"formatted_id": "123-123-123",
"agent_id": 1,
"follower_link": "https://surfly.com/123-123-123",
"cobro_server_name": "session.surfly.com",
"start_time": "2017-04-21T13:55:08.251918Z",
"duration": null,
"participant_num": 3,
"end_time": null,
"successful_start": null,
"queue_id": 0,
"pin": null,
"queued": false,
"waiting_time": null,
"start_url": "https://example.com",
"meta": "{}",
"tags": [],
"opentok_archive_id": null,
"options": {
"enable_sounds": true,
"videochat": true,
"allowlist": "[]",
"agent_can_end_session": false,
"auto_restore": true,
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"agent_can_request_control": false,
"widget_key": 0,
"cookie_transfer_proxying": false,
"store_chat_logs": false,
"allow_control_switching": true,
"start_muted": false,
"format_session_id": true,
"disable_end_redirect": false,
"agent_can_take_control": false,
"cookie_transfer_urls": [],
"splash": true,
"theme_font_size": 14,
"theme_font_color": "#FFFFFF",
"verbose_console": false,
"newurl": true,
"end_of_session_popup_url": "",
"start_docked": false,
"autohide_button": false,
"white_label": false,
"blocklist": "[]",
"position": "bottomleft",
"filesharing": true,
"hide_until_agent_joins": false,
"hidden": false,
"allow_original_file_download": false,
"docked_only": false,
"ui_off": false,
"sharing_button": true,
"auto_start": false,
"theme_font_background": "#cc0000",
"block_until_agent_joins": false,
"follower_redirect_url": "",
"only_embedded_sessions": false,
"stealth_mode": true,
"leader_redirect_url": ""
}
}
Get session informationGET/sessions/{ID}/?api_key={API_KEY}
Get information about a session by ID
. ID
can be a formatted ID (e.g. 123-123-123), or an unformatted ID (e.g. fuSHr0sRQ1usugvheahwQ)
cURL example:
curl --include \
'https://surfly.com/v2/sessions/ID/?api_key=API_KEY'
Response Body:
Name | Description | Example |
---|---|---|
session_id | unique ID of the session | fOBg4dXAPTHSoil6LywgfYA |
formatted_id | unique formatted ID of the session | 123-456-789 |
agent_id | ID of the agent | 2 |
follower_link | the link that must be opened in a follower browser | https://surfly.com/123-456-789 |
start_time | time the session started | 2016-06-17T14:30:44.026111Z |
duration | length of the session (in seconds) | 123 |
participant_num | number of session participants | 3 |
end_time | time the session finished | 2016-06-17T15:30:44.026111Z |
successful_start | Whether the session was technically successful or not | true |
pin | 4-digit PIN code that can be used to join the session | 3927 |
queued | Whether the session has been put in a waiting queue | false |
waiting_time | time the session waited to start when it was in queue. will be null if it’s never been in queue |
00:00:56 |
start_url | page the session started from | https://example.com/ |
meta | additional data attached to joining user | {} |
tags | array of attached session tags | [“tag1”, “tag2”] |
options | options the session was created with | {“ui_off”: false, “block_until_agent_joins”: true} |
cobro_server_name | server name for multi-server installations | session12.surfly.com |
opentok_archive_id | Opentok archive ID | b40ef09b-3811-4726-b508-e41a0f96c68f |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- ID
string
(required) Example: fuSHr0sRQ1usugvheahwQ
End session ¶
Headers
Content-Type: application/json
Body
{
"id": "fvFkrL4saf52nuFh4GP9oQw",
"session_id": "fvFkrL4saf52nuFh4GP9oQw",
"formatted_id": "123-123-123",
"agent_id": 1,
"follower_link": "https://surfly.com/123-123-123",
"cobro_server_name": "session.surfly.com",
"start_time": "2017-04-21T13:55:08.251918Z",
"duration": 10,
"participant_num": 3,
"end_time": "2017-04-21T13:55:18.251918Z",
"successful_start": false,
"queue_id": 0,
"pin": null,
"queued": false,
"waiting_time": null,
"start_url": "https://example.com",
"meta": "{}",
"tags": [],
"opentok_archive_id": null,
"options": {
"enable_sounds": true,
"videochat": true,
"allowlist": "[]",
"agent_can_end_session": false,
"auto_restore": true,
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"agent_can_request_control": false,
"widget_key": 0,
"cookie_transfer_proxying": false,
"store_chat_logs": false,
"allow_control_switching": true,
"start_muted": false,
"enable_native_dialogs": 0,
"format_session_id": true,
"disable_end_redirect": false,
"agent_can_take_control": false,
"cookie_transfer_urls": [],
"splash": true,
"theme_font_size": 14,
"theme_font_color": "#FFFFFF",
"verbose_console": false,
"newurl": true,
"end_of_session_popup_url": "",
"start_docked": false,
"autohide_button": false,
"white_label": false,
"blocklist": "[]",
"position": "bottomleft",
"filesharing": true,
"hide_until_agent_joins": false,
"hidden": false,
"allow_original_file_download": false,
"docked_only": false,
"ui_off": false,
"sharing_button": true,
"auto_start": false,
"confirm_session_start": 0,
"theme_font_background": "#cc0000",
"block_until_agent_joins": false,
"follower_redirect_url": "",
"only_embedded_sessions": false,
"stealth_mode": true,
"leader_redirect_url": ""
}
}
End sessionPOST/sessions/{ID}/end/?api_key={API_KEY}
End session
cURL example:
curl --data '' --include \
'https://surfly.com/v2/sessions/ID/end/?api_key=API_KEY'
Response Body:
Name | Description | Example |
---|---|---|
session_id | unique ID of the session | fOBg4dXAPTHSoil6LywgfYA |
formatted_id | unique formatted ID of the session | 123-456-789 |
agent_id | ID of the agent | 2 |
follower_link | the link that must be opened in a follower browser | https://surfly.com/123-456-789 |
start_time | time the session started | 2016-06-17T14:30:44.026111Z |
duration | length of the session (in seconds) | 123 |
participant_num | number of session participants | 3 |
end_time | time the session finished | 2016-06-17T15:30:44.026111Z |
successful_start | Whether the session was technically successful or not | true |
pin | 4-digit PIN code that can be used to join the session | 3927 |
queued | Whether the session has been put in a waiting queue | false |
waiting_time | time the session waited to start when it was in queue. will be null if it’s never been in queue |
00:00:56 |
start_url | page the session started from | https://example.com/ |
meta | additional data attached to joining user | {} |
tags | array of attached session tags | [“tag1”, “tag2”] |
options | options the session was created with | {“ui_off”: false, “block_until_agent_joins”: true} |
cobro_server_name | server name for multi-server installations | session12.surfly.com |
opentok_archive_id | Opentok archive ID | b40ef09b-3811-4726-b508-e41a0f96c68f |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- ID
string
(required) Example: fuSHr0sRQ1usugvheahwQ
Company ¶
Headers
Content-Type: application/json
Body
{
"enable_sounds": true,
"videochat": true,
"allowlist": "[]"
}
Retrieve default optionsGET/company/options/?api_key={api_key}
Returns an object with default session options. Plan limitations are taken into account
Also available with the widget key
cURL example:
curl 'https://surfly.com/v2/company/options/?api_key=API_KEY'
- api_key
string
(required) Example: 3b57bd2db21c46d2875508b982968d26REST API key of a company
Headers
Content-Type: application/json
Body
{
"enable_sounds": true,
"videochat": true,
"allowlist": "[]"
}
Set default optionsPOST/company/options/?api_key={api_key}
Sets new default options. If any option is missing in the request body, its value is reset to default. If you need to update only certain options and leave the other intact, consider the PATCH
method instead.
cURL example:
curl -X POST -d '{"start_docked": true}' 'https://surfly.com/v2/company/options/?api_key=API_KEY'
- api_key
string
(required) Example: 3b57bd2db21c46d2875508b982968d26REST API key of a company
Headers
Content-Type: application/json
Body
{
"enable_sounds": true,
"videochat": true,
"allowlist": "[]"
}
Update default optionsPATCH/company/options/?api_key={api_key}
Updates values of options specified in the request body. Other options are left intact
curl -X PATCH --header "Content-Type: application/json" -d '{"start_docked": true}' 'https://surfly.com/v2/company/options/?api_key=API_KEY'
- api_key
string
(required) Example: 3b57bd2db21c46d2875508b982968d26REST API key of a company
Reset default optionsDELETE/company/options/?api_key={api_key}
Resets all session options to their default values
cURL example:
curl -X DELETE 'https://surfly.com/v2/company/options/?api_key=API_KEY'
- api_key
string
(required) Example: 3b57bd2db21c46d2875508b982968d26REST API key of a company
Screenshots ¶
Latest Screenshot ¶
Headers
Content-Type: application/json
Body
{
"url": "http://surfly-screenshots.s3.amazonaws.com/screenshot-ID.webp"
}
Latest ScreenshotGET/sessions/{ID}/screenshots/latest/?api_key={API_KEY}
Get latest screenshot for session by its ID
.
cURL example:
curl --include \
'https://surfly.com/v2/sessions/ID/screenshots/latest/?api_key=API_KEY'
Response body
Name | Description | Example |
---|---|---|
url | address of the latest image | http://surfly-screenshots.s3.amazonaws.com/screenshot-ID.webp |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- ID
string
(required) Example: fuSHr0sRQ1usugvheahwQ
Create Screenshot ¶
Headers
Content-Type: application/json
Body
{
"size": 1024,
"interval": 30
}
Headers
Content-Type: text/plain
Body
"GENERATION-STARTED"
Create ScreenshotPOST/sessions/{ID}/screenshots/create/?api_key={API_KEY}
Start generation of screenshots. The screenshots will be created as long as you keep getting the latest screenshots using the get latest screenshot API, that is to stop the creation of screenshot you just have to stop requesting the latest screenshot. There will be a new screenshot after a set interval second. The interval will be adjusted if the given value is lower than 5 secs. The max size of the screenshot will be adjusted in case the requested size is more than the window size.
cURL example:
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{
\"size\": 1920,
\"interval\": 30
}" \
'https://surfly.com/v2/sessions/ID/screenshots/create/?api_key=API_KEY'
Request Body:
Name | Description | Example |
---|---|---|
size | width of the screenshot | 1920 |
interval | rate in second, at which screenshot will be generated | 60 |
Response Body:
MESSAGE | Description |
---|---|
GENERATION-STARTED | screenshot generation process started |
ALREADY-RUNNING | screenshot generation process already running |
FAILED-INTERNALLY | screenshot generation process failed internally |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- ID
string
(required) Example: fEapBPiwxSouiLcAgb2OXQ1
Clients ¶
(2018-03-19)
RESELLER_KEY
is deprecated. In order to make old API calls compatible, we replaced the placeholder with the keywordall
Clients Collection ¶
Headers
Content-Type: application/json
Body
[
{
"company_name": "Neverland",
"company_plan_name": "pro",
"client_key": "AOEUaoeuntsPDe",
"agent_count": 15,
"widget_key": "24d1414c71a94cbf9f205ed4fc4999b5",
"rest_key": "3b57bd2db21c46d2875508b982968d26",
"domains": "example.com, *.example.com"
},
{
"company_name": "DefaultCompany",
"company_plan_name": "free",
"client_key": "b05b45b8d4df42ba96",
"agent_count": 2,
"widget_key": "c6a1333308a843cc9fb6aee2e42941d6",
"rest_key": "767dd31a038c4ee798c72abb4b568ade",
"domains": "*"
}
]
Lists all your clientsGET/clients/all/?api_key={API_KEY}
Return all clients of a reseller account
cURL example:
curl --include \
'https://surfly.com/v2/clients/all/?api_key=API_KEY'
Response Body:
A list of objects containing the following parameters:
Name | Description | Example |
---|---|---|
company_name | name of company | Neverland |
company_plan_name | name of the company’s plan | pro |
client_key | client key | AOEUaoeuntsPDe |
agent_count | maximum number of agents | 15 |
widget_key | widget key | 24d1414c71a94cbf9f205ed4fc4999b5 |
rest_key | REST API key | 3b57bd2db21c46d2875508b982968d26 |
domains | comma-separated list of domains | example.com, *.example.com |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Headers
Content-Type: application/json
Body
{
"company_name": "Neverland",
"domains": "*",
"agent_email": "peter@mail.com",
"agent_name": "Peter Pan"
}
Headers
Content-Type: application/json
Body
{
"company_name": "Neverland",
"client_key": "fOBg4dXAPTHSoil6LywgfYA",
"rest_key": "22c0f77e5ca54d8fa6748f7cec4732c5",
"widget_key": "92cdd920f4e345768f6717b02f15dae8"
}
Create a new clientPOST/clients/all/?api_key={API_KEY}
Add a new client
cURL example:
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{
\"company_name\": \"Neverland\",
\"domains\": \"*\",
\"agent_email\": \"peter@mail.com\",
\"agent_name\": \"Peter Pan\"
}" \
'https://surfly.com/v2/clients/all/?api_key=API_KEY'
Request Body:
Name | Description | Example |
---|---|---|
company_name | name of new company | Neverland |
domains (optional) | comma-separated list of domains | * |
agent_email (optional) | email of a company admin | peter@mail.com |
agent_name (optional) | name of a company admin | Peter Pan |
agent_password (optional) | password for an agent account | Password123! |
Response Body:
Name | Description | Example |
---|---|---|
company_name | name of company | Neverland |
client_key | client key | fOBg4dXAPTHSoil6LywgfYA |
rest_key | REST API key | 22c0f77e5ca54d8fa6748f7cec4732c5 |
widget_key | widget key | 92cdd920f4e345768f6717b02f15dae8 |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Client Information ¶
Headers
Content-Type: application/json
Body
{
"company_name": "Neverland",
"company_plan_name": "pro",
"client_key": "AOEUaoeuntsPDe",
"agent_count": 15,
"widget_key": "24d1414c71a94cbf9f205ed4fc4999b5",
"rest_key": "3b57bd2db21c46d2875508b982968d26",
"domains": "example.com, *.example.com"
}
Get Client InformationGET/clients/all/{CLIENT_KEY}/?api_key={API_KEY}
Get information about a specific client by CLIENT_KEY
cURL example:
curl --include \
'https://surfly.com/v2/clients/all/CLIENT_KEY/?api_key=API_KEY'
Response Body:
Name | Description | Example |
---|---|---|
company_name | name of company | Neverland |
company_plan_name | name of the company’s plan | pro |
client_key | client key | AOEUaoeuntsPDe |
agent_count | maximum number of agents | 15 |
widget_key | widget key | 24d1414c71a94cbf9f205ed4fc4999b5 |
rest_key | REST API key | 3b57bd2db21c46d2875508b982968d26 |
domains | comma-separated list of domains | example.com, *.example.com |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- CLIENT_KEY
string
(required) Example: 63668234b4aa19dd436e6a76ab8ae000
Headers
Content-Type: application/json
Body
{
"domains": "example.com, *.example.com"
}
Headers
Content-Type: application/json
Body
{
"domains": "example.com, *.example.com"
}
Set Client Domain ListPOST/clients/all/{CLIENT_KEY}/?api_key={API_KEY}
cURL example:
curl --include \
'https://surfly.com/v2/clients/all/CLIENT_KEY/?api_key=API_KEY'
Request Body:
Name | Description | Example |
---|---|---|
domains | comma-separated list of domains | example.com, *.example.com |
Response Body:
Name | Description | Example |
---|---|---|
domains | comma-separated list of domains | example.com, *.example.com |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- CLIENT_KEY
string
(required) Example: 63668234b4aa19dd436e6a76ab8ae000
Headers
Content-Type: application/json
Body
{
"company_name": "Peter Pan"
}
Headers
Content-Type: application/json
Body
{
"agent_count": 15,
"company_name": "Peter Pan",
"client_key": "AOEUaoeuntsPDe"
}
Update a clientPUT/clients/all/{CLIENT_KEY}/?api_key={API_KEY}
Update a client
cURL example:
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary "{
\"company_name\": \"Peter Pan\"
}" \
'https://surfly.com/v2/clients/all/CLIENT_KEY/?api_key=API_KEY'
Request Body:
Name | Description | Example |
---|---|---|
company_name | new name of company | Peter Pan |
Response Body:
Name | Description | Example |
---|---|---|
agent_count | maximum number of agents | 15 |
company_name | name of company | Peter Pan |
client_key | client key | AOEUaoeuntsPDe |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- CLIENT_KEY
string
(required) Example: 63668234b4aa19dd436e6a76ab8ae000
Headers
Content-Type: application/json
Body
{
"response": "Client has been removed Successfully"
}
Delete a ClientDELETE/clients/all/{CLIENT_KEY}/?api_key={API_KEY}
cURL example:
curl --include \
--request DELETE \
'https://surfly.com/v2/clients/all/CLIENT_KEY/?api_key=API_KEY'
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- CLIENT_KEY
string
(required) Example: 63668234b4aa19dd436e6a76ab8ae000
Reseller Sessions Collection ¶
Headers
Content-Type: application/json
Body
[
{
"session_id": "fOBg4dXAPTHSoil6LywgfYA",
"agent_id": 2,
"follower_link": "https://session.surfly.com/fwqcOuuMwTty7ii3kcA8Q",
"start_time": "2016-08-11T13:44:58.025358Z",
"duration": 123
}
]
List Active Sessions for Reseller's ClientGET/sessions/?api_key={API_KEY}&clientkey={CLIENT_KEY}&active_session=true&year=2015&month=01
List all ACTIVE sessions for a certain CLIENT
, year
, month
active_session
, year
and month
are optional
cURL example:
curl --include \
'https://surfly.com/v2/sessions/?api_key=API_KEY&clientkey=CLIENT_KEY&active_session=true&year=2015&month=01'
Response Body:
A list of objects containing the following parameters:
Name | Description | Example |
---|---|---|
session_id | unique ID of the session | fOBg4dXAPTHSoil6LywgfYA |
agent_id | ID of the agent | 2 |
follower_link | the link that must be opened in a viewer browser | https://session.surfly.com/fHrD6TMmRrurMevgidxyw |
start_time | time the session started | 2016-08-11T13:44:58.025358Z |
duration | length of the session (in seconds) | 123 |
- CLIENT_KEY
string
(required) Example: 00063668234b4aa19dd436e6a76ab8ae- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Servers ¶
Servers Collection ¶
Headers
Content-Type: application/json
Body
[
{
"id": "10",
"region": "eu",
"description": "Germany, Nuremberg"
}
]
List all serversGET/servers/
Return a list of available servers
cURL example:
curl --include \
'https://surfly.com/v2/servers/'
Response body
A list of objects containing the following parameters:
Name | Description | Example |
---|---|---|
id | Server’s ID | “10” |
region | Server’s location | “eu” |
description | Description | “Germany, Nuremberg” |
ips | List of IP addresses which are assigned to the server | “1.1.1.1, 2.2.2.2” |
History ¶
History View ¶
Headers
Content-Type: application/json
Body
{
"next": null,
"previous": null,
"results": [
{
"id": "fvFkrL4saf52nuFh4GP9oQw",
"session_id": "fvFkrL4saf52nuFh4GP9oQw",
"formatted_id": "123-123-123",
"cobro_server_name": "session.sitesupport.net",
"agent_id": null,
"follower_link": "https://sitesupport.net/fvFkrL4saf52nuFh4GP9oQw",
"start_time": "2020-05-06T06:58:15.957711Z",
"duration": null,
"end_time": null,
"successful_start": null,
"queue_id": 0,
"pin": null,
"queued": false,
"start_url": "http://www.surfly.com/",
"meta": "{}",
"tags": [
"tag1",
"tag2"
],
"participant_num": 0,
"options": {
"enable_sounds": true,
"store_session_logs": false,
"videochat": true,
"share_downloads": true,
"stealth_mode": true,
"orphan_redirect_url": "",
"follower_drawing_selector": "",
"hide_selector": "",
"auto_restore": true,
"s3_log_bucket": "",
"branding_primary_color": "#e54747",
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"allow_pause": false,
"agent_can_request_control": false,
"branding_primary_fg_color": "#ffffff",
"show_loading_screen": true,
"show_cursors": true,
"store_chat_logs": false,
"hide_until_agent_joins": false,
"allow_control_switching": true,
"start_muted": false,
"format_session_id": false,
"require_password": false,
"soft_end_filter": [],
"proxy_only": false,
"agent_can_take_control": false,
"cookie_transfer_urls": [],
"splash": false,
"theme_font_size": 14,
"shake_to_start": false,
"chat_integration": "disabled",
"hidden": false,
"cookie_transfer_proxying": false,
"verbose_console": false,
"newurl": true,
"disable_end_redirect": false,
"end_of_session_popup_url": "",
"start_docked": true,
"widget_key": "",
"white_label": false,
"blocklist": "[]",
"allowlist": "[]",
"branding_secondary_fg_color": "#ffffff",
"agent_can_end_session": false,
"block_until_agent_joins": true,
"native_selects": true,
"filesharing": true,
"autohide_button": false,
"soft_session_end": false,
"auto_start": false,
"allow_original_file_download": false,
"docked_only": false,
"language": "en",
"confirm_session_start": false,
"branding_secondary_color": "#6e2222",
"theme_font_background": "#cc0000",
"ui_off": false,
"url_mangling": false,
"theme_font_color": "#FFFFFF",
"enable_native_dialogs": false,
"sharing_button": true,
"leader_redirect_url": "",
"private_session": false,
"videochat_autostart": false,
"position": "bottomleft",
"follower_redirect_url": "",
"only_embedded_sessions": false,
"region": "",
"selected_regions": []
}
},
{
"id": "fuSHr0sRQ1usugvheahwQ",
"session_id": "fuSHr0sRQ1usugvheahwQ",
"formatted_id": "266-974-529",
"cobro_server_name": "session.sitesupport174.net",
"agent_id": null,
"follower_link": "https://sitesupport174.net/fuSHr0sRQ1usugvheahwQ",
"start_time": "2020-05-06T06:58:14.234421Z",
"duration": 648,
"end_time": null,
"successful_start": false,
"queue_id": 1579,
"pin": "1579",
"queued": false,
"start_url": "http://www.glover.org/",
"meta": "{}",
"tags": [],
"participant_num": 0,
"options": {
"enable_sounds": true,
"store_session_logs": false,
"require_password": false,
"videochat": true,
"share_downloads": true,
"allowlist": "[]",
"orphan_redirect_url": "",
"position": "bottomleft",
"follower_drawing_selector": "",
"hide_selector": "",
"auto_restore": true,
"s3_log_bucket": "",
"branding_primary_color": "#e54747",
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"allow_pause": false,
"agent_can_request_control": false,
"widget_key": "",
"branding_primary_fg_color": "#ffffff",
"show_loading_screen": true,
"show_cursors": true,
"store_chat_logs": false,
"allow_control_switching": true,
"branding_logo_url": "",
"start_muted": false,
"format_session_id": false,
"private_session": false,
"soft_end_filter": [],
"proxy_only": false,
"agent_can_take_control": false,
"splash": false,
"theme_font_size": 14,
"branding_logo_link": "",
"chat_integration": "disabled",
"hidden": false,
"cookie_transfer_proxying": false,
"theme_font_color": "#FFFFFF",
"verbose_console": false,
"end_of_session_popup_url": "",
"newurl": true,
"disable_end_redirect": false,
"cookie_transfer_urls": [],
"start_docked": true,
"autohide_button": false,
"agent_can_end_session": false,
"white_label": false,
"blocklist": "[]",
"branding_secondary_fg_color": "#ffffff",
"dashboard_background_url": "",
"filesharing": true,
"hide_until_agent_joins": false,
"soft_session_end": false,
"auto_start": false,
"allow_original_file_download": false,
"docked_only": false,
"language": "en",
"confirm_session_start": false,
"branding_secondary_color": "#6e2222",
"theme_font_background": "#cc0000",
"ui_off": false,
"url_mangling": false,
"shake_to_start": false,
"enable_native_dialogs": false,
"sharing_button": true,
"videochat_autostart": false,
"region": "",
"selected_regions": [],
"block_until_agent_joins": true,
"follower_redirect_url": "",
"only_embedded_sessions": false,
"stealth_mode": true,
"native_selects": true,
"leader_redirect_url": ""
}
},
{
"id": "fEapBPiwxSouiLcAgb2OXQ",
"session_id": "fEapBPiwxSouiLcAgb2OXQ",
"formatted_id": "596-185-458",
"cobro_server_name": "session.sitesupport174.net",
"agent_id": 3,
"follower_link": "https://sitesupport174.net/fEapBPiwxSouiLcAgb2OXQ",
"start_time": "2020-05-06T06:58:14.135584Z",
"duration": null,
"end_time": null,
"successful_start": null,
"queue_id": 0,
"pin": null,
"queued": false,
"start_url": "http://wolffweissnat.net/",
"meta": "{}",
"tags": [],
"participant_num": 0,
"options": {
"enable_sounds": true,
"store_session_logs": false,
"require_password": false,
"videochat": true,
"share_downloads": true,
"allowlist": "[]",
"orphan_redirect_url": "",
"position": "bottomleft",
"follower_drawing_selector": "",
"hide_selector": "",
"auto_restore": true,
"s3_log_bucket": "",
"branding_primary_color": "#e54747",
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"allow_pause": false,
"agent_can_request_control": false,
"widget_key": "",
"branding_primary_fg_color": "#ffffff",
"show_loading_screen": true,
"show_cursors": true,
"store_chat_logs": false,
"allow_control_switching": true,
"branding_logo_url": "",
"start_muted": false,
"format_session_id": false,
"private_session": false,
"soft_end_filter": [],
"proxy_only": false,
"agent_can_take_control": false,
"splash": false,
"theme_font_size": 14,
"branding_logo_link": "",
"chat_integration": "disabled",
"hidden": false,
"cookie_transfer_proxying": false,
"theme_font_color": "#FFFFFF",
"verbose_console": false,
"end_of_session_popup_url": "",
"newurl": true,
"disable_end_redirect": false,
"cookie_transfer_urls": [],
"start_docked": true,
"autohide_button": false,
"agent_can_end_session": false,
"white_label": false,
"blocklist": "[]",
"branding_secondary_fg_color": "#ffffff",
"dashboard_background_url": "",
"filesharing": true,
"hide_until_agent_joins": false,
"soft_session_end": false,
"auto_start": false,
"allow_original_file_download": false,
"docked_only": false,
"language": "en",
"confirm_session_start": false,
"branding_secondary_color": "#6e2222",
"theme_font_background": "#cc0000",
"ui_off": false,
"url_mangling": false,
"shake_to_start": false,
"enable_native_dialogs": false,
"sharing_button": true,
"videochat_autostart": false,
"region": "",
"selected_regions": [],
"block_until_agent_joins": true,
"follower_redirect_url": "",
"only_embedded_sessions": false,
"stealth_mode": true,
"native_selects": true,
"leader_redirect_url": ""
}
}
]
}
List session historyGET/history/?api_key={API_KEY}
List history of all sessions
cURL example:
curl --include \
'https://surfly.com/v2/history/?api_key=API_KEY'
Response Body:
An object containing the following parameters:
Name | Description | Example |
---|---|---|
next | link to the next page | https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&page=3 |
previous | link to the previous page | https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&page=1 |
results | a list of objects |
Results:
Parameter results
is a list of objects containing the following parameters:
Name | Description | Example |
---|---|---|
session_id | unique ID of the session | fOBg4dXAPTHSoil6LywgfYA |
formatted_id | unique formatted ID of the session | 123-456-789 |
agent_id | ID of the agent | 2 |
follower_link | the link that must be opened in a follower browser | https://surfly.com/123-456-789 |
start_time | time the session started | 2016-06-17T14:30:44.026111Z |
duration | length of the session (in seconds) | 123 |
participant_num | number of session participants | 3 |
end_time | time the session finished | 2016-06-17T15:30:44.026111Z |
successful_start | Whether the session was technically successful or not | true |
pin | 4-digit PIN code that can be used to join the session | 3927 |
queued | Whether the session has been put in a waiting queue | false |
start_url | page the session started from | https://example.com/ |
meta | additional data attached to joining user | {} |
tags | array of attached session tags | [“tag1”, “tag2”] |
options | options the session was created with | {“ui_off”: false, “block_until_agent_joins”: true} |
cobro_server_name | server name for multi-server installations | session12.surfly.com |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Filtering History ¶
Headers
Content-Type: application/json
Body
{
"next": null,
"previous": null,
"results": [
{
"id": "fuSHr0sRQ1usugvheahwQ",
"session_id": "fuSHr0sRQ1usugvheahwQ",
"formatted_id": "737-464-923",
"cobro_server_name": "session.sitesupport.net",
"agent_id": null,
"follower_link": "https://sitesupport.net/fuSHr0sRQ1usugvheahwQ",
"start_time": "2020-05-06T10:42:44.940708Z",
"duration": 120,
"end_time": null,
"successful_start": false,
"queue_id": 8359,
"pin": "8359",
"queued": false,
"start_url": "http://www.surfly.com/",
"meta": "{}",
"tags": [
"tag1"
],
"participant_num": 0,
"options": {
"enable_sounds": true,
"store_session_logs": false,
"require_password": false,
"videochat": true,
"share_downloads": true,
"allowlist": "[]",
"orphan_redirect_url": "",
"position": "bottomleft",
"follower_drawing_selector": "",
"hide_selector": "",
"auto_restore": true,
"s3_log_bucket": "",
"branding_primary_color": "#e54747",
"cookie_transfer_enabled": true,
"cookie_transfer_scopes": [],
"allow_pause": false,
"agent_can_request_control": false,
"widget_key": "",
"branding_primary_fg_color": "#ffffff",
"show_loading_screen": true,
"show_cursors": true,
"store_chat_logs": false,
"allow_control_switching": true,
"branding_logo_url": "",
"start_muted": false,
"format_session_id": false,
"private_session": false,
"soft_end_filter": [],
"proxy_only": false,
"agent_can_take_control": false,
"splash": false,
"theme_font_size": 14,
"branding_logo_link": "",
"chat_integration": "disabled",
"hidden": false,
"cookie_transfer_proxying": false,
"theme_font_color": "#FFFFFF",
"verbose_console": false,
"end_of_session_popup_url": "",
"newurl": true,
"disable_end_redirect": false,
"cookie_transfer_urls": [],
"start_docked": true,
"autohide_button": false,
"agent_can_end_session": false,
"white_label": false,
"blocklist": "[]",
"branding_secondary_fg_color": "#ffffff",
"dashboard_background_url": "",
"filesharing": true,
"hide_until_agent_joins": false,
"soft_session_end": false,
"auto_start": false,
"allow_original_file_download": false,
"docked_only": false,
"language": "en",
"confirm_session_start": false,
"branding_secondary_color": "#6e2222",
"theme_font_background": "#cc0000",
"ui_off": false,
"url_mangling": false,
"shake_to_start": false,
"enable_native_dialogs": false,
"sharing_button": true,
"videochat_autostart": false,
"region": "",
"selected_regions": [],
"block_until_agent_joins": true,
"follower_redirect_url": "",
"only_embedded_sessions": false,
"stealth_mode": true,
"native_selects": true,
"leader_redirect_url": ""
}
}
]
}
Filter session historyGET/history/?api_key={api_key}&active_session={active_session}&agent_id={agent_id}&pin={pin}&tags={tags}&min_duration={min_duration}&max_duration={max_duration}&min_date={min_date}&max_date={max_date}
Results:
All filters are stackable like this:
https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&&tags=tag1&tags=null
When filtering by pin, you might want to filter on active sessions by adding &active_session=true
.
Pins are generated to be unique for active sessions, so in case you are looking for a running session via pin, please use active_session
filter as well:
https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&pin=1234&active_session=true
Range of min_date and max_date is [min, max)
. So to get results from 2020-04-21:
https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&min_date=2020-04-21T12:30-02:00&max_date=2020-04-22T12:30-02:00
cURL example:
curl --include \
'https://surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&tags=tag1'
- api_key
string
(required) Example: 3b57bd2db21c46d2875508b982968d26REST API key of a company
- active_session
boolean
(optional) Example: falseFilter active or inactive sessions. Takes
true
orfalse
.- agent_id
string
(optional) Example: nullFilter by ID of the agent who joined/started a session. Can take
null
as a value.- pin
string
(optional) Example: 1234Filter by session pin. Can take
null
as a value.- tags
string
(optional) Example: tag1Filter by session tag. Can take
null
as a value.- min_duration
number
(optional) Example: 120Filter by minimum duration of a session.
- max_duration
number
(optional) Example: 120Filter by maximum duration of a session.
- min_date
string
(optional) Example: 2020-05-06T00:00:00.000000ZFilter by earlist start date/time. Accepts a timestamp in iso8601 format. Make sure to take the timezone into account
- max_date
string
(optional) Example: 2020-05-06T00:00:00.000000ZFilter by latest start date/time. Accepts a timestamp in iso8601 format. Make sure to take the timezone into account
Webhooks ¶
Webhooks Collection ¶
Headers
Content-Type: application/json
Body
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": 538,
"url": "https://dev.mycompany.com/webhooks/",
"category": "session.started",
"enabled": true,
"ssl_verification": true,
"company_id": 94906
},
{
"id": 537,
"url": "https://mycompany.com/webhooks/",
"category": "session.started",
"enabled": true,
"ssl_verification": true,
"company_id": 94906
}
]
}
List all WebhooksGET/webhooks/?api_key={API_KEY}
List all Webhooks
cURL example:
curl --include \
'https://surfly.com/v2/webhooks/?api_key=API_KEY'
Response Body:
An object containing the following parameters:
Name | Description | Example |
---|---|---|
count | the total number of objects, across all pages | |
next | link to the next page | https://app.surfly.com/v2/webhooks/?api_key=3b57bd2db21c46d2875508b982968d26&page=3 |
previous | link to the previous page | https://app.surfly.com/v2/webhooks/?api_key=3b57bd2db21c46d2875508b982968d26&page=1 |
results | a list of objects |
Results:
Parameter results
is a list of objects containing the following parameters:
Name | Description | Example |
---|---|---|
id | webhook ID | 538 |
url | webhook url | https://dev.mycompany.com/webhooks/ |
category | webhook category | session.started |
enabled | whether the webhook is enabled or nor | true |
ssl_verification | whether to verify the server’s TLS certificate or not | true |
company_id | company ID | 94906 |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Headers
Content-Type: application/json
Body
{
"url": "https://mycompany.com/webhooks/",
"category": "session.started",
"enabled": true,
"ssl_verification": true
}
Headers
Content-Type: application/json
Body
{
"id": 539,
"url": "https://mycompany.com/webhooks/",
"category": "session.started",
"enabled": true,
"ssl_verification": true,
"company_id": 94906
}
Create a WebhookPOST/webhooks/?api_key={API_KEY}
Create an Webhook
cURL example:
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{
\"url\": \"https://mycompany.com/webhooks/\",
\"category\": \"session.started\",
\"enabled\": true,
\"ssl_verification\": true
}" \
'https://surfly.com/v2/webhooks/?api_key=API_KEY'
Request Body:
Name | Description | Example |
---|---|---|
url | webhook url | https://mycompany.com/webhooks/ |
category | webhook category | session.started |
enabled | whether the webhook is enabled or nor | true |
ssl_verification | whether to verify the server’s TLS certificate or not | true |
Response Body:
Name | Description | Example |
---|---|---|
id | webhook ID | 538 |
url | webhook url | https://mycompany.com/webhooks/ |
category | webhook category | session.started |
enabled | whether the webhook is enabled or nor | true |
ssl_verification | whether to verify the server’s TLS certificate or not | true |
company_id | company ID | 94906 |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26
Webhook Information ¶
Headers
Content-Type: application/json
Body
{
"id": 539,
"url": "https://mycompany.com/webhooks/",
"category": "session.started",
"enabled": true,
"ssl_verification": true,
"company_id": 94906
}
Get Webhook InformationGET/webhooks/{WEBHOOK_ID}/?api_key={API_KEY}
Get Webhook Information
cURL example:
curl --include \
'https://surfly.com/v2/webhooks/WEBHOOK_ID/?api_key=API_KEY'
Response Body:
Name | Description | Example |
---|---|---|
id | webhook ID | 538 |
url | webhook url | https://mycompany.com/webhooks/ |
category | webhook category | session.started |
enabled | whether the webhook is enabled or nor | true |
ssl_verification | whether to verify the server’s TLS certificate or not | true |
company_id | company ID | 94906 |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- WEBHOOK_ID
string
(required) Example: 1
Headers
Content-Type: application/json
Body
{
"url": "https://mycompany.com/webhooks/",
"category": "session.started",
"enabled": true,
"ssl_verification": true
}
Headers
Content-Type: application/json
Body
{
"id": 539,
"url": "https://mycompany.com/webhooks/",
"category": "session.started",
"enabled": true,
"ssl_verification": true,
"company_id": 94906
}
Update an WebhookPUT/webhooks/{WEBHOOK_ID}/?api_key={API_KEY}
Update an Webhook
cURL example:
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary "{
\"url\": \"https://mycompany.com/webhooks/\",
\"category\": \"session.started\",
\"enabled\": false,
\"ssl_verification\": true
}" \
'https://surfly.com/v2/webhooks/WEBHOOK_ID/?api_key=API_KEY'
Request Body:
Name | Description | Example |
---|---|---|
url | webhook url | https://mycompany.com/webhooks/ |
category | webhook category | session.started |
enabled | whether the webhook is enabled or nor | true |
ssl_verification | whether to verify the server’s TLS certificate or not | true |
Response Body:
Name | Description | Example |
---|---|---|
id | webhook ID | 538 |
url | webhook url | https://mycompany.com/webhooks/ |
category | webhook category | session.started |
enabled | whether the webhook is enabled or nor | true |
ssl_verification | whether to verify the server’s TLS certificate or not | true |
company_id | company ID | 94906 |
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- WEBHOOK_ID
string
(required) Example: 1
Delete an WebhookDELETE/webhooks/{WEBHOOK_ID}/?api_key={API_KEY}
Remove an Webhook by WEBHOOK_ID
cURL example:
curl --include \
--request DELETE \
'https://surfly.com/v2/webhooks/WEBHOOK_ID/?api_key=API_KEY'
- API_KEY
string
(required) Example: 3b57bd2db21c46d2875508b982968d26- WEBHOOK_ID
string
(required) Example: 1
Generated by aglio on 16 Aug 2022