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