Help Center/ Cognitive Engagement Center/ API Reference/ Agent Workbench Interface Reference/ Agent Control/ Agent Operation Interfaces: onlineagent/ Signing In
Updated on 2023-09-27 GMT+08:00
View PDF
Share

Signing In

Prerequisites

None

Description

This interface is used by an agent to sign in.

After an agent signs in, the poll interface is invoked immediately to poll events. If no event occurs within 2 minutes, the agent is signed out.

For an agent:

  • If the sign-out interface does not respond, the sign-in interface cannot be invoked.
  • If the sign-in interface does not respond, the sign-out interface cannot be invoked.

Interface Method

The request method must be set to PUT. This interface supports only the PUT method.

URI

https://ip:port/agentgateway/resource/onlineagent/{agentid}

In the URL, ip indicates the IP address of the CC-Gateway server, and port indicates the HTTPS port number of the CC-Gateway server.

Table 1 Parameter in the URI

No.

Parameter

Data Type

Mandatory (Yes/No)

Description

1

agentid

String

Yes

Agent ID. The value ranges from 101 to 59999.

Method Name in Logs

login

Request Description

  • Message header
    Table 2 Parameter in the request message header

    No.

    Parameter

    Value Type

    Mandatory (Yes/No)

    Description

    1

    Content-Type

    String

    Yes

    Coding mode of the message body. The default value is application/json; charset=UTF-8.
  • Message body
    Table 3 Parameters in the message body

    No.

    Parameter

    Value Type

    Mandatory (Yes/No)

    Description

    1

    password

    String

    Yes

    Password of an employee ID on the CTI platform. The value can contain a maximum of 32 characters.

    2

    phonenum

    String

    Yes

    Softphone number. The value can contain a maximum of 24 characters.

    3

    autoanswer

    Boolean

    No

    Whether to enable automatic answering. The default value is true.

    4

    autoenteridle

    Boolean

    No

    Whether to automatically enter the idle state after a call ends. The default value is true.

    5

    releasephone

    Boolean

    No

    Whether an agent enters the non-always-off-hook state (the phone is hung up after the call ends) after the agent hangs up. The default value is true.

    6

    agenttype

    Integer

    No

    Type of the agent who signs in. The default value is 4.

    • 4: PC+phone agent
    • 11: PC+phone video agent

    7

    status

    Integer

    No

    Status after an agent signs in. The default value is 4.

    • 3: busy
    • 4: idle
    • 5: wrap-up

    8

    ip

    String

    No

    Agent IP address. The default value is 127.0.0.1 and can contain a maximum of 15 characters. IPv6 addresses are not supported.

    9

    entryIp

    String

    No

    IP address of the gateway to which the agent client application connects.

    10

    phonelinkage

    Boolean

    No

    Whether to enable phone linkage, including connection and hard phone linkage control. Currently, only eSpace 7910 phones on the CC network are supported.

    The default value is false.

    11

    checkInWebm

    Boolean

    No

    Whether to sign in to the WebM media server.

    The default value is true.

    12

    checkInMailm

    Boolean

    No

    Whether to sign in to the MailM server.

    The default value is false.

    13

    vcPhoneNumber

    String

    No

    VC number. The value contains a maximum of 24 characters.

    14

    listenStatus

    Boolean

    No

    Whether an inspector listens to the sign-in and sign-out operations of an agent.

    The default value is false.

    15

    callBackUri

    String

    No

    Event callback address.

    For details about the interface definition, see Calling Back Pushed Events.

    16

    serviceToken

    String

    No

    Authentication code. The value contains a maximum of 50 characters and cannot contain special characters.

    17

    serviceworkid

    String

    No

    Business employee ID. The value can contain a maximum of 30 characters.

    If both callBackUri and serviceToken are transferred, the event push mode is used. Otherwise, the event polling mode is used.

Response Description

Table 4 Response header parameters

No.

Parameter

Value Type

Mandatory (Yes/No)

Description

1

Content-Type

String

Yes

Coding mode of the message body. The default value is application/json; charset=UTF-8.

2

Guid

String

Yes

GUID returned by the sign-in interface during static authentication (AUTHMODE is set to 1) or GUID returned by the polling event query interface during dynamic authentication (AUTHMODE is set to 2).

3

Set-GUID

String

Yes

An example value is JSESSIONID=279fe2*****************0f5.AgentGateway0. In the value, 279fe2*****************0f5.AgentGateway0 is the GUID.
Table 5 Parameters in the message body

No.

Parameter

Value Type

Description

1

message

String

Description.

2

retcode

String

Error code. The options are as follows:

0: success

Other values: failure

3

result

Map

Object in the returned result after a successful query.

For details about the parameters of this object, see Table 6.
Table 6 Parameter description of result

No.

Parameter

Value Type

Description

3.1

vdnid

String

VDN ID.

3.2

workno

String

Agent ID.

3.3

mediatype

String

Whether the agent successfully signs in to the media server of a specific type. T indicates success and F indicates failure. The three characters indicate CTI Server, WebM, and MailM, respectively. For example, TTF indicates that the agent successfully signs in to the CTI Server and WebM but fails to sign in to the MailM.

The voice business can be processed only after the agent successfully signs in to the CTI Server. The text chat business can be processed only after the agent successfully signs in to the WebM. Currently, the agent cannot sign in to the MailM.

3.4

loginTime

String

Sign-in time. The value is a timestamp.

3.5

isForceChange

String

Whether to forcibly change the password. If the parameter is set to true, the agent must change the password after sign-in. To change the password, invoke the interface described in Changing the Password (Extended).

NOTE:

If the value is true but the agent does not change the password, the agent cannot make calls.

3.6

serverName

String

Cluster name of the CC-Gateway to which an agent signs in.

3.7

timeRemaining

String

Remaining password validity period.

An empty string indicates that the agent password never expires. The value ranges from 0 to 180 days.

Triggered Event

If the status parameter is set to 3 (busy) during sign-in, the following events are triggered:

  • AgentOther_InService
  • AgentState_Ready
  • AgentState_SetNotReady_Success

If the status parameter is set to 4 (idle) during sign-in, the following events are triggered:

  • AgentOther_InService
  • AgentState_Ready

If the status parameter is set to 5 (wrap-up) during sign-in, the following events are triggered:

  • AgentOther_InService
  • AgentState_Ready
  • AgentState_Work

If phone linkage is enabled during sign-in, the following event is triggered:

  • AgentEvent_linkageCapability

Error Code

  • 100-001
  • 100-002
  • 100-003
  • 100-004
  • 100-007
  • 100-012
  • 100-015
  • 100-016
  • 110-016
  • 999-001

Example

  • Message header 
    Content-Type:application/json; charset=UTF-8
  • Request parameter 
    {
    "password": "",
    "phonenum": "40038",
    "status": "4",
    "releasephone": "false",
    "agenttype": "4"
}
  • Response parameter 
    {
    "message": "",
    "retcode": "0",
    "result": {
        "vdnid": 1,
        "workno": "291",
        "mediatype": "TTF",
        "loginTime": "1471585949806",
        "isForceChange": "false",
        "serverName": "AgentGateway",
        "timeRemaining": "9"
    }
}