Google+
Developers Network
Currently Being Moderated

Agent API (REST) Reference

Before reading this document it is recommended that you refer the following documents:

 

Contents


 

Introduction

This document describes the Agent API (REST).

 

Notes: To implement Agent API, the following should be taken into consideration:

  • From the time an agent is logged in, the server checks for agent activity. If an agent is not active (an Agent API request is not sent for a certain amount of time), the agent is logged out by the server. The default timeout is 400 seconds.
  • As a best practice, the Incoming Requests method should be called periodically to receive updates from the server.
  • 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.

     

    Documentation Conventions

    The following documentation conventions are observed:

    • The name of the resource or relationship link is listed in the main headings in orange text.
    • Explanations of how to get to each resource, either via a static URI (from the Location header) or via a relationship link, are found in the URI sections.
    • The actions that are applicable for each resource are listed in the subheadings in orange italic text.
    • The method for using the resources (i.e., GET, DELETE, POST, and PUT) is found in the HTTP Method sections.
    • The supported input and output formats are found in the Formats sections.
    • If applicable, parameters and examples are provided for each resource.

     

    Base Resource

    The first resource that you should access is the Base Resource.

    In order to start using the Agent Chat API, issue a GET request to the following URI:

     

    https://api.liveperson.net/api/account/{accountID}?v=1

     

    In return to this request, you will be redirected to the correct domain for your Developer account.
    For example, https://dev.liveperson.net/api/account/{accountID}

     

    Once you follow the redirection link, you will receive an XML response with links to the available resources for that account. You should use these resources which will lead you to additional resources as appropriate.

     

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

     

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

     

     

     

    Elements in the Response
    NameDescriptionType/Value

    account

    LivePerson account number.

    string
    agent-sessionURI to log in to the system.link relationship


    Agent Session

    Description

    Submits an agent login request. The body media type must be specified (see Formats below). 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.

     

    Notes:

    • The URI of the session is returned in the Location header. This URI is referred to as the agent-session-uri in this document.
    • To establish and use an agent session via unsigned requests, you must correctly handle cookies which are set by the server in response to API requests. Cookies are scoped to a specific agent session. When working with multiple agents, make sure to track cookies separately for each agent session. There is no need to use this security cookie when using Signed requests, therefore it will not be set by the server.

    URI

    This resource is accessed from the agent-session link in response to the Base Resource request.

     

     

    Logging In to an Agent Session

    If successful a "201 Created" status code response is returned.

    HTTP Method

    POST

    Formats

    The body media type must have one of the following formats:

    • application/x-www-form-urlencoded
    • application/xml
    • application/json

     

    Body Parameters

    You can use the following parameters in the XML body:

    NameDescriptionType/Value

    username

    The agent's user name. This is a mandatory parameter.

    alphanumeric

    password

    The agent's password. This is a mandatory parameter.

    alphanumeric
    appVersionIndicates the application name in use. Default: REST.numeric
    repSyncTimeAgent UTC time in milliseconds. Default: The server time in milliseconds.long
    repLocaleNot implemented-

     

    application/x-www-form-urlencoded Body Example

    username=john&password=123

     

    application/xml Body Example

     

    <loginData>
        <userName>john</userName>
        <password>123</password>
    </loginData>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

     

     

    application/json Body Example

     

    {
      "loginData" : {
        "userName" : "john",
        "password" : "123"
      }
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    


    Agent Session URI

    Description

    Returns an XML response with links to the available resources for a particular agent session or logs out an agent that is currently logged in.

    URI

    This resource is accessed from a link in the Location header from the response to the Agent Session POST request.

     

    Retrieving All Resources for a Session

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <agentSessionId>
        <link rel="self" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123"/>
        <link rel="availability" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/7890123/availability"/>
        <link rel="available-agents" href="https://dev.liveperson.net/hc/api/
    account/12345678/agentSession/7890123/
    availableAgents"/>
        <link rel="incoming-requests" href="https://dev.liveperson.net/hc/api/account/12345678/
    agentSession/7890123/incomingRequests"/>
        <link rel="info" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/7890123/info"/>
        <link rel="chat-available-slots" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/
    7890123/availableSlots"/>
    </agentSessionId>

     

     

    Elements in the Response
    NameDescriptionType/Value

    availability

    URI to determine or set agent availability.

    link relationship
    available-agents

    URI to determine available agent.

    link relationship
    incoming-requestsURI to determine the number of incoming chat requests or to return an existing chat session.link relationship
    infoURI to provide the agent's information.link relationship
    chat-available-slotsURI to determine the number of available slots for chats.link relationship

     

    Logging Out From a Session

    Description

    If successful a "200 OK" status code response is returned.

    HTTP Method

    DELETE*

     

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

    Formats

    xml, json

     

    Agent Availability

    Description

    Returns the agent's availability to accept chat requests or sets the agent's availability to Online, Away or Occupied.

     

    where:

    • Online: Agents can accept chat requests.
    • Away: Agents cannot accept chat requests.
    • Occupied: Agents can receive chats that were transferred to them.

    URI

    This resource is accessed from the availability link in response to the Agent Session URI GET request.

     

    Retrieving Current Availability

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <availability>
        <chat>Away</chat>
    </availability>

     

    Elements in the Response
    NameDescriptionType/Value

    chat

    Displays the agent's availability to accept chats.string. Can be one of Online | Away | Occupied


    Setting Agent Availability

    HTTP Method

    PUT *

     

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

    Formats

    xml, json

    Body Parameters

    You can use the following parameters in the XML body:

    NameDescriptionType/Value

    chat

    Sets the agent's availability.string. Can be one of Online | Away | Occupied

     

    Request Body XMLExample

     

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

     

     

    Request Body JSON Example

     

    {
        "availability": {
            "chat" : "Online"
        }
    }

     

    Available Agents

    Description

    This resource will return all agents which are not disabled in the system for the account provided in the request.  The agents returned include both online and offline agents, but not agents that were disabled (for any reason).  For each agent this resource will return details such as ID, username, nickname, and more. The resource will also return, for each agent, the agent's skills and the agent's availability to accept chats (the number of chats this agent is configured to take and the number of chats in which this agent is already involved).

     

    This resource can be used to know to which other agent's you can transfer chats. Also, you might want to use this method if you want to present all agents in a table (possibly indicating for each agent if they can take chats or not). In these cases you would want to call this resource periodically in order to be updated with other agent's statuses.


    This resource can be called with filter parameters. This will generate a minimized list only for agents that with these parameters.

    URI

    This resource is accessed from the available-agents link in response to the Agent Session URI GET request.

     

    Retrieving Available Agents

    If successful a "200 OK" status code response is returned. The request will return the details of all the agents that follow the parameter conditions (or all agents if no parameters are provided). When the request is submitted without any filter parameters, a  next link will be returned for retrieving only agents that were modified since the last request.

     

    HTTP Method

    GET

    Formats

    xml, json

    Parameters

    You can filter the returning available agents by using the following parameters:

     

    NameDescriptionType/Value

    skill

    Skill name. Filter the returned agents list by the requested skill.

    For example:  {available-agents}?skill=Default&v=1.

    alphanumeric

    chatState

    State name. Filter the returned agents list by the agent's chat state.

    String can be one of Online | Offline | Occupied | Away

    voiceStateState name. Filter the returned agents list by the agent's voice state.String can be one of Online | Offline | Occupied | Away

    Response XML Example

     

    <availableAgents>
    <agents>
       <agent id="1000" chatState="1" voiceState="1" maxChats="3">
         <userName>Christopher Ben</userName>
         <nickname>Christopher</nickname>
         <email>test@test.com</email>
         <privilegeGroup>Test operators</privilegeGroup>
         <skills>
           <skill>1</skill>
           <skill>13</skill>
         </skills>
         <chats>3</chats>
       </agent>
       <agent id="1001" chatState="1" voiceState="1" maxChats="3">
         <userName>Adam</userName>
         <nickname>Berg</nickname>
         <email>test1@test.com</email>
         <privilegeGroup>Test operators</privilegeGroup>
         <skills>
           <skill>1</skill>
           <skill>13</skill>
           <skill>14</skill>
         </skills>
         <chats>2</chats>
       </agent>
    </agents>
    <link href="https://webserver/api/account/23232443/agentSession/210473400/availableAgents?timeStamp=1322077963361" rel="next"/>
    </availableAgents>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Response JSON Example

     

    {    "availableAgents" :
        {
            "agents" : {
                "agent" : [ {
                    "@chatState" : "4",
                    "@id" : "2",
                    "@maxChats" : "-1",
                    "@voiceState" : "1",
                    "email" : "test@test.com",
                    "nickname" : "Agent1-Nickname",
                    "privilegeGroup" : "administrators",
                    "skills" : { "skill" : [ "2" , "4" ] },
                    "userName" : "Agent1"
                } ] },
                "link" : { "@href" : "https://webserver/api/account/20026006/agentSession/982759926/availableAgents?timeStamp=1331544926464",
                        "@rel" : "next"
                }
        }}

     

     

    Elements in the Response
    NameDescriptionType/Value
    availableAgentsThe main element which contains the list of available agents and the link to the next call.Element
    agentsContains the list of available agents.Element
    agentContains the agent's details (as attributes its ID, chatState, voiceState, maxChats) and more details as child elements.Element
    idThe ID associated with this agent.numeric
    chatStateThe state of the agent for chat.
    1 - Offline - Agent is logged off.
    2 - Online - Agent can accept chat requests.
    3 - Occupied - Agent can receive chats that were transferred to him/her.
    4 - Away - Agent cannot accept chat requests.
    numeric
    voiceStateThe state of the agent for voice.
    1 - Offline - Agent is logged off.
    2 - Online - Agent can accept voice requests.
    3 - Occupied - Agent can receive voice requests that were transferred to him/her.
    4 - Away - Agent cannot accept voice requests.
    numeric
    maxChatsThe maximum number of chats this agent can take, according to his/her current availability.numeric
    userNameThe username of this agent.alphanumeric
    nicknameThe nickname of this agent.alphanumeric
    skillsThe list of skills for this agentElement
    skillA skill ID for this agent.numeric
    chatsThe current number of chats for the agent.numeric

    link with rel="next"

    Use this link to call the next available agents request.link relationship

     

    Available Slots

    Description

    The capacity (or number of slots) in the chat system, is the total number of chats that can be handled simultaneously by all online agents. Since some agents can handle multiple chats, the number of slots is usually larger than the number of agents. Available Slots refers to the number of slots that are free at the current time.

    URI

    This resource is accessed from the chat-available-slots link in response to the Agent Session URI GET request.

     

    Retrieving Available Slots

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Parameters

    You can request available slots using the following parameters:

     

    NameDescriptionType/Value

     

    skill

     

    Skill name. Calculates the number of available slots in queue for a  specific skill. For example,  {chat-available-slots}?skill=Default&maxWaitTime=200&v=1.

    alphanumeric

    maxWaitTime

    The maximum time in seconds that a visitor can wait before a chat  starts. This parameter must be between 0 and 86,400 seconds (24 hours).   Use 0 for immediate availability.numeric

     

    You can request available slots for a specific agent using the following parameter:

     

    NameDescriptionType/Value

    agent

    Agent login name, calculates the number of available slots of a specific agent. This parameter cannot be used with other parameters. For example,  {chat-available-slots}?agent=John&v=1.

    alphanumeric

     

    Response XML Example

     

    <availableSlots>2</availableSlots>

     

    Notes:

    • The Application Key must include Chat privileges.
    • The calculation of wait time is based on a statistical estimate and may change constantly.
    • When the number of available slots is unlimited the response is -1.


    Agent Information

    Description

    Returns the agent's information such as name, maximum number of chats allowed and availability.

     

    Note: When maxChats is unlimited, -1 is returned.

    URI

    This resource is accessed from the info link in response to the Agent Session URI GET request.

     

    Retrieving Agent Information

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <info>
        <link rel="self" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/7890123/info"/>
        <agentName>John</agentName>
        <displayName>John</displayName>
        <loginName>John</loginName>
        <id>3</id>
        <maxChats>4</maxChats>
        <availability>
            <chat>Away</chat>
        </availability>
    </info>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    Elements in the Response
    NameDescriptionType/Value
    agentNameThe name the visitors will see when chatting with the agent. It is the nickname of the agent defined in the Admin Console.alphanumeric
    displayNameThe name displayed in the list of agents in the Admin Console.alphanumeric
    loginNameThe agent uses this name to login.alphanumeric
    idThe agent's unique ID.numeric
    maxChatsThe maximum number of chats the agent can handle simultaneously.numeric
    availabilityThe availability state of the agent.string. Can be one of Online | Away | Occupied

     

    Incoming Requests  

    Description

    Returns the number of incoming chat requests or accepts the next chat request.

    URI

    This resource is accessed by using the incoming-requests link in response to the Agent Session URI GET request.

     

    Determining Incoming Chat Requests

    Returns the number of incoming chat requests assigned to the logged in agent and a link to accept the next chat request. The results include ringnigCount and link elements. The ringingCount includes the number of chat requests that are assigned to the agent. The link element includes an accept-next-chat attribute. If there are no incoming chat requests then the rel link will not appear. If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <incomingRequests>
        <ringingCount>1</ringingCount>
        <link rel="acceptNextChat" href="https://dev.liveperson.net/api/
    account/12345678/agentSession/7890123/incomingRequests"/
    >
    </incomingRequests>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    Elements in the Response
    NameDescriptionType/Value
    ringingCountNumber of incoming requests to chat with an agent.numeric
    acceptNextChatAccept next chat in the queue.link relationship

     

    Accepting a Chat

    If a chat request exists the request will return an existing chat session. You should verify the results to see if there are any chat requests before accessing the resource. The chat-session-uri is displayed in the Location header. No Body parameters should be posted. If successful a "201 Created" status  code response is returned.

    HTTP Method

    POST

    Formats

    xml, json

     

    Chat Session URI

    Description

    Retrieves the chat events, information and resources.

    URI

    This resource is accessed from the Location header in the Incoming Requests POST request.

     

    Retrieving Chat Resources, Events and Information

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    XML, JSON

    Response XML Example

     

    <chat>
    <link rel="self" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419"/>
    <link rel="events" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/events"/>
    <link rel="info" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/info"/>
    <link rel="next" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419?from=4"/>
    <events>
    <link rel="self" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/events"/>
    <link rel="next" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/events?from=4"/>
    <event type="state" id="0">
    <time>2011-02-13T17:43:45.409+02:00</time><state>waiting</state>
    </event>
    <event type="line" id="1">
    <time>2011-02-13T17:43:45.409+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-02-13T17:43:47.082+02:00</time>
    <state>chatting</state></event>
    <event type="line" id="3">
    <time>2011-02-13T17:43:47.083+02:00</time>
    <text>You are now chatting with 'John'</text>
    <by>info</by>
    <source>system</source>
    <systemMessageId>3</systemMessageId></event>
    </events>
    <info>
    <link rel="self" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/info"/>
    <link rel="visitor-name" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/visitorName"/>
    <link rel="visitor-typing" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/visitorTyping"/>
    <link rel="agent-typing" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/agentTyping"/>
    <state>chatting</state>
    <agentName>John</agentName>
    <startTime>2011-02-13T17:43:45.409+02:00</startTime>
    <lastUpdate>2011-02-13T17:43:47.092+02:00</lastUpdate>
    <chatTimeout>40</chatTimeout>
    <visitorId>1600350003</visitorId>
    <agentTyping>not-typing</agentTyping>
    <visitorTyping>typing</visitorTyping>
    <visitorName>visitor</visitorName>
    <rtSessionId>16779419</rtSessionId>
    </info>
    <link rel="visit-id" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/visits/visit/
    H9067284163308954154K16779419"/>
    <link rel="transfer" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/transfer"/>
    <link rel="agent-survey" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/survey"/>
    <link rel="collaboration-channels" href="https://dev.liveperson.net/api/account/12345678/agentSession/7890123/chat/
    H9067284163308954154-4047270689103073078K16779419/collaborationChannel"/>
    </chat>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

     

    Elements in the Response
    NameDescriptionType/Value
    visit-idURI for aggregated data and links for information on the visit, pages visited  and custom variables related to the visit.link relationship
    transferTransfer a chat from an agent to a specific skill.link relationship
    eventsRetrieves the chat events such as: state, resource and line. Use this method to periodically poll for new events in the chat session.link relationship
    agent-surveyURI for retrieving the Agent survey structure and submitting the survey data.link relationship
    collaboration-channelsURI for creating collaboration channels and sending collaborationeventslink relationship
    info
    Retrieves information regarding the current status of the chat.link relationship
    next
    The method for polling additional events. This will retrieve events added after your last poll.link relationship
    <events>The chat events. See Chat Events.-
    <info>The actual information about the chat. See Chat Information.-

     

    Chat Events

    Description

    Retrieves the chat events such as: state, url, line or callaboration; adds a line or ends a chat.

    URI

    This resource is accessed from the events link in the Chat Session URI GET request.

     

    Retrieving Chat Events

    Use this method to periodically poll for new events in the chat session. The method for polling should always be the URI specified in the "next" link. This will only retrieve events added after your last poll. If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Parameters

    NameDescriptionType/Value

    from

    The ID of the first event that is shown in the response.numeric

     

    Response XML Example

     

    <events>
    <link rel="self" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/
    901234567/chat/H3135644473379525-2249553296845149375K10071773/events">
    <link rel="next" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/
    901234567/chat/H3135644473379525-2249553296845149375K10071773/events?from=5">
    <event type="line" id="0">
    <time>2009-08-05T16:49:10.513+03:00</time>
    <text>Please wait for a site operator to respond. We
    will be with you in 0 minutes and 19 seconds.</text>
    <by>info</by>
    <source>system</source>
    <systemMessageId>4</systemMessageId>
    </event>
    <event type="state" id="1">
    <time>2009-08-05T16:49:10.513+03:00</time>
    <state>waiting</state>
    </event>
    <event type="state" id="2">
    <time>2009-08-05T16:49:18.138+03:00</time>
    <state>chatting</state>
    </event>
    <event type="line" id="3">
    <time>2009-08-05T16:49:18.153+03:00</time>
    <text>You are now chatting with 'John'</text>
    <by>info</by>
    <source>system</source>
    <systemMessageId>3</systemMessageId>
    </event>
    <event type="line" id="4">
    <time>2009-08-05T16:49:25.794+03:00</time>
    <text>How can I help you?</text>
    <by>john</by>
    <source>agent</source>
    </event>
    <event type="line" id="5">
    <time>2009-08-05T16:50:25.794+03:00</time>
    <text>Please wait while I transfer the chat to 'Bob'.</text>
    <by>info</by>
    <source>system</source>
    <systemMessageId>13</systemMessageId>
    </event>
    <event type="line" id="6">
    <time>2009-08-05T16:55:25.794+03:00</time>
    <text>Visitor is interesting in skiing vacation</text>
    <by>john</by>
    <source>agent</source>
    </event>
    </events>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

     

     

    Event type="line" Parameters

     

    NameDescriptionType/Value
    timeThe time the event occurred.time
    textContent of the chat.alphanumeric
    textTypeThe type of message.plain | html
    byType of message that is sent.string. Can be one of info | agent | visitor
    sourceIndication of who sent the message.string. Can be one of system | agent | visitor
    systemMessageIdThe ID of the message. See System Messages below.numeric

     

    System Messages

    Messages that are initiated by the system. These messages are added with the <systemMessageId> element tag. The following table describes the available messages and IDs:

     

    IDEvent
    4Routing chat to an agent.
    22Ticket ID associated with chat.
    5Operator ends chat.
    3Operator accepts chat.
    2Site operators are currently busy.
    13Chat is transferred to an operator.
    15Chat is transferred to another skill group.
    6Chat is unexpectedly disconnected.
    23Chat requeued by system.

     

    Event type="state" Parameters

     

    NameDescriptionType/Value
    timeThe time the event occurred.time
    stateThe state of the chat.string. Can be one of waiting | chatting | ended

     

     

    Event type="collaboration" Parameters

     

    NameDescriptionType/Value
    commandA string command that controls the visitor side widget.string
    infoA list of name-value pairs that provide further details about the command and how it should be executed on the visitor's side.string. Nested element containing a list of name/value
    channelIDThe ID of the collaboration channel to which this event relates.string
    timeThe time the event occurred.time

     

    Adding Lines

    Use this request to add a line. The URI of the event that was added is returned in the Location header. If successful a 201 Created status code is returned.

    HTTP Method

    POST

    Formats

    xml, json

    Body Parameters

    You can use the following parameters in the XML body:

    NameDescriptionType/Value

    text

    Add a line of text to the visitor. This is a mandatory parameter.alphanumeric
    textTypeThe type of message and it's proper UI representation.plain | html

    Text Types

    It is possible to add different types of lines to the chat. When no text type is defined, it is assumed that a plain type was submitted.

    Changing the text type will be handled as follows:

     

    Name
    DescriptionType/Value
    plainThe default type when non used, the text will be displayed as provided.text
    html

    For passing HTML content from the agent to the chat session. The text must be escaped when provided and
    cannot include the following:

    • iframes
    • scripts
    • DOM actions
    • Links with  taget="_blank".
    text

     

    Request Body XML Example: Adding a Line

     

    <event type="line">
    <text>How can I help you?</text>
    </event>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

    Request Body JSON Example: Adding a Line

     

    {
        "event" :
           {
            "@type" : "line",
            "text" : "How can I help you?"
        }
    }

     

    Request Body XML Example: Adding a Line with  HTML

     

    <event  type="line">
    <text>&lt;i&gt;How  can I help you&lt;/i&gt;< /text>
    <textType>html</textType>
    </event>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    


    Note: Only one event can be added per POST event request.

     

    Ending a Chat

    Use this request to end a chat. If successful a 201 Created status code is returned.

    HTTP Method

    POST

    Formats

    xml, json

    Body Parameters

    You can use the following parameters in the XML body:

    NameDescriptionType/Value

    state

    End the chat with the visitor. This is a mandatory parameter.string

    Request Body XML Example: Ending a Chat

     

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

    Request Body JSON Example: Ending a Chat

     

    {
        "event" :
        {
            "@type" : "state",
            "state" : "ended"
        }
    }

     

    Note: The "ended" event ends the chat (and adds an "ended" event to the chat content), but it does NOT delete the chat session resource.

     

    Chat Information

    Description

    Retrieves information regarding the current status of the chat. The information section includes the agent's state, agent's name, start time of the chat, last update, visitor's ID, agent typing, visitor typing, and the visitor's name.

    URI

    This resource is accessed from Info link from the Chat Session URI GET request.

     

    Retrieving Chat Information

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <info>
    <link rel="self" href="https://dev.liveperson.net/hc/api/account
    /12345678/agentSession/901234567/chat/H3135644473379525-2249553296845149375K10071773/info"/>
    <link rel="visitor-name" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/
    901234567/chat/H3135644473379525-2249553296845149375K10071773/info/visitorName"/>
    <link rel="visitor-typing" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/
    901234567/chat/H3135644473379525-2249553296845149375K10071773/info/visitorTyping"/>
    <link rel="agent-typing" href="https://dev.liveperson.net/hc/api/account/12345678/agentSession/
    901234567/chat/H3135644473379525-2249553296845149375K10071773/info/agentTyping"/>
    <state>chatting</state>
    <chatSessionKey>H3135644473379525-2249553296845149375K10071773</chatSessionKey>
    <agentName>john</agentName>
    <agentId>4</agentId>
    <startTime>2009-08-05T16:55:11.359+03:00</startTime>
    <lastUpdate>2009-08-05T16:56:12.687+03:00</lastUpdate>
    <chatTimeout>40</chatTimeout>
    <visitorId>15203200049</visitorId>
    <agentTyping>not-typing</agentTyping>
    <visitorTyping>typing</visitorTyping>
    <visitorName>visitor</visitorName>
    <rtSessionId>10071773</rtSessionId>
    </info>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Elements in the Response
    NameDescriptionType/Value
    visitor-nameThe name that was set by the visitor.link relationship
    visitor-typingVisitor's typing status.link relationship
    agent-typingAgent's typing status.link relationship

    state

    The state of the chat session.string.
    Can be one of waiting | chatting | ended
    chatSessionKeyThe current chat session key.string
    agentNameThe name of the agent that is currently chatting with the visitor.alphanumeric
    agentIdThe ID number of the agent that is chatting with the visitor.numeric
    startTimeThe time the chat started.time
    lastUpdateThe last time that any request was sent to the chat session.time
    chatTimeoutThe time in seconds from the last update time,
    after which the chat times out and must be updated again before this timeout.
    numeric
    visitorIdThe ID number of the visitor that is chatting with the agent.numeric
    agentTypingIndicates if the agent is currently typing a message.string.
    Can be one of typing | not-typing
    visitorTypingIndicates if the visitor is currently typing a message.string.
    Can be one of typing | not-typing

    visitorName

    The name of the visitor that is chatting with the agent.
    If no name was given, the default value is visitor.
    alphanumeric
    rtSessionIdThe identifier of this session which is shared across other APIs. This identifier can be used to correlate the session through the various  API  types. This identifier can also be retrieved in Operator Alerts using the macro {LPINFO!rt-session-id}. In order to make it unique, concatenate the account id to this value.numeric

     

    Visitor Name

    Description

    Returns the name that was set by the visitor (default: visitor).

    URI

    This resource is accessed from visitor-name link from the Chat Information GET request.

     

    Retrieving the Visitor's Name

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <visitorName>visitor</visitorName>

     

    Elements in the Response
    NameDescriptionType/Value

    visitorName

    The name of the visitor.alphanumeric

     

    Agent Typing 

    Description

    Returns the agent's typing status or sets the agent's typing status. The agent's typing status can be one of typing, not-typing or unknown.

    URI

    This resource is accessed from agent-typing link from the Chat Information GET request.

     

    Retrieving the Agent's Typing Status

    The agent's typing status can be one of typing, not-typing or unknown. If successful a "201 Created" status code  response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <agentTyping>typing</agentTyping>

     

    Elements in the Response
    NameDescriptionType/Value

    agentTyping

    Indicates if the agent is currently typing a response.string. Can be one of typing | not-typing | unknown

     

    Setting the Agent Typing Status

    Sets the agent's typing status. The agent's typing status can be one of  typing, not-typing or unknown. If successful a "201 Created" status code response is returned.

    HTTP Method

    PUT *

     

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

    Formats

    xml, json

    Body Parameters

    You can use the following parameters in the XML body:

    NameDescriptionType/Value

    agentTyping

    Indicates if the agent is currently typing a response. This is a mandatory parameter.string. Can be one of typing | not-typing | unknown

    Request Body XML Example

     

    <agentTyping>typing</agentTyping>

     

     

    Request Body JSON Example

     

    {
    "agentTyping" : "typing"
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    


    Visitor Typing

    Description

    Returns visitor's typing status.

    URI

    This resource is accessed from visitor-typing link from the Chat Information GET request.

     

    Retrieving the Visitor's Typing Status

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

     

    <visitorTyping>typing</visitorTyping>

     

     

    Elements in the Response
    NameDescriptionType/Value

    visitorTyping

    Indicates if the visitor is currently typing a message. This is a mandatory parameter.string. Can be one of typing | not-typing

     

    Transfer  

    Description

    Used to retrieve the available skills to transfer a chat or to transfer a chat from an agent to a specific skill or agent.

    URI

    This resource is accessed from the transfer link in the Chat Session URI GET request.

     

    Retrieving the Available Skills

    Returns the available skills to transfer a chat. The list includes all skills that have at least one agent online and is not currently engaged in the chat. If successful a "200 OK" status code response is returned.

     

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <transfer>
      <skill>
        <id>2</id>
        <name>Sales</name>
      </skill>
      <skill>
        <id>3</id>
        <name>QA</name>
      </skill>
    </transfer>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    Elements in the Response
    NameDescriptionType/Value

    skill

    The available skills (id and name) to which the chat can be transferred.

    alphanumeric

     

    Transferring a Chat

    If successful a "200 OK" status code response is returned.

    HTTP Method

    POST

    Formats

    xml, json

    Body Parameters

    You need to pass either agent ID or skill ID to transfer the chat.

     

    Note: If both parameters are stated, the agent ID will be used, and the skill ID will be ignored.

     

    You can use the following parameters in the XML body:

    NameDescriptionType/Value

    skill

    The skill ID to which the chat will be transferred. numeric
    agentThe agent ID to which the chat will be transferred.numeric

    text

    Optional  message from the current agent. These lines are only available to an  agent to whom the chat was transferred and will not be seen by the  visitor.

    alphanumeric

     

    Request Body XML Example - Skill

     

    <transfer>
      <skill>
           <id>3</id>
      </skill>
           <text>This person needs your help.</text>
    </transfer>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

     

    Request Body XML Example - Agent

     

    <transfer>
       <agent>
          <id>2</id>
       </agent>
          <text>This person needs your help.</text>
    </transfer>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Request Body JSON Example - Skill

     

    {
        "transfer": {
             "skill":
                     {
                       "id": 2
                   }
               ,
         "text" : "I think this person need some help from you."
         }
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Request Body JSON Example - Agent

     

    {
          "transfer": {
                "agent":
                           {
                               "id": 6
                           }
                 ,
                 "text" : "I think this person need some help from you."
                 }
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Note: Placing more than one skill entry in the XML will mean that only the first skill will be selected.

     

    Agent Survey  

    Description

    Used to retrieve the Agent survey structure or to submit the survey data.

    URI

    This resource is accessed from the agent-survey link in the Chat Session URI GET request.

     

    Retrieving the Agent Survey Structure

    Returns the Agent survey structure. The survey structure is in XML that describes the questions of the survey as well as the logic of which questions are hidden. If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

     

    Response XML Example

     

    <survey id="41108">
    <header>Agent Survey Example</header>
    <questions>
      <question mandatory="true"order="0" logicId="1" id="16148804" validationType="alpha_numeric" type="Text Field">
       <label>Order Total for Internal Orders ONLY</label>
       <lastKnownValue>666</lastKnownValue>
      </question>
      <question mandatory="false" order="1" logicId="4" id="6416182" validationType="email" type="Text Field">
       <label>Email Address</label>
       <lastKnownValue></lastKnownValue>
      </question>
      <question mandatory="true" order="2" logicId="5" id="26386685" validationType="alpha_numeric" type="Radio Button">
       <label>Was the issue the customer contacted you about resolved during this engagement?</label>
       <entry>
        <value>Yes, the issue was resolved</value>
        <logic><showLogicId>6</showLogicId></logic>
       </entry>
       <entry>
        <value>No, the issue was not resolved</value>
       </entry>
      </question>
      <question mandatory="false" order="3" logicId="6" id="4291707" validationType="alpha_numeric" type="Dropdown Box">
       <label>On which Product?</label>
       <entry>
        <value>Telephone</value>
       </entry>
       <entry>
        <value>Fax Machine</value>
       </entry>
       <entry>
        <value>Scanner</value>
       </entry>
      </question>
    </questions>
    </survey>

     


    Elements in the Response
    NameDescriptionType/Value
    headerThe survey's displayed header.alphanumeric
    questionContains all the question data.
    mandatoryWhether this question is mandatory in the survey.true/false
    orderThe order of the question in the survey.
    logicIdUnique ID of this question for logic. (See Logic section below).
    idUnique ID of this question.
    typeIdentifies the question answer type.Dropdown Box
    Checkbox
    Radio Button (side by side)
    Radio Button
    validationTypeIdentifies the question validation type.

    alphanumeric

    numeric

    email
    labelThe displayed questinon label.alphanumeric
    lastKnownValueAn old value from an earlier session (for non-selection questions). You should show it to the user as the default value for this question.alphanumeric
    entryA selection question item.
    checkedIndicates whether this item should be selected when you show this question to the user.true/false
    value (entry)The label of the selection item.alphanumeric
    logic

    Exists if this question has any logic. Logic allows specified questions in surveys to be hidden or displayed to visitors based on the answers given to previous questions in a survey.

     

    In the examples above, the question with attribute logicID 5 will be displayed when the 'CATS' answer is selected via the drop-down box in question with id="12786273". This behavior is set by the "showLogicId" element.

     

    Question Logic is particularly useful when the user might get a long list of options that would not be as user-friendly in a single list; or you wish to hide conditional or required questions which might not be relevant for all users completing the survey.

    showLogicIdThe ID of the question to be displayed if this item is selectednumeric

     

    Submitting Survey Data

    If successful a "200 OK" status code response is returned.

    HTTP Method

    PUT *

     

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

    Formats

    xml, json

    Body Parameters

    You can use the following parameters in the XML body:

    NameDescriptionType/Value

    question

    Contains answer elements for the survey's question with this ID.

    answer

    Given answer for the container question. If the question is a  multiselection type (checkbox) it can contain more than one answer.alphanumeric

     

    Request Body Example

     

    <survey id="40292">
    <question id="25245945">
    <answer>answer1</answer>
    </question>
    <question id="12817515">
    <answer>answer2</answer>
    </question>
    </survey>

     

     

    Collaboration Channels

    Description

    Creates a Collaboration Channel with a specified channel type. Returns a location to the newly created channel.

     

    Collaboration Channels are used for communicating with widgets that are deployed on the visitor's side. The communication is done through collaboration events. The Agent API can be used for opening Collaboration Channels and for sending Collaboration Events to those channels. For example, if a YouTube widget is deployed on the visitor's side, then the agent may want to open a collaboration channel against this widget, and then send collaboration events to this channel so that the widget would display the required YouTube content to the visitor. The channel type maps events sent by this channel to the corresponding widget on the visitor's side. An example of a channel type is "youTubeVideo". Several channels can be opened with the same channel Type. The result would be that several instances (sessions) of this widget would be created on the visitor's side and each would communicate with the agent's side through their own separate channel.

     

    Note: The names of the collaboration channels and the content of the collaboration events are based on a convention between the specific widget implementation and the agent's side. Normally, the same party who develops the widget would provide the agent control logic for opening collaboration channels and sending collaboration events for controlling that widget.

     

    URI

    This resource is accessed from the collaboration-channels link in the Chat Session URI GET request.

     

    Creating a Collaboration Channel

    If successful a "201 Created" status code response is returned.

    HTTP Method

    POST

    Formats

    xml,  json

    Body Parameters

    You can use the following parameters in the XML body:

    NameDescriptionType/Value
    channelTypeThe name of the channel type would map events sent by this channel to the corresponding widget on the visitor's side.String

     

    Request Body JSON Example

     

    {
    "channelType" :
            {
             "collaborationChannelType" : "youtubeVideo"
            }
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    


    Collaboration Channel URI

    Description

    Returns a response with links to the available resources for a particular collaboration channel.

    URI

    This resource is accessed from the location obtained as result of the Collaboration Channels POST request.

    HTTP Method

    GET

    Formats

    xml, json

     

    JSON Response Example

     

    {
        "collaborationChannel":
       {
          "link":
          {
              "href":"https://dev.liveperson.net/hc/api/account/31773795/agentSession/
    60321033/chat/H4670318608921909989-6655101289844072949K8407009/collaborationChannels/1/events",
              "rel":"events"
          }
       }
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

    Element in the Response
    NameDescriptionType/Value

    events

    Access to the events of the collaboration channel.

    link relationship

     

    Collaboration Channel URI Events

    Description

    Sends and retrieves Collaboration Events for a specific Collaboration Channel. A Collaboration Event is a structure that describes a message from the agent's side to a specific widget on the visitor's side, or from the visitor's side to the agent's side. Each Event contains a command, such as "start", and an info object, constructed of a list of name-value pairs. Both the command and the name-value pairs that follow it are a part of the convention between the agent's side and the widget. In the "youTubeVideo" example, the command that the agent sends would be "start" and the info elements would contain the title and the URL of the video shown.

    URI

    This resource is accessed from the events link in the Collaboration Channel URI GET request.

     

    Sending a Collaboration Event

    Use this method to send Collaboration Events to the Visitor's side.

    HTTP Method

    POST

    Formats

    xml, json

    Parameters

    NameDescriptionType/Value

    command

    A string command that controls the visitor side widget.string
    infoA list of name-value pairs that provide further details about the command and how it should be executed on the visitor's side.string. Nested element containing a list of name/value

     

    Request Body JSON Example

     

    {
        "event" :
           {
            "command" : "show",
             "info":[{"@name":"youtubeID","$":"h1DcGUwRe8g"},{"@name":"title","$":"World  Music"}]
        }
    }

     

    Receiving Collaboration Events

    Use this method to obtain a list of all collaboration events that were sent for this channel. This includes events sent by the agent and visitor.

    HTTP Method

    GET

    Formats

    xml, json

     

    JSON Response Example

     

    {
       "collabEvents":
       {
          "event":
          [
              {
                "id":0,
                "type":"collaboration",
                 "time":"2012-04-18T19:21:23.504+03:00",
                 "command":"show",
                "channelID":"1",
                 "info":
                [
                   {
                       "name":"title",
                      "$":"World Music"
                    },
                   {
                       "name":"youtubeID",
                      "$":"h1DcGUwRe8g"
                    }
                ],
                "source":"agent"
             },
              {
                "id":1,
                "type":"collaboration",
                 "time":"2012-04-18T19:21:26.738+03:00",
                 "command":"stateChange",
                "channelID":"1",
                 "info":
                [
                   {
                       "name":"state",
                      "$":"ready"
                    }
                ],
                "source":"visitor"
             }
          ]
       }
    }

    Visit Session URI

    Description

    Obtains resources related to the visit. The URI is referred to as the visit-session-uri in the rest of the document.

    URI

    This resource is accessed from the visit-id link in response to the Chat Session URI GET request.

     

    Retrieving All Resources for a Visit

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

     

     

    Response XML Example

     

    <visitId>
    <link rel="self" href="http://api.liveperson.net/api/account/12345678/agentSession/7890123/visits/visit/
    H8831383048526229002K55555"/>
      <link rel="info" href="http://api.liveperson.net/api/account/12345678/agentSession/7890123/visits/visit/
    H8831383048526229002K55555/info"/>
      <link rel="pages" href="http://api.liveperson.net/api/account/12345678/agentSession/7890123/visits/visit/
    H8831383048526229002K55555/pages"/>
      <link rel="custom-variables" href="http://api.liveperson.net/api/account/12345678/agentSession/7890123/visits/visit/
    H8831383048526229002K55555/customVariables"/>
    </visitId>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

     

     

    Elements in the Response
    NameDescriptionType/Value

    info

    Data and links for information on the visit.link relationship

    pages

    Pages visited related to a specific session.link relationship
    custom-variablesCustom variables for the visit.link relationship

     

    Visit Session Pages

    Description

    This resource returns pages visited related to the specified session (visit-session-uri). If no data is available for an attribute/element then it will be omitted. In addition to a list of pages returned the result contains a link to obtain the following pages on the list (if applicable).

    URI

    This resource is accessed from the pages link in response to the Visit Session URI GET request.

     

    Retrieving Visited Pages

    If successful a "200 OK" status code response is returned.

    HTTP Method

    GET

    Formats

    xml, json

    Query Parameter

    ParameterDescriptionType/Value

    from

    The index of the first page that is shown in the response.

    numeric

     

    Response XML Example

     

    <pages>
        <link rel="self" href="https://dev.liveperson.net/api/account/40009003/agentSession/88276279/
    visits/visit/H5549000448519537492K8807/pages"/>
        <link rel="next" href="https://dev.liveperson.net/api/account/40009003/agentSession/88276279/
    visits/visit/H5549000448519537492K8807/pages?from=2"/>
        <page index="0" id="2600511327" isCurrent="false">
            <link rel="self" href="https://dev.liveperson.net/api/account/40009003/agentSession/88276279/
    visits/visit/H5549000448519537492K8807/pages0"/>
            <link rel="page-viewer" href="https://dev.liveperson.net/hc/web/repcobrowse/?site=40009003&
    repid=8827627927865118829173667228&amp;visid=8807&amp;siteContainer=STANDALONE&amp;
    url=http%3a%2f%2fstore.apple.com%2fcreateSite%2ejsp%3fsiteid%3d40009003%
    26server%3ddev.liveperson.net&amp;pageIndex=0"/>
            <time>2011-02-28T17:41:58.303+02:00</time>
            <title>Visit Site 40009003</title>
            <url>http://store.apple.com/createSite.jsp?siteid=40009003&server=dev.liveperson.net</url>
            <referrer>http://store.apple.com/createSite.jsp</referrer>
        </page>
        <page index="1" id="9328199461" isCurrent="false">
            <link rel="self" href="https://dev.liveperson.net/api/account/40009003/agentSession/88276279/visits/visit/
    H5549000448519537492K8807/pages1"/>
            <link rel="page-viewer" href="https://dev.liveperson.net/hc/web/repcobrowse/?site=40009003&
    repid=8827627927865118829173667228&amp;visid=8807&amp;siteContainer=STANDALONE&amp;
    url=http%3a%2f%2fstore.apple.com%2fcreateSite%2ejsp%3fsiteid%3d40009003%
    26server%3ddev.liveperson.net&amp;pageIndex=1"/>
            <time>2011-02-28T17:42:00.230+02:00</time>
            <title>Visit Site 40009003</title>
            <url>http://store.apple.com/createSite.jsp?siteid=40009003&server=dev.liveperson.net</url>
            <referrer>http://store.apple.com/createSite.jsp</referrer>
        </page>
        <page index="2" id="7635064744" isCurrent="true">
            <link rel="self" href="https://dev.liveperson.net/api/account/40009003/agentSession/88276279/visits/visit/
    H5549000448519537492K8807/pages2"/>
            <link rel="page-viewer" href="https://dev.liveperson.net/hc/web/repcobrowse/?site=40009003&repid=8827627927865118829173667228&visid=8807&
    siteContainer=STANDALONE&amp;
    url=http%3a%2f%2fstore.apple.com%2fcreateSite%2ejsp%3fsiteid%3d40009003%
    26server%3ddev.liveperson.net&amp;pageIndex=2"/>
            <time>2011-02-28T17:42:01.842+02:00</time>
            <title>Visit Site 40009003</title>
            <url>http://store.apple.com/createSite.jsp?siteid=40009003&server=dev.liveperson.net</url>
            <referrer>http://store.apple.com/createSite.jsp</referrer>
        </page>
    </pages>

     

    Elements in the Response
    NameDescriptionType/Value
    nextThe method for polling additional pages. This will retrieve pages added after your last poll.link relationship
    <page>The actual page information. See Visit Session Page Index.-

     

    Visit Session Page Index

    Description

    The resource retrieves the information for a specific page.

    URI

    This resource is accessed from a specific page ("self") in response to the Visit Session Pages GET request.

     

    Retrieving Specific Page Information

    HTTP Method

    GET

    Formats

    xml, json

     

    Response XML Example

     

    <page isCurrent="true" id="0" index="0">
     <link rel="self" href="http://dev.liveperson.net/api/account/12345678/agentSession/7890123
    /visits/visit/H8831383048526229002K55555/pages/0"/>
    <link rel="page-viewer" href="http://dev.liveperson.net/hc/web/repcobrowse/?site=12345678&
    repid=21358337423725932231800700376&visid=19601&siteContainer=STANDALONE&url
    =http://store.apple.com/us/browse/home/shop_iphone/family/iphone?mco=OTY2ODA2OQ?
    siteid=12345678&server=miko&pageIndex=0"/>
    <title>iPhone 4 & iPhone 3GS</title>
     <url>http://store.apple.com/us/browse/home/shop_iphone/family/iphone?mco=OTY2ODA2OQ</url>
    <time>1234567</time>
     <referrer>http://store.apple.com/us</referrer>
    </page>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    


    Elements in the Response
    NameDescriptionType/Value
    isCurrentSpecifies whether the page is currently viewed by the visitor.boolean. Can be one of true | false
    idThe ID of the page.numeric
    indexThe index of the page in the visitor history.numeric
    page-viewerA URI for the agent application to display the page that the visitor sees.link relationship
    titleThe page title.alphanumeric
    urlThe URL for the page as seen by the visitor.link
    timeThe time the visitor visited the page.date time
    referrerThe link that led to this page.link

     

    Visit Session Details

    Description

    Retrieves all the details of the visit.

    URI

    This resource is accessed from the info link in response to the Visit Session URI GET request.

     

    Retrieving the Details of a Visit

    HTTP Method

    GET

    Formats

    xml, json

     

     

    Response XML Example

     

    <visitInfo>
    <link rel="self" href="https://www.liveperson.com/api/account/
    1234567/agentSession/830570067/visits/visit/H2331666100861651613K31104/info"/>
    <visitorId>14701590006</visitorId>
    <isInCurrentChat>true</isInCurrentChat>
      <sessionInfo>
       <info name="sso">false</info>
       <info name="ip">128.148.15.7</info>
       <info name="browser">MSIE 7.0</info>
       <info name="state">IN_CHAT</info>
       <info name="skill">Sport</info>
       <info name="current Page">www.liveperson.com</info>
       <info name="title">Visit Site 42723835</info>
       <info name="serviceQueue" id="1">API Q</info>
       <info name="os">Windows Server 2003 (Windows NT 5.2)</info>
      </sessionInfo>
      <visitorInfo>
       <info name="geoOrg">LivePerson</info>
       <info name="geoLat">41.826706</info>
       <info name="geoIP">128.148.15.7</info>
       <info name="geoTimeZone">Jerusalem / +0200</info>
       <info name="geoReg">Asia</info>
       <info name="geoConType">Cable/DSL</info>
       <info name="geoLong">-71.3977</info>
       <info name="geoPost">02912</info>
       <info name="geoCountry">Israel</info>
       <info name="geoISP">Internet Services</info>
       <info name="geoCity">Tel Aviv</info>
       <info name="contactID">128.148.15.7</info>
      </visitorInfo>
      <time>
       <info name="visitStartTime">2010-12-14T16:54:17.536+02:00</info>
      </time></visitInfo>
    
    
    
    
    
    
    
    
    

     

    Response JSON Example

     

    {
    "visitInfo":
    {
    "link"{
    "@rel" : "self",
    "@href" : "https://www.liveperson.com/api/account/1234567/
    agentSession/789012345/visits/visit/H2331666100861651613K31104/info"
    }
    "isInCurrentChat": true,
    "visitorId":14701210002,
    "sessionInfo":
    {
       "info":
       [
        {
         "@name":"sso",
         "$":"false"
        },
        {
         "@name":"ip",
         "$":"128.148.15.7"
        },
        {
         "@name":"browser",
         "$":"MSIE 7.0"
        },
        {
         "@name":"state",
         "$":"IN_CHAT"
        },
        {
         "@name":"skill",
         "$":"Sport"
        },
        {
         "@name":"currentPage",
         "$":"www.liveperson.com"
        },
        {
         "@name":"title",
         "$":"Visit Site 42723835"
        },
        {
         "@name":"serviceQueue",
         "$":"API Q"
        },
        {
         "@name":"os",
         "$":"Windows Server 2003 (Windows NT 5.2)"
        }
       ]
    },
    "visitorInfo":
    {
          "info":
          [
       {
           "@name":"geoOrg",
           "$":"LivePerson"
       },
       {
           "@name":"geoLat",
           "$":"39.996796"
       },
       {
           "@name":"geoIP",
           "$":"65.43.29.59"
       },
       {
           "@name":"geoTimeZone",
           "$":"Jerusalem / +0200"
       },
       {
           "@name":"geoReg",
           "$":"Asia"
       },
       {
           "@name":"geoConType",
           "$":"Cable/DSL"
       },
       {
           "@name":"geoLong",
           "$":"-82.9883"
       },
       {
           "@name":"geoCountry",
           "$":"Israel"
       },
       {
           "@name":"geoISP",
           "$":"Internet Services"
       },
         {
           "@name":"geoCity",
           "$":"Tel Aviv"
        },
    {
           "@name":"contactID",
           "$":"65.43.29.59"
       },   ]
    },
    "time":
    {
         "info":
         [
       {
           "@name":"visitStartTime",
           $":"2010-12-14T16:26:02.062+02:00"
       },
          ]
    },
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    


    Elements in the Response
    NameDescriptionType/Value
    isInCurrentChatIndicates whether or not the agent, initiating the request, is the agent chatting or assigned to the session. This is a mandatory parameter.boolean. Can be one of true | false
    visitorIdThe visitor's identifier. This is a mandatory parameter.numeric

    sessionInfo

    ssoIndicates if the connection is SSO or not. This is a mandatory parameter.boolean. Can be one of true | false
    ipThe visitor's IP address. This is a mandatory parameter.alphanumeric (IP)
    browserThe type of browser the visitor is using. This is a mandatory parameter.alphanumeric
    stateThe visitor's status. This is a mandatory parameter.string. Can be one of WAITING_FOR_CHAT | IN_CHAT | AFTER_CHAT
    skillThe assigned skill (if the data exists).alphanumeric
    currentPageThe current page if it exists.link
    titleThe page title.alphanumeric
    serviceQueues

    The assigned service queue as it was assigned to the visitor. It includes an ID.

    Note: A rule should be defined in advance with the following:

    • Rule Type (context): While visitor is browsing site.
    • Action: Routing.
    • Assign to ServiceQueue.
    alphanumeric
    skillRoomThe skill room will display the skill, if it’s a valid skill (exists). It includes an ID.alphanumeric
    osThe visitor operating system.alphanumeric
    visitorInfo
    geoLatLatitude.numeric
    geoIPIP.alphanumeric (IP)
    geoTimeZoneTime Zone.alphanumeric
    geoConTypeConnection Type.alphanumeric
    geoLongLongitude.numeric
    geoCityVisitor City.alphanumeric
    geoOrgOrganization.alphanumeric
    geoRegWorld Regionalphanumeric
    geoPostPostal Code.alphanumeric
    geoISPISP.alphanumeric (IP)
    geoCountryCountry.alphanumeric
    contactIDThe ID for the visitor.* Empty
    * IP
    * If survey exits, the survey identifier
    * the name entered in the chat window.
    time
    visitStartTimeThe visitor's start time since they entered the site. This is a mandatory parameter.date time
    visitWaitTimeThe visitor's wait time since clicked to chat. state = WAITING_FOR_CHAT.date time

     

     

    Visit Session Custom Variables

    Description

    Retrieves the custom variables for the visit.

     

    Notes:

    • Many custom variables per request.
    • Variable Scope: Session, Page or Visitor.

     

    URI

    This resource is accessed from the custom-variables link in response to the Visit Session URI GET request. If successful a "200 OK" status code response is returned.

     

    Retrieving Custom Variables

    HTTP Method

    GET

    Formats

    xml, json

    Response XML Example

     

    <customVariables>
        <link rel="self" href="https://dev.liveperson.net/api/account/1234567/agentSession/78901234/visits/
    visit/H6321277421762156610K8418109/customVariables"/>
        <customVariable source="rule engine" scope="visitor">
            <name>VisitVar</name>
            <time>2010-12-29T19:15:58.875+02:00</time>
            <displayName>VisitVar</displayName>
            <value>3</value>
        </customVariable>
        <customVariable source="Visitor Single SignOn" scope="session">
            <name>SessionVar</name>
            <time>2010-12-29T19:15:58.875+02:00</time>
            <displayName>SessionVar</displayName>
            <value>2</value>
        </customVariable>
        <customVariable source="xxx" scope="page">
           <link rel="pageUrl" href="https://dev.liveperson.net/api/account/1234567/agentSession/78901234/visits/
    visit/H6321277421762156610K8418109/pages/1"/>
            <name>pageVar</name>
            <time>2010-12-29T19:15:58.875+02:00</time>
            <displayName>pageVar</displayName>
            <value>1</value>
               </customVariable>
    </customVariables>
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    JSON Example

     

    {
      "customVariables" : {
        "link" : {
          "@rel" : "self",
          "@href" : "https://dev.liveperson.net/api/account/1234567/agentSession/890123456/visits/visit/
    H6321277421762156610K8418109/customVariables"
        },
        "customVariable" : [ {
          "@source" : "Visitor Single SignOn",
          "@scope" : "visitor",
          "name" : "VisitVar",
          "time" : "2010-12-29T19:15:58.875+02:00",
          "displayName" : "VisitVar",
          "value" : "3"
        }, {
          "@source" : "xxx",
          "@scope" : "session",
          "name" : "SessionVar",
          "time" : "2010-12-29T19:15:58.875+02:00",
          "displayName" : "SessionVar",
          "value" : "2"
        }, {
          "@source" : "rule engine",
          "@scope" : "page",
          "link" : {
            "@rel" : "pageUrl",
            "@href" : "https://dev.liveperson.net/api/account/1234567/agentSession/890123456/visits/visit/
    H6321277421762156610K8418109/pages/1"
          }
          "name" : "pageVar",
          "time" : "2010-12-29T19:15:58.875+02:00",
          "displayName" : "pageVar",
          "value" : "1",
             } ]
      }
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Elements in the Response
    NameDescriptionType/Value
    nameThe name of the custom variable.alphanumeric
    scopeThe scope of the customer variable.string. Can be one of visitor | session | page
    source

    Origin of where the custom variable was created. It can be used to group custom variables. It may include a number of different values. The significant values are:

    • Visitor Single SignOn: Custom variables for an authenticated visitor.
    • Visitor Promotion Campaign: Custom variables for a promotion  campaign that is relevant for this visitor. The promotion campaign  options include the following: Google Analytics, LP (LivePerson), CPC (cost-per-click),  Organic, Referral, and Direct (if no other option).
    string. Visitor Single SignOn |Visitor Promotion Campaign
    timeThe time the custom variable occurred.time
    displayNameThe display name of the custom variable.alphanumeric
    valueThe value of the custom variable.alphanumeric
    pageUrlURI to access the page resources that are associated with this custom variable. This item is only available for page scope custom variables.link relationship

    Comments

    Delete Document

    Are you sure you want to delete this document?