--- title: "Chat" slug: "visitor-side-api-chat" updated: 2024-01-03T04:39:45Z published: 2024-01-03T04:39:45Z canonical: "developer.comm100.com/visitor-side-api-chat" --- > ## Documentation Index > Fetch the complete documentation index at: https://developer.comm100.com/llms.txt > Use this file to discover all available pages before exploring further. # Chat ## Chat ### Chat Status You could use the following API to listen to chat status changes: ``` Comm100API.on('livechat.chat.start', function (chatGuid) { }); Comm100API.on('livechat.chat.end', function () { }); ``` Here, when chat starts, the callback will be triggered with chat ID provided (as string). Chat will be considered as started when agent accepts the requesting chat, either accepts manually or automatically. When visitor is waiting, the chat is considered not started yet. You could use the following API to listen to the queue position change: ``` Comm100API.on('livechat.chat.waitingQueue.update', function (queue) { }); ``` Here, queue position data will be provided as an object when callback is triggered. The structure of this object is as follows: ``` const queue = { position: 0, // number, position of queue the visitor is in waitTime: 0, // number, estimated wait time }; ``` ### Agent Comm100 Live Chat API provides several events related to agents involved in chats, they are: #### Agent Join Chat ``` Comm100API.on('livechat.chat.agent.join', function (agent) { }); ``` Here, agent info is provided as an object when callback is triggered. The structure of this object is as follows: ``` const agent = { id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', // string, agent id name: '', // string, agent name title: '', // string, title of agent bio: '', // string, bio of agent }; ``` #### Agent Leave Chat ``` Comm100API.on('livechat.chat.agent.leave', function (agent) { }); ``` Here, agent info is provided as an object when callback is triggered. The structure of this object is the same as shown [above](/docs/visitor-side-api-chat#agent-join-chat). #### Agent Transfer Chat ``` Comm100API.on('livechat.chat.agent.transfer', function (agent) { }); ``` Here, agent info is provided as an object when callback is triggered. The structure of this object is the same as shown [above](/docs/visitor-side-api-chat#agent-join-chat). Please notice that this agent is the one who transfer the chat to someone else or to some other department. If you would like to know who accept the transfer, you should use [join chat](/docs/visitor-side-api-chat#agent-join-chat) API instead. #### Agent Input ``` Comm100API.on('livechat.chat.agent.input', function (agent, content) { }); ``` Here, agent info is provided as an object when callback is triggered. The structure of this object is the same as shown [above](/docs/visitor-side-api-chat#agent-join-chat). It also provides second parameter, which is the content of agent sent message. For text message, `content` will be string; for attachment or image, `content` will be an object with property `name` indicating the name of this attachment and `url` indicating the download link of this attachment. ### Visitor #### Visitor Input ``` Comm100API.on('livechat.chat.visitor.input', function (content) { }); ``` When visitor sends out text messages, this event will be triggered. When function is called, what visitor sends out will be provided as `content` parameter. Here, `content` is string. Please notice that if you configured to mask credit card number, the sensitive data will be masked first before providing to you via API. #### Visitor Set Email ``` Comm100API.on('livechat.chat.visitor.setEmail', function (email) { }); ``` This api will inform you when visitor set his/her email address during the chat. Email address will be provided as string. #### Visitor Send Text Message You can listen to visitor send text message: ``` Comm100API.on('livechat.chat.visitor.sendText', function (event) { }); ``` This api will inform you before visitor send text message to agent. The text message content can be accessed via `event.data.text`. Additionally, you have the capability to abort the message sending process by invoking the `event.cancel()` method within this callback function. Note The `event.cancel()` method must be invoked synchronously within the callback function. To send a text message to agent during chat: ``` Comm100API.do('livechat.chat.visitor.sendText', 'Message content'); ``` Note Invoking the `livechat.chat.visitor.sendText` method programmatically does not trigger the event associated with it. Therefore, it is safe to call this method within the event callback function. With the APIs described above, you can intercept a visitor's text message, modify it, and then forward it to an agent. Following is an example of masking visitor text when matching a regex: ``` Comm100API.on('livechat.chat.visitor.sendText', function (event) { if (event.data.text) { const urlRegex = /https?:\/\/[^\s+]/g; // cancel current action, this MUST happen synchronously inside this function event.cancel(); // send masked content Comm100API.do('livechat.chat.visitor.sendText', '***'); } }); ``` #### Rating ``` Comm100API.on('livechat.chat.visitor.rate', function (rating) { }); ``` When visitor rate the agent during chat, callback will be triggered. The rating result will be provided as an object, which has the following structure: ``` const rating = { score: 0, // number, rating score comment: '', // string, rating comment } ``` Please notice that the attribute of strucutre above are optional, it depends on whether you have enabled them in Control Panel. ### Display You could listen to display event of chat panel: ``` Comm100API.on('livechat.chat.display', function () { }); ``` ### Minimize You could listen to minimize event of chat panel: ``` Comm100API.on('livechat.chat.minimize', function () { }); ``` To minimize chat panel manually, use following API: ``` Comm100API.do('livechat.chat.minimize'); ``` ### Restore You could listen to restore event of chat panel: ``` Comm100API.on('livechat.chat.restore', function () { }); ``` To restore the chat panel manually, use following API: ``` Comm100API.do('livechat.chat.restore'); ``` ### Close You could listen to close event of chat panel: ``` Comm100API.on('livechat.chat.close', function () { }); ``` To close the chat panel manually, use following API: ``` Comm100API.do('livechat.chat.close'); ``` Please notice that closing chat will not end chat by default. To ensure the ongoing chat is ended before window is closed, you could use the API described below. ### End Chat To end ongoing chat, use following API: ``` Comm100API.do('livechat.chat.endChat'); ``` ### Replacement There are several components in chat panel which can be replaced by your own component, following are they and how you could replace: #### Header Icons ``` Comm100API.render('livechat.chat.header.icons', function () { // return custom HTMLElement to replace default component }); ``` #### Header ``` Comm100API.render('livechat.chat.header', function () { // return custom HTMLElement to replace default component }); ``` #### Footer ``` Comm100API.render('livechat.chat.footer', function () { // return custom HTMLElement to replace default component }); ``` #### Powered-by Area ``` Comm100API.render('livechat.chat.footer.poweredby', function () { // return custom HTMLElement to replace default component }); ``` ### Audio/Video Chat To initiate audio chat, use following API: ``` /** @type {Promise} */ const promise = Comm100API.do('livechat.chat.audio.request'); ``` To initiate video chat, use following API: ``` /** @type {Promise} */ const promise = Comm100API.do('livechat.chat.video.request'); ``` Calling this API is same as clicking audio/video icon on chat window. That means, it might fail if audio/video chat is not available. The returned promise will reject with error string when failed. Following are possible error strings rejected by promise: - `webrtc_not_supported`: brorwser of either agent or visitor does not support WebRTC. - `audio_video_chatting`: visitor is either audio chatting or video chatting. - `frequency_limited`: number of messages sent out by visitor during a certain period of time has reached upper limitation, cannot send out further message at the moment. - `audio_not_enabled`: audio chat is not enabled in this campaign - `video_not_enabled`: video chat is not enabled in this campaign - `not_chatting`: visitor is currently not chatting Following are available events that can be listened to when audio/video chat status changed: Request of Audio/Video Chat: ``` Comm100API.on('livechat.chat.audio.request', function () { }); Comm100API.on('livechat.chat.video.request', function () { }); ``` Refuse of Audio/Video Chat: ``` Comm100API.on('livechat.chat.audio.refuse', function () { }); Comm100API.on('livechat.chat.video.refuse', function () { }); ``` Start of Audio/Video Chat: ``` Comm100API.on('livechat.chat.audio.start', function () { }); Comm100API.on('livechat.chat.video.start', function () { }); ``` Stop of Audio/Video Chat: ``` Comm100API.on('livechat.chat.audio.stop', function () { }); Comm100API.on('livechat.chat.video.stop', function () { }); ``` Cancel of Audio/Video Chat request: ``` Comm100API.on('livechat.chat.audio.cancel', function () { }); Comm100API.on('livechat.chat.video.cancel', function () { }); ``` Audio/Video Chat request has not been answered: ``` Comm100API.on('livechat.chat.audio.noanswer', function () { }); Comm100API.on('livechat.chat.video.noanswer', function () { }); ```