Embed API

Goals ¶

The main purpose of Embed API is to enable partners to build rich integrations for support agents.

It is possible to integrate Surfly using our REST API, however in most cases it requires a lot of custom code to build a support queue page. Partners have to design their own UI, and business logic around the REST API, practically implementing Surfly Queue page from scratch.

SSO authentication makes it a little easier, because you can embed the Surfly dashboard in an iframe, and it will work seamlessly for the agent, without a need of a separate login into Surfly. However, not every partner has an SSO setup, and the default Surfly UI is not well adapted for such a use case (e.g. sidebar menu is redundant in most cases).

The Embed API solves all these issues by allowing to embed our standard dashboard functionality such as Queue, Settings, Agent Management in a simple and secure way.

Requirements ¶

We assume that partners who use the Embed API have access to our REST API. Security of the Embed API is based heavily on the secrecy of the REST API key. It is the responsibility of a partner to keep this REST key safe.

High-level overview ¶

Before showing a page to the user, the integrating app obtains an AGENT_TOKEN, using Surfly’s REST API. The integrating app uses the AGENT_TOKEN to generate an embed URL. This embed URL can be opened in an iframe inside the integrating app directly in the agent browser. The agent will be able to use the authenticated Surfly agent functionality inside the iframe, without explicit login into the Surfly portal.

Embed in 3 simple steps ¶

1. Obtain an AGENT_TOKEN ¶

First of all, you will need to use the REST API to generate the access token for a specific agent. Please take a look at the REST API call to obtain the access token.

2. Use the token in an embed URL ¶

The embed URL endpoints must always provide a valid AGENT_TOKEN in a query parameter. Currently we provide the following embed views:

https://app.surfly.com/embed/start/?agent_token=AGENT_TOKEN - page for creating outbound sessions. This endpoint accepts optional “url” query parameter. You can provide either a valid url to start a session or a 4-digit pin to join an existing session.

https://app.surfly.com/embed/queue/?agent_token=AGENT_TOKEN - support queue page

https://app.surfly.com/embed/history/?agent_token=AGENT_TOKEN - session history page

https://app.surfly.com/embed/options/?agent_token=AGENT_TOKEN - page for changing company-wide session options

If you plan to use these URL inside an iframe you should set the proper permissions in the allow attribute for it. For example, if you plan on using videochat, this iframe will need access to camera & microphone. Whereas WebRTC screenshots will require this iframe to have display-capture permission. Considering your requirements, your iframe HTML code can look something like:

<iframe width="1024" height="768" src="https://app.surfly.com/embed/history/?agent_token=`AGENT_TOKEN`" allow="autoplay *; camera *; microphone *; display-capture *; geolocation *;"></iframe>

When receiving a request to one of the embed pages, Surfly validates the AGENT_TOKEN and authenticates the user. Note that if the user was previously logged in to Surfly, that session will be invalidated.

If the token is invalid, the user will be logged out and see a page with the error.

3. Use the token in session links ¶

The generated AGENT_TOKEN can also be used by not-logged-in agents to join sessions with private_session option. Normally, followers in such sessions are only allowed in if they are already logged in Surfly dashboard. However, if an agent has an AGENT_TOKEN, they can pass it as a GET parameter agent_token to the follower link instead.

Example of a follower link with an agent token:

https://surfly.com/123-123-123?agent_token=AGENT_TOKEN

Demo page ¶

If you want to see the Embed API in action, there is a demo page here

SSO users ¶

For companies using SSO functionality, there is an embeddable version of the start page at https://app.surfly.com/embed/start/sso/. Note that it will only work if the user has previously logged in to the web interface.