Google+
Developers Network
Currently Being Moderated

Getting Started: Using the Agent API (REST)

Introduction

In order to successfully use the Agent 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 agent console application with the ability to log in, change agent status and take chat requests. Here is an example flow for using the Agent API.

 

 

 

Notes:

  • Before working with APIs you will need to familiarize yourself with the 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.
  • By default you cannot request keys for unsigned Agent API applications. If you need to use unsigned Agent API applications, please start a new discussion in the LivePerson Developer Community.

 

Prerequisites

To complete this Getting Started you need to perform the following in the LivePerson Admin Console:

  • Configure an agent to accept chat requests under User Set Up > Operators.
  • Create a Chat button to request a chat with an agent under Account Set Up > Page Code Builder.

 

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 signed API Calls. For more 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
Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b", oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity.

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="agent-session" href="https://dev.liveperson.net/api/account/12345678/agentSession"/>
</account>

 

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

 

Step 2: Logging In to an Agent Session

In this step you log an agent into the system. When logging in, the default filtering for the agent is set to "All Chats", and other users with the same credentials will be logged out. This resource is accessed from the agent-session link from Step 1. If the request succeeds a "201 Created" status code is returned.

 

To log an agent into the system:

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

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

 

Include the following headers:

HeaderValue
Acceptapplication/xml
Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity.

Content-Typeapplication/xml

 

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

 

<?xml version="1.0" encoding="UTF-8"?>
<loginData>
    <userName>dave</userName>
    <password>1234</password>
</loginData>

 

 

This request will log the agent called "dave" with password "1234" into the system. You can verify that the agent is logged in by going to the User Set Up > Operators page in the Admin Console. The agent is logged and their status is set to Away. An example is displayed next.

 

AdminConsole-AgentOnline.gif

 

2.  The link that is returned in the Location header is referred to as the agent-session-uri in the rest of the document. e.g., https://dev.liveperson.net/api/account/12345678/agentSession/789012345. This will be used in Step 3.

Step 3: Starting an Agent Session

In this step you use the agent-session-uri which uniquely identifies the session, and can be used for further interaction with the session. 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 start an agent session:

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

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

 

Include the following headers:

HeaderValue
Acceptapplication/xml
Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity.

Content-Typeapplication/xml

 

 

An example XML response is displayed next:

 

<?xml version="1.0" encoding="UTF-8"?>
<agentSessionId>
    <link rel="availability" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/availability"/>
    <link rel="incoming-requests" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/incomingRequests"/>
    <link rel="info" href="https://dev.liveperson.net/api/account/12345678/agentSession/789012345/info"/>
    <link rel="chat-available-slots" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/availableSlots"/>
</agentSessionId>

 

 

2.  The availability link from the response is used to access the availability resource, and will be used in Step 4.

 

3.  The incoming-requests link from the response is used to accept incoming requests to the agent, and will be used in Steps 5 and 6.

 

Step 4: Setting Agent Availability

In this step you set the agent's availability to accept chat requests. You can set the agent’s availability to Online, Offline, Away, or Occupied. The resource is accessed from the availability link from Step 3. If the request is successful a "200 OK" status code is returned.

 

To set the agent's availability:

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

https://dev.liveperson.net/api/account/12345678/agentSession/789012345/availability?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
AuthorizationOAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",   oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been   inserted for clarity.
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"):

 

<availability>
    <chat>Online</chat>
</availability>

 

 

You can verify that the agent's status was set correctly by issuing the following GET request (https://dev.liveperson.net/api/account/12345678/agentSession/789012345/availability?v=1) or by referring to the User Set Up > Operators page in the Admin Console.

 

Step 5: Determining Incoming Chat Requests

In this step you determine the number of incoming chat requests. The results include ringnigCount and link elements. The link element includes an accept-next-chat attribute. If there are no incoming chat requests then the relationship link will not appear. This resource is accessed from the incoming-requests link from Step 3. If the request is successful a "200 OK" status code response is returned.

 

To determine incoming chat requests:

1.  Click the Chat button to initiate a chat request with an agent. A chat button can be created using the Account Set Up > Page Code Builder page in the Admin Console. An example is displayed next.

 

chat_button.png

 

The chat window is displayed with a message "Please wait for a site operator to respond." An example is displayed next.

 

Chat_window.png

 

2.  Issue a GET request to the incoming-requests link. Example URI:

https://dev.liveperson.net/api/account/12345678/agentSession/89012345/incomingRequests?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been   inserted for clarity.

Content-Typeapplication/xml

 

The URI determines the number of chat request that are waiting in the queue to be assigned to agents. An example XML response with one response (ringingCount) is displayed next.

 

<?xml version="1.0" encoding="UTF-8"?>
<incomingRequests>
    <ringingCount>1</ringingCount>
    <link rel="accept-next-chat" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/incomingRequests"/>
</incomingRequests>



 

Step 6: Accepting the Next Available Chat

In this step you initiate a request from a visitor to chat with an agent. The request is placed in the chat queue and an agent needs to accept the chat request. This resource is accessed from the incoming-requests link from Step 3. The URI (including the Chat ID) for  the chat session is returned in the Location header. If the request succeeds a "201  Created" status code is returned.

 

To accept a chat request:

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

https://dev.liveperson.net/api/account/12345678/agentSession/7890123/incomingRequests?v=1

 

Include the following headers:

HeaderValue

Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been   inserted for clarity.

Acceptapplication/xml
Content-Typeapplication/xml

 

 

The visitor receives a message indicating that they are now chatting with a particular agent. An example is displayed next.

 

Chat_window_agent.png

 

2. The link that is returned in the Location header (chat-session-uri) is used to access the chat session resources. E.g., https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/H38001395503749281967361225793255837004K902. This will be used in step 7.

 

Step 7: Managing a Chat

In this step, you manage the chat related operations such as:

  • Requesting Chat Events
  • Adding Chat Lines
  • Requesting Chat Information
  • Ending the Chat

7A:  Requesting Chat Events

In this step you retrieve the Events section of the chat session, which includes chat events such as: state, url, and line. This retrieves the chat event, information and URIs. The URIs can be used for transferring the chat to another agent or for visit session resources. When a chat is requested, the server checks for chat activity. If a chat is not active for a certain amount of time, the chat is ended by the server. Any call to the API resets the inactivity time. As a best practice, the Incoming Requests method should be called periodically to get updates from the server. The URI for polling should always be the URI specified in the "next" link tag, which will retrieve events that were added after the last poll.

 

The chat-session-uri resource is accessed from the link in the Location header from Step 6, and then the events resource is accessed from a link that is returned in the chat-session-uri resource. If the requests are successful a "200 OK" status code is returned.

 

To retrieve chat events and information:

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

https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902?v=1

 

Include the following headers:

HeaderValue

Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been   inserted for clarity.

Acceptapplication/xml
Content-Typeapplication/xml

 

An example XML response is displayed next:

 

<?xml version="1.0" encoding="UTF-8"?>
<chat>
    <link rel="self" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/chat/H38001395503749281967361225793255837004K902"/>
    <link rel="visit-id" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/visits/visit/H38001395503749281967361225793255837004K902"/>
    <link rel="transfer" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/chat/H38001395503749281967361225793255837004K902/transfer"/>
    <link rel="events" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/chat/H38001395503749281967361225793255837004K902/events"/>
    <link rel="info" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/chat/H38001395503749281967361225793255837004K902/info"/>
    <link rel="next" href="https://dev.liveperson.com/api/account/12345678/agentSession/
789012345/chat/H38001395503749281967361225793255837004K902?from=4"/>
    <events>
        <link rel="next" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/chat/H38001395503749281967361225793255837004K902/events?from=4"/>
        <event type="state" id="0">
            <time>2011-01-30T17:46:19.378+02:00</time>
            <state>waiting</state>
        </event>
        <event type="line" id="1">
            <time>2011-01-30T17:46:19.380+02:00</time>
            <text>Please wait for a site operator to respond.</text>
            <by>info</by>
            <source>system</source>
            <systemMessageId>4</systemMessageId>
        </event>
        <event type="state" id="2">
            <time>2011-01-30T17:46:33.010+02:00</time>
            <state>chatting</state>
        </event>
        <event type="line" id="3">
            <time>2011-01-30T17:46:33.011+02:00</time>
            <text>You are now chatting with 'john'</text>
            <by>info</by>
            <source>system</source>
            <systemMessageId>3</systemMessageId>
        </event>
    </events>
    <info>
        <state>chatting</state>
        <agentName>john</agentName>
        <startTime>2011-01-30T17:46:19.380+02:00</startTime>
        <lastUpdate>2011-01-30T17:46:53.056+02:00</lastUpdate>
        <chatTimeout>40</chatTimeout>
        <visitorId>1600500010</visitorId>
        <agentTyping>not-typing</agentTyping>
        <visitorTyping>not-typing</visitorTyping>
        <visitorName>visitor</visitorName>
    </info>
</chat>

 

2.  The events link from the response is used to get the lines from the chat session and the chat status. This link will be used in Steps 7B and 7D.

 

3.  The info link from the response is used to get information about the chat session. This link will be used in Steps 7C.

 

To request chat events:

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

https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902/events?v=1

 

Include the following headers:

HeaderValue

Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been   inserted for clarity.

Acceptapplication/xml
Content-Typeapplication/xml

 

This URI retrieves the Events of the chat. An example XML response is displayed below.

 

<?xml version="1.0" encoding="UTF-8"?>
<events>
     <link rel="self" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/chat/H38001395503749281967361225793255837004K902/events" />
    <link rel="next" href="https://dev.liveperson.net/api/account/12345678/agentSession/
789012345/chat/H38001395503749281967361225793255837004K902/events?from=8"/>
    <event type="state" id="0">
        <time>2010-11-28T13:55:24.910+02:00</time>
        <state>waiting</state>
    </event>
    <event type="line" id="1">
        <time>2010-11-28T13:55:24.910+02:00</time>
        <text>Please wait for a site operator to respond.</text>
        <by>info</by>
        <source>system</source>
    </event>
    <event type="state" id="2">
        <time>2010-11-28T13:55:35.114+02:00</time>
        <state>chatting</state>
    </event>
    <event type="line" id="3">
        <time>2010-11-28T13:55:35.114+02:00</time>
        <text>You are now chatting with 'dave'</text>
        <by>info</by>
        <source>system</source>
    </event>
    <event type="line" id="4">
        <time>2010-11-28T14:03:28.488+02:00</time>
        <text>Can you give me advice on which product is more
            reliable?</text>
        <by>dave</by>
        <source>agent</source>
    </event>
    <event type="line" id="5">
        <time>2010-11-28T15:05:51.514+02:00</time>
        <text>Can you give me advice on which product is more
            reliable?</text>
        <by>dave</by>
        <source>agent</source>
    </event>
    <event type="line" id="6">
        <time>2010-11-28T15:05:59.780+02:00</time>
        <text>ok</text>
        <by>you</by>
        <source>visitor</source>
    </event>
    <event type="line" id="7">
        <time>2010-11-28T15:06:06.030+02:00</time>
        <text>I would also like price quotes for other products.</text>
        <by>you</by>
        <source>visitor</source>
    </event>
</events>

 

 

7B:  Adding Chat Lines

In  this step you add agent lines to the chat so that the agent can communicate with the visitor. The chat lines are displayed in the Event details. This resource is also accessed from the events link in Step 7A. If the request succeeds a "201 Created" status code response is returned. The URI of the event that was added is found in the Location header.

 

To add lines to a chat:

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

https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902/events?v=1

 

Include the following headers:

HeaderValue

Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been   inserted for clarity.

Acceptapplication/xml
Content-Typeapplication/xml

 

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

 

<event type="line">
<text>Can you give me advice on which product is more reliable?</text>
</event>

 

This URI adds a new line of text from the agent.

 

7C:  Requesting Chat Information

In this step you retrieve the general information about the chat such as state, skill, agent name, visitor name, start time of the chat, last update, visitor ID, agent typing, and visitor typing. This resource is accessed from the info link from Step 7A. If the request succeeds a "200 OK" status code response is returned.

 

To query chat request information:

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

https://dev.liveperson.com/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902/info?v=1

 

Include the following headers:

HeaderValue
Acceptapplication/xml
Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been   inserted for clarity.

Content-Typeapplication/xml

 

An example XML response is displayed next.

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<info>
    <link rel="self" href="https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902/info"/>
    <link rel="visitor-name" href="https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902/info/visitorName"/>
    <link rel="visitor-typing" href="https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902/info/visitorTyping"/>
    <link rel="agent-typing" href="https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902/info/agentTyping"/>
    <state>chatting</state>
    <agentName>daniel</agentName>
    <startTime>2011-02-22T16:08:36.267+02:00</startTime>
    <lastUpdate>2011-02-22T16:14:16.832+02:00</lastUpdate>
    <chatTimeout>40</chatTimeout>
    <visitorId>999941730001</visitorId>
    <agentTyping>not-typing</agentTyping>
    <visitorTyping>typing</visitorTyping>
    <visitorName>visitor</visitorName>
</info>

 

7D:  Ending the Chat

In this step you end the visitors chat. Issue a POST request to the events link to log out. This resource is accessed from the events link in Step 7A. If the request succeeds a "201 Created" status code response is returned.

 

To end a chat:

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

https://dev.liveperson.net/api/account/12345678/agentSession/789012345/chat/
H38001395503749281967361225793255837004K902/events?v=1

 

Include the following headers:

HeaderValue

Authorization

OAuth   oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D",

oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization should be contained on a single line. Newlines have been   inserted for clarity.

Acceptapplication/xml
Content-Typeapplication/xml

 

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

 

<event type="state">
<state>ended</state>
</event>

 

 

Note: After the chat ends, the session continues as long as you continue to request events or information. During this time, you can add custom variables to the chat sessions.

 

This is the final step in the example flow. For more information, refer to Agent API (REST) Reference.

Comments

Delete Document

Are you sure you want to delete this document?