NAME
Kernel::System::Chat – chat engine backend
DESCRIPTION
Chat engine backend
PUBLIC INTERFACE
new()
create an object. Do not use it directly, instead use:
use Kernel::System::ObjectManager;
local $Kernel::OM = Kernel::System::ObjectManager->new();
my $ChatObject = $Kernel::OM->Get('Kernel::System::Chat');ChatAdd()
add a new chat (request).
my $ChatID = $ChatObject->ChatAdd(
Status => 'request', # request or active
RequesterName => 'Some Name',
RequesterType => 'User', # 'User', 'Customer' or 'Public'
TargetType => 'Customer', # 'User' or 'Customer'
RequesterID => 3,
ChannelID => 3 , # required
TicketID => 3, # not required, related TicketID
);returns my $ChatID = 1;
events: ChatAdd – a new chat request is added
ChatUpdate()
update a chat.
my $Success = $ChatObject->ChatUpdate(
ChatID => $ChatID,
Status => 'request', # request, active or closed
# status closed is used for deprecated chats
# chats with status closed will be removed from database by OTRS Daemon
);
returns
my $Success = 1;events: ChatUpdate – emitted when chat was updated (any update) ChatRequestUpdate – emitted when chat was updated, but previous state was 'request'
ChatGet()
Get a chat's data.
my %Chat = $ChatObject->ChatGet(
ChatID => $ID,
);Result:
%Chat = (
ChatID => '1',
Status => 'active',
RequesterID => 'jdoe',
RequesterName => 'John Doe,
RequesterType => 'Customer',
TargetType => 'Agent',
CreateTime => '2015-07-03 13:25:41',
ChatChannelID => 1,
TicketID => 0,
);ChatList()
List all or specific chats.
my @AllChats = $ChatObject->ChatList();
my @Chats = $ChatObject->ChatList(
Status => 'request', # optional, request or active
RequesterType => 'Customer', # optional
# or
RequesterType => ['Customer'] # optional
TargetType => 'User', # optional
ChannelIDs => [3,5,7], # optional
Outdated => 1, # optional, list chats that passed the decay time
# Filter chats based on chat_participants (needs at least ChatterID and ChatterType)
ChatterID => $ChatterID, # Optional, typically this would be a UserID
ChatterType => $ChatterType, # Optional, typically this would be 'User', 'Customer' or 'Public'
ChatterActive => 0 or 1, # Optional, if specified looks for confirmed or unconfirmed chat participants
MaskAgentName => 1, # optional, will use the appropriate config setting to display a generic agent name instead of the real one
InvitationPending => 1, # optional, in combination with ChatterID, lists chats with a pending invitation
);Returns:
@Chats = [
{
'ChatID' => '168',
'CreateTime' => '2015-07-06 06:49:47',
'Status' => 'active',
'Channel' => 'Channel 1',
'RequesterType' => 'Customer',
'Order' => 0,
'RequesterID' => 'jdoe',
'RequesterName' => 'John Doe',
'TargetType' => 'User',
'Invitation' => '0',
'ChannelID' => '72',
'TicketID' => '0',
},
{
'ChatID' => '171',
'CreateTime' => '2015-07-07 13:40:52',
'Status' => 'active',
'Channel' => 'Channel 2',
'RequesterType' => 'Customer',
'Order' => 0,
'RequesterID' => 'jdoe',
'RequesterName' => 'John Doe',
'TargetType' => 'User',
'Invitation' => '0',
'ChannelID' => '72',
'TicketID' => '0'
}
];CustomerIDGet()
Get CustomerID for given Chat.
my $CustomerUserID = $ChatObject->CustomerIDGet(
Chat => \%Chat,
);Result:
$CustomerUserID = "jdoe";ChatPermissionLevelGet()
Get user's permission level for particular chat. my $PermissionLevel = $ChatObject->ChatPermissionLevelGet( ChatID => 2, UserID => 1, ); $PermissionLevel = "Participant";
ChatDelete()
delete chat. my $Success = $ChatObject->ChatDelete( ChatID => $ID, ); returns $Success = 1;
ChatCleanup()
removes chats
my $Success = $ChatObject->ChatCleanup(
Cleanup => 'Old' # if Cleanup is old, old chats will be removed
# else closed chats will be removed
);ChatParticipantAdd()
grants a chatter access to a chat.
my $Success = $ChatObject->ChatParticipantAdd(
ChatID => $ChatID,
ChatterID => $ChatterID, # Typically this would be a UserID
ChatterName => 'John Doe', # Visible name to display in chats
ChatterType => $ChatterType, # Typically this would be 'User' or 'Customer'
ChatterActive => 1, # 0 or 1, indicates if chat request was accepted
PermissionLevel => 'Owner', # (required for agents) Permissions in selected chat - 'Owner', 'Observer', 'Participant'
Invitation => 1, # user is invited to chat
Monitoring => 2 # 0,1 or 2. 0 - do not monitor this chat
1 - monitor Customer activity in the chat
2 - monitor all activity in the chat
);events: ChatRequestUser – fired when ChatterType is User and ChatterActive is 0 (signal chat request) ChatRequestCustomer – fired when ChatterType is Customer and ChatterActive is 0 (signal chat request)
ChatParticipantUpdate()
confirms a chat participant.
my $Success = $ChatObject->ChatParticipantUpdate(
ChatID => $ChatID,
ChatterID => $ChatterID, # Typically this would be a UserID
ChatterType => $ChatterType, # Typically this would be 'User' or 'Customer'
ChatterActive => $ChatterActive # -1, 0 or 1 (left/declined / inactive / active)
Monitoring => 1 # 0 , 1 or 2 , not required
PermissionLevel => 'Participant'
);AgentPermissionsUpdate()
changes agent permissions to ( Participant / Observer )
my $Success = $ChatObject->AgentPermissionsUpdate(
ChatID => $ChatID,
ChatterID => $ChatterID, # Typically this would be a UserID
PermissionLevel => $PermissionLevel, # Participant or Observer
ChatterActive => $ChatterActive, # 0 or 1
);ContributorsCount()
Return number of currently involved contributing agents. my $Count = $ChatObject->ContributorsCount( ChatID => $ChatID, ); Result: $Count = 4;
CustomerPresent()
Returns 1 if there is active Customer in the chat Works the same for the public users my $CustomerPresent = $ChatObject->CustomerPresent( ChatID => $ChatID, Active => 1, # optional, include only active customers ); Result: $CustomerPresent = 1;
ChatParticipantList()
Lists all participants of a chat
my @Participants = $ChatObject->ChatParticipantList(
ChatID => $ChatID,
);returns [ ( ChatterName => 'Firstname Lastname', ChatterID => 123, ChatterType => 'User', ChatterActive => 1, PermissionLevel => 'Owner', Status => 1, # Might not be included Monitoring => 2, ), ( ChatterName => 'Firstname Lastname', ChatterID => 123, ChatterType => 'User', ChatterActive => 1, PermissionLevel => 'Participant', Status => 1, # Might not be included Monitoring => 0, ) ]
ChatParticipantNumberGet()
get number of chat participants ( 1, 2, 3) – used with default agent name example: if DefaultAgentName is on and DefaultAgentNumbers is on result will be: SupportAgent1, SupportAgent2 ,…
my $ChatParticipantNumber = $ChatObject->ChatParticipantNumberGet(
ChatID => $ChatID,
ChatterName => $ChatterName,
);returns $ChatParticipantNumber = 1;
AgentAvailabilityGet()
Get agents availability my $AgentAvailability = $ChatObject->AgentAvailabilityGet( UserID => 2, # UserID External => 1, # optional (default 1) Get external availability );
returns $AgentAvailability = 1; # 0 – off-line, 1 – unavailable, 2 – away, 3 – on-line
CustomerAvailabilityGet()
Get chat availability of customer user. my $CustomerAvailability = $ChatObject->CustomerAvailabilityGet( UserID => 'customer-1', # CustomerUserID );
Returns: $CustomerAvailability = 3; # 0 – off-line, 2 – away, 3 – on-line
ChatParticipantCheck()
checks if a chatter has access to a chat my %Access = $ChatObject->ChatParticipantCheck( ChatID => $ChatID, ChatterID => $ChatterID, # Typically this would be a UserID ChatterType => $ChatterType, # Typically this would be 'User' or 'Customer' NoActive => 1, # do not force to show only active chatters ); Returns my %Access = { ChatParticipantID => 123, ChatterActive => 0, PermissionLevel => 'Owner', Invitation => 1, };
ChatParticipantRemove()
revokes chatter access.
my $Success = $ChatObject->ChatParticipantRemove(
ChatID => $ChatID,
ChatterID => $ChatterID, # Typically this would be a UserID
# or
ChatterType => $ChatterType # Typically this would be 'User' or 'Customer'
);or
my $Success = $ChatObject->ChatParticipantRemove(
ChatID => $ChatID,
All => 1,
);ChatMessageAdd()
adds a message to a chat.
my $Success = $ChatObject->ChatMessageAdd(
ChatID => $ChatID,
ChatterID => 'Heinz Hinz',
ChatterType => 'User',
MessageText => 'My message', # plain text, max. 3800 characters
SystemGenerated => 1, # optional, 0 or 1 (for internal messages like XY has left the chat)
Internal => 0, # optional (default 0) - If 1, this message will not be presented to the customer
Customer => 1, # optional (default 0) - If 1, this message will not be presented to the agent
);events: ChatMessageAdd – emitted when chat message is added
ChatMessageGet()
Returns a chat message for given ChatMessageID.
Usage:
my %ChatMessage = $ChatObject->ChatMessageGet(
ChatMessageID => 123, # (required)
);Returns:
%ChatMessage = (
{
ID => 123,
ChatID => 123,
ChatterID => 123,
MessageText => 'Hello',
SystemGenerated => 0,
CreateTime => '2018-09-01 12:00:00',
Internal => 0,
},
...
);ChatMessageList()
lists chat messages of a chat.
To get all chat messages:
my @ChatMessages = $ChatObject->ChatMessageList(
ChatID => $ChatID, # get all messages
MaskAgentName => 1, # optional, will use the appropriate config setting to display a generic agent name instead of the real one
ExcludeInternal => 1, # optional (default 0) - if set, system will return only external messages
ExcludeCustomer => 0, # optional (default 0) - if set, will return only messages agent can see
);If you already have a part of the chat, you can ask for new entries:
my @ChatMessages = $ChatObject->ChatMessageList(
ChatID => $ChatID,
LastKnownChatMessageID => $ChatMessageID, # optional
FirstMessage => 1, # optional, get the first text message
);If you need only last message: my @ChatMessages = $ChatObject->ChatMessageList( ChatID => $ChatID, LastMessage => 1, # optional, get only last text message );
returns
(
{
ID => 123,
MessageText => 'My chat message',
CreateTime => '2014-04-04 10:10:10',
SystemGenerated => 0,
ChatterID => '123',
ChatterType => 'User',
ChatterName => 'John Doe',
},
...
)ChatInvite()
Invite agent to chat. my %InviteResult = $ChatObject->ChatInvite( ChatID => 5, # Chat ID InviteUserID => 3, # User ID of target agent UserID => 2, # User ID of the agent who is inviting InvitationChatID => 1, # id of a chat through which communication will go );
events: ChatInvite
ChatInvitesGet()
Check if there is chat invite for given user.
my $ChatID = $ChatObject->ChatInvitesGet(
UserID => 123,
InvitationChatID => 3, # id of the chat in which user is invited to participate another
ChatID => 3, # DO NOT USE BOTH ChatID and InvitationChatID
);Result: $ChatID = 2;
ChatDecline()
Decline chat invitation (only possible for agent to agent chats).
my $Success = $ChatObject->ChatDecline(
UserID => 123,
ChatID => 4,
Message => "User xy has declined the chat request.",
);ChatChannelUpdate()
Move the chat to another channel.
my $Success = $ChatObject->ChatChannelUpdate(
UserID => 123,
ChatID => 4,
ChatChannelID => 5,
);returns $Success = 1;
events: ChatChannelUpdate – emitted when chat was moved to a different channel
ChatInviteRemove()
Delete invite for particular user and chat
my $Success = $ChatObject->ChatInviteRemove(
UserID => 123,
ChatID => 4,
InvitationChatID => 3, # don't use ChatID and InvitationChatID, send only one
);return $Success = 1;
OnlineUserList()
Fetches a list of on-line users.
my %OnlineUsers = $ChatObject->OnlineUserList(
UserType => 'User', # (required) Get only users of particular type ('User' or 'Customer')
# or
Group => 'chat', # (required) Group that user must belong to
# or
UserID => 5, # (required) Check if a specific user is on-line
External => 1, # (optional) Return only users available for external chat requests (default: 1)
IgnoreSuspend => 0, # (optional) Skip the check if agent is not active, and return suspend status
instead (default: 0)
NoDetailData => 0, # (optional) Return no user and customer user detail data (default: 0)
);Returns a hash of sessions:
%OnlineUsers = (
'13QA68d8D7IACAKzxSUKne3uVWpjZdoY5m' => {
UserSessionStart => 1402047758,
UserLastRequest => 1402047758,
UserEmail => 'root@example.com',
UserRemoteUserAgent => 'none',
UserID => 'ut-onlineuserlist-ChatCustomer-test843809',
UserRemoteAddr => 'none',
UserLogin => 'ut-onlineuserlist-ChatCustomer-test843809',
UserType => 'Customer',
UserChallengeToken => 'rBNoBkumaygHucwpqE9fY1HBxmqq8cvW',
ChatAvailability => 0, # 0,1,2
NoOutOfOffice => 1, # 1 or 0 defaults to 0
...
},
...
);AvailableUsersGet()
Returns a list of currently on-line users and their selected channels. my %Available = $ChatObject->AvailableUsersGet( Key => 'ExternalChannels' # (Required) );
Returns: %Available = { '123' => # UserID [ 1, 3, 5 ], # Chat Channel IDs … };
IsChatAgentToAgent()
Checks is this A2A chat. my $A2AChat = $ChatObject->IsChatAgentToAgent( ChatID => 1, );
Returns: $A2AChat = 1; # 0 if it's not
ChatFlagSet()
set Chat flags
my $Success = $ChatObject->ChatFlagSet(
ChatID => 123,
Key => 'Seen',
Value => 1,
UserID => 123, # apply to this user
);returns $Success = 1;
ChatFlagDelete()
delete Chat flag
my $Success = $ChatObject->ChatFlagDelete(
ChatID => 123,
Key => 'Seen',
UserID => 123,
);
my $Success = $ChatObject->ChatFlagDelete(
ChatID => 123,
AllUsers => 1,
);returns: $Success = 1;
ChatFlagGet()
get chat flags. One of the following parameters is mandatory: ChatID Key KeyNot UserID ValueID ValueNot
examples:
# get all chat flags for one user and one chat
my @Flags = $ChatObject->ChatFlagGet(
ChatID => 123,
UserID => 123, # to get flags one user
);
# get all chat update flags for one chat and for all users
# which are unseen (Value is not 1)
my @Flags = $ChatObject->ChatFlagGet(
ChatID => 123,
ValueNot => 1,
Key => "NotificationChatUpdateSeen",
);
# get all new chat flags which are already seen
# for one chat and for all users
my @Flags = $ChatObject->ChatFlagGet(
ChatID => 123,
Value => 1,
Key => "NotificationNewChatSeen"
);
# get all unseen update flags for one user and for all chats
my @Flags = $ChatObject->ChatFlagGet(
UserID => 123,
Key => "NotificationChatUpdateSeen",
ValueNot => 1, # to get all unseen flags for the user
);
# get all flags for one chat
my @Flags = $ChatObject->ChatFlagGet(
ChatID => 123,
);
# get all flags for one chat where key is not "NotificationNewChatSeen"
my @Flags = $ChatObject->ChatFlagGet(
ChatID => 123,
KeyNot => 'NotificationNewChatSeen',
);returns: @Flags = [ { Key => 'Seen', Value => 1, ChatID => 123, UserID => 1, }, … ];
