Add a Live Chat Channel

Add and configure a Live Chat channel.

Request URL

POST {base_url}/{api_path}/message_channel/createlivechat?access_token={access_token}

Request parameters

Parameter Required Type Description
name Yes String Name of the message channel.
Note: The length must not exceed 63 characters.
website_domain Yes String The domain name of the website where the Live Chat channel will be embedded.
Note: The length must not exceed 1023 characters.
communication_method Yes Integer The interaction mode supported on the Live Chat channel.
Valid value:
  • 1: Chat only.
  • 2: Phone call and chat.
destination_type Yes String The type of the destination.
Valid value:
  • extension: Extension user.
  • queue: Message queue.
  • api: Third-party message analytics platform (transmitted via API).
destination_id No Integer The ID of the destination.
Note:
enable_webrtc_inbound_call No Integer Whether to enable WebRTC inbound call, so that website visitors can make calls through the Live Chat channel.
Valid value:
  • 0: Disable.
  • 1: Enable.
webrtc_trunk_id No Integer The ID of the WebRTC trunk.
Note:
  • This parameter is REQUIRED when enable_webrtc_inbound_call is set to 1.
  • You can query the WebRTC trunk ID using Search Specific Trunks (search_value=webtrunk).
webrtc_inbound_route_id No Integer The ID of the inbound route associated with the WebRTC trunk.
Note:
max_concurrent_call Yes Integer Set the maximum number of concurrent calls supported on the Live Chat channel.

Valid value: 1 - 10.
message_type Yes Integer The message type that website visitors can send.

Valid value:

  • 1: Text and emojis.
  • 2: Text, emojis, and images.
auto_close_session No Integer Whether to close messaging sessions automatically after a specified period of inactivity.
Valid value:
  • 0: Disable.
  • 1: Enable.
session_expired_time No Integer The duration of inactivity after which a session is automatically closed.
session_expired_unit No String Specify the time unit for session expiration.
Note: This parameter is REQUIRED when auto_close_session is set to 1.
Valid value:
  • minite
  • hour
  • day
theme_mode Yes String Theme mode of the Live Chat widget.

Valid value:

  • light
  • dark
theme_color Yes String Theme color of the Live Chat widget.

Valid value: 6-digit hexadecimal RGB color value. E.g. #00DDB3.
minimize_style Yes String The style of the minimized window.

Valid value:

  • round: Bubble style.
  • bar: Strip style.
chat_icon Yes String Chat icon of the Live Chat widget.
Valid value:
  • 1:
  • 2:
  • 3:
  • 4:
  • 5:
  • 6:
default_avatar No String The file name (ID) of the agent avatar.
Note: To use a custom avatar, upload the avatar image first, then enter the file parameter value returned by the upload API in this field.
default_agent_name Yes String Agent name.
Note: The length must not exceed 63 characters.
show_agent_info No Integer Whether to display the agent information.
Valid value:
  • 0: Not display.
  • 1: Display agent name
  • 2: Display agent name and avatar.
hide_provider_info No Integer Whether to display the service provider's information Powered by Yeastar in the Live Chat widget.
Valid value:
  • 0: Display.
  • 1: Not display.
language Yes String Specify the display language of the Live Chat channel.
Valid value:
  • BROWSER_LANGUAGE: Follow website visitor's browser language.
  • en: English
  • zh-CN: 简体中文 (Chinese Simplified)
  • zh-TW: 繁體中文 (Chinese Traditional)
  • ar: العربية (Arabic)
  • pt_BR: Português Brasil (Portuguese Brazil)
  • cz: Čeština (Czech)
  • nl: Nederlands (Dutch)
  • fr: Française (French)
  • de: Deutsch (German)
  • he: עברית (Hebrew)
  • it: Italiano (Italian)
  • ja: 日本語 (Japanese)
  • fa: فارسی (Persian)
  • pl: Polski (Polish)
  • pt: Português (Portuguese)
  • ru: Pусский (Russian)
  • sl: Slovenščina (Slovenian)
  • es: Español (Spanish)
  • th: ไทย (Thai)
  • tr: Türk (Turkish)
  • tk: Türkmenistan (Turkmen)
  • uk: Українська (Ukrainian)
  • vi: Tiếng Việt (Vietnamese)
enable_prechat_form No Integer Whether to enable pre-chat form.
Valid value:
  • 0: Disable.
  • 1: Enable.
prechat_form_title No String The title of the pre-chat form.
Note: This parameter is REQUIRED when enable_prechat_form is set to 1.
prechat_form_subtitle No String The sub-title of the pre-chat form.
Note: This parameter is REQUIRED when enable_prechat_form is set to 1.
show_name No Integer Whether to display name field in the pre-chat form.
Note: When enable_prechat_form is set to 1, at least one of show_name, show_email, or show_phone must be set to 1.
Valid value:
  • 0: Not display.
  • 1: Display.
show_email No Integer Whether to display email address field in the pre-chat form.
Note: When enable_prechat_form is set to 1, at least one of show_name, show_email, or show_phone must be set to 1.
Valid value:
  • 0: Not display.
  • 1: Display.
show_phone No Integer Whether to display phone number field in the pre-chat form.
Note: When enable_prechat_form is set to 1, at least one of show_name, show_email, or show_phone must be set to 1.
Valid value:
  • 0: Not display.
  • 1: Display.
require_name No Integer Whether name is required in the pre-chat form.
Valid value:
  • 0: Optional.
  • 1: Required.
require_email No Integer Whether email address is required in the pre-chat form.
Valid value:
  • 0: Optional.
  • 1: Required.
require_phone No Integer Whether phone number is required in the pre-chat form.
Valid value:
  • 0: Optional.
  • 1: Required.
enable_data_privacy No Integer Whether to enable the data privacy statement.
Valid value:
  • 0: Disable.
  • 1: Enable.
data_privacy_content No String The content of the data privacy statement.
Note:
  • This parameter is REQUIRED when enable_data_privacy is set to 1.
  • The length must not exceed 590 characters.
require_data_privacy_consent No Integer Whether explicit consent to the data privacy statement is required.
Valid value:
  • 0: Not required.
  • 1: Required.
online_welcome_message Yes String The welcome message automatically sent to website visitors when they enter the chat widget while the system is within business hours and the message destination is available.
Note: The length must not exceed 255 characters.
offline_welcome_message Yes String The welcome message automatically sent to website visitors when they enter the chat widget while the system is outside business hours, or the message destination is not available.
Note: The length must not exceed 255 characters.
first_reply_message No String The message automatically sent after the website visitor sends their first message, regardless of message type.
Note: The length must not exceed 255 characters.
session_closed_message Yes String The message automatically sent to website visitors when the chat session ends, either manually closed by agent / website visitor or automatically closed when session timeout is reached.
Note: The length must not exceed 255 characters.

Response parameters

Table 1.
Parameter Type Description
errcode Integer Returned error code.
  • 0: Succeed.
  • Non-zero value: Failed.
Note: You can check the error code and error message in Error Code and Error Message.
errmsg String Returned message.
  • SUCCESS: Succeed.
  • FAILURE: Failed.
id Integer The unique ID of the message channel.

Examples

Request example

POST /openapi/v1.0/message_channel/createlivechat?access_token=EX8zZM5hdq3krlPcNmBbDSqfKF1ovibL HTTP/1.1
Host: 192.168.5.150:8088
Content-Type: application/json

{
    "name": "Docs-LiveChat Channel",
    "website_domain": "www.yeastar.com",
    "type": "livechat",
    "channel": "livechat",
    "communication_method": 2,
    "destination_type": "extension",    
    "destination_id": 137,
    "enable_webrtc_inbound_call": 1,  
    "webrtc_trunk_id": 3,
    "webrtc_inbound_route_id": 3,
    "max_concurrent_call": 5,
    "message_type": 2,    
    "auto_close_session": 1,
    "session_expired_unit": "day",
    "session_expired_time": 1,
    
    "theme_mode": "light",
    "theme_color": "#00DDB3",
    "minimize_style": "bar",
    "chat_icon": "6",  
    "default_avatar": "",  
    "default_agent_name": "Support",
    "show_agent_info": 0,  
    "hide_provider_info": 0, 

    "language": "BROWSER_LANGUAGE",
    "enable_prechat_form": 1,
    "prechat_form_title": "Hello 👋",
    "prechat_form_subtitle": "Please fill in the form below before starting the chat.",
    "show_email": 1,
    "show_name": 1,
    "show_phone": 1,
    "require_name": 1,
    "require_phone": 0,
    "require_email": 0,

    "enable_data_privacy": 1,
    "data_privacy_content": "<p>We need to store and process your personal data to provide you with the requested content. For detailed information about our privacy practices and our commitment to protecting your privacy, please check our Privacy Policy.</p>",
    "require_data_privacy_consent": 1,

    "online_welcome_message": "Hello! How can we help you?",
    "offline_welcome_message": "We are away, leave us a message!",
    "first_reply_message": "Hello, thank you for contacting us. We have received your message.",
    "session_closed_message": "This chat session has ended. Please feel free to contact us if you have any further questions."
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 219
}