Google+
Developers Network
Currently Being Moderated

Getting Started: Building a Visit API Application

Introduction

In order to successfully use the Visit API (REST), you must understand how to construct a URI and interpret the response. All resources and operations exposed by the API are accessible through a hierarchy of URIs. Using this Getting Started you will be able to build an application that creates a visit and adds a Color and Material custom variable to the visit. Here is an example flow for using the Visit API.

 

 

 

 

Note: Before working with APIs you will need to familiarize yourself with process of working in the LivePerson Developer Community, which includes applying for: an Application Key and Test Account. For more information, refer to Getting Started with Applications.

 

Prerequisites

To complete this Getting Started you need to perform the following:

  • In the LivePerson Admin Console, set up an agent to accept chat requests under User Set Up > Operators.
  • Start the LivePerson Agent Console and make sure that the agent's status is set to Online.

 

Step 1: Determining the Base Resources

In this step you determine the base resources for your account. An Application Key is used to identify applications that will be developed. Anyone who wishes to use a LivePerson API must first receive a unique Application Key from the LivePerson community, and then include it in every request as an Authorization header. The format of the header changes depending on whether the account allows signed or unsigned API calls. This Getting Started uses Unsigned API Calls. For information on signing APIs, refer to OAuth for Signed REST Communication.

 

To determine the base resources:
1.  Issue a GET request to the following URI:

 

where {accountID} is your LivePerson account number. For example, https://api.liveperson.net/api/account/12345678?v=1.

 

Include the following headers:

Header KeyValue
Acceptapplication/xml
AuthorizationLivePerson appKey={xyz}
where {xyz} is the alphanumeric application key e.g.,25dfd026beff1bf9913f6148f63a7f81
Content-Typeapplication/xml

 

In return to this request, you will be redirected to the base resources for your account. The version number must be included in every request as a query parameter (currently use v=1). If you issue the request to the specified domain, you will receive the base URI as a response.

 

For example, here are the available resources for account "12345678":

<?xml version="1.0" encoding="UTF-8"?>
<account id="12345678">
<link rel="self" href="https://dev.liveperson.net/api/account/12345678"/>

<link rel="visit" href=https://dev.liveperson.net/api/account/12345678/visit/>

<account>

 

2.  The visit link from the response is used to access all session resources and will be used in Step 2.

 

Step 2: Creating a Visit

In this step you initiate a new visit session. This request returns a "session-uri" which uniquely identifies this session, and can be used for further interaction with the session. The URI of the visit session is returned in the Location header. This URI is referred to as the visit-session-uri in the rest of the document. This resource is accessed from the visit link from Step 1. If the request succeeds a "201 Created" status code is returned.

 

To create a visit:

1.  Issue a POST request to the visit link. Example URI:

https://dev.liveperson.net/api/account/12345678/visit?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
AuthorizationLivePerson appKey=25dfd026beff1bf9913f6148f63a7f81
Content-Typeapplication/xml

 

2.  The link that is returned in the Location header will be used in Step 3. e.g.,

https://dev.liveperson.net/api/account/12345678/visit/H3368623705661212332K1203.

 

Step 3: Retrieving All Resources for a Visit

In this step you use the visit-session-uri, which returns an XML with links to the available resources. This resource is accessed from the link in the Location header from Step 2. If the request succeeds a "200 OK" status code is returned.

 

To retrieve all resources for a visit:

1.  Issue a GET request to the visit-session-uri. Example URI:

https://dev.liveperson.net/api/account/12345678/visit/H3368623705661212332K1203?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
AuthorizationLivePerson appKey=25dfd026beff1bf9913f6148f63a7f81
Content-Typeapplication/xml

 

An example XML response is displayed next:

 

<?xml version="1.0" encoding="UTF-8"?>
<visitId>
    <link rel="self" href="https://dev.liveperson.net/api/account/12345678/visit/H3368623705661212332K1203"/>
<link rel="info" href="https://dev.liveperson.net/api/account/12345678/
visit/H3368623705661212332K1203/info">
    <link rel="custom-variables" href="https://dev.liveperson.net/api/account/12345678/visit/
H3368623705661212332K1203/customVariables"/>
    <link rel="keep-alive" href="https://dev.liveperson.net/api/account/12345678/visit/
H3368623705661212332K1203/keepAlive"/>
    <link rel="chat-request" href="https://dev.liveperson.net/api/account/12345678/visit/
H3368623705661212332K1203/chat/request"/>
</visitId>


 

 

2.  The custom-variables link from the response is used to set or create specific custom variables. This link will be used in Step 4.

 

3.  The info link from the response is used to retrieve visit information. This link will be used in Step 5.

 

4. The chat-request link from the response is used to initiate a chat session and is the main chat resource. This link will be used in Step 6.

 

5. The keep-alive link from the response is used to avoid a visit time out. This link will be used in Step 7.

 

Step 4: Setting Custom Variables

In this step you set the custom variables for the visit. The resource is accessed from the custom-variable link from Step 3. If the request succeeds a "200 OK" status code is returned.

 

To set custom variables for a visit:

1.  Issue a POST request to the custom-variable link. Example URI:

https://dev.liveperson.net/hc/api/account/12345678/visit/H3368623705661212332K1203/customVariables?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
AuthorizationLivePerson appKey=25dfd026beff1bf9913f6148f63a7f81
Content-Typeapplication/xml
X-HTTP-Method-OverridePUT

 

Note: Currently PUT is supported using a POST method with the "X-HTTP-Method-Override=PUT" header.

 

Add the following Body XML ("application/xml", with a character set of "UTF-8"):

 

customVariables>
<customVariable><name>color</name><value>blue</value></customVariable>
<customVariable><name>material</name><value>silver</value></customVariable>
</customVariables>

 

The XML above sets two custom variables: color=blue and material=silver


Step 5: Retrieving the Details of a Visit

In this step you retrieve information regarding the visit. The resource is accessed from the info link from Step 3. If the request succeeds a "200 OK" status code is returned.

 

To retrieve the details of a visit:

1.  Issue a GET request to the info link. Example URI:

https://dev.liveperson.net/hc/api/account/12345678/visit/H3368623705661212332K1203/info?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
AuthorizationLivePerson appKey=25dfd026beff1bf9913f6148f63a7f81
Content-Typeapplication/xml

 

 

Add the following Body XML ("application/xml", with a character set of "UTF-8"):

 

<?xml version="1.0" encoding="UTF-8"?>
<info>
    <visitorId>999941690007</visitorId>
    <link rel="self" href="https://dev.liveperson.net/api/account/12345678/
visit/H3368623705661212332K1203/info"/>
</info>

 

 

Step 6: Initiate a Request to Chat

In this step you initiate a request to chat. A new chat session is created, and the session is placed in the agent's queue. The resource is accessed from the chat-request link from Step 3. If the request succeeds a "201 Created" status code is returned. For more information on the Chat API, refer to Chat API (REST) Reference.

 

To initiate a request to chat:

1.  Issue a POST request to the chat-request link. Example URI:

https://dev.liveperson.net/api/account/12345678/visit/H3368623705661212332K1203/chat/request?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
AuthorizationLivePerson appKey=25dfd026beff1bf9913f6148f63a7f81
Content-Typeapplication/xml

 

Add the following Body XML ("application/xml", with a character set of "UTF-8"):

 

<request>
<skill>Sales</skill>
<maxWaitTime>0</maxWaitTime>
</request>



 

Note: The Body XML above is a partial list of parameters. For a full list, refer to Chat Request.

 

The skill parameter specifies that this chat is for the Sales skill. The maxWaitTime parameter of 0 specifies immediate availability. The following figure displays this chat request in the LivePerson Agent Console. The agent needs to click the Take button to accept the chat.

 

AgentConsole.gif


Step 7: Keeping the Visitor Session Alive

In this step you keep the visitor session alive and retrieve the maximum time interval for keeping the visitor alive (in seconds). The time interval is based on the account's configuration. The resource is accessed from the keep-alive link from Step 3. If the request succeeds a "200 OK" status code is returned.

 

Note: You only need to use this resource to keep the visit session alive if you do not send any other requests.

 

To retrieve all resources for a visit:

1.  Issue a POST request to the keep-alive link. Example URI:

https://dev.liveperson.net/api/account/12345678/visit/H3368623705661212332K1203/keepAlive?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
AuthorizationLivePerson appKey=25dfd026beff1bf9913f6148f63a7f81
Content-Typeapplication/xml
X-HTTP-Method-OverridePUT

 

Note: Currently PUT is supported using a POST method with the "X-HTTP-Method-Override=PUT" header.

Comments

Delete Document

Are you sure you want to delete this document?