Embedded Service Chat for Web Developer Guide
jNote: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.
Custom Pre-Chat Component Sample Using Aura
The following code sample contains examples of the component, controller, and helper
code for a custom pre-chat component using Aura.
This component:
- Uses Aura to create the pre-chat fields and start a chat.
- Uses an initialize function that fetches the pre-chat fields from setup and dynamically creates the pre-chat field components using $A.createComponents.
- Creates an array when the user clicks the Start Chat button. The array contains pre-chat field information to pass to the startChat method on the prechatAPI component.
Component Code
1<aura:component implements="lightningsnapin:prechatUI" description="Sample custom pre-chat component for Embedded Chat. Implemented using Aura.">
2 <!-- You must implement "lightningsnapin:prechatUI" for this component to appear in the "Pre-chat Component" customization dropdown in the Embedded Service setup -->
3
4 <!-- Pre-chat field components to render -->
5 <aura:attribute name="prechatFieldComponents" type="List" description="An array of objects representing the pre-chat fields specified in pre-chat setup."/>
6
7 <!-- Handler for when this component is initialized -->
8 <aura:handler name="init" value="{!this}" action="{!c.onInit}" />
9
10 <!-- For Aura performance -->
11 <aura:locator target="startButton" description="Pre-chat form submit button."/>
12
13 <!-- Contains methods for getting pre-chat fields, starting a chat, and validating fields -->
14 <lightningsnapin:prechatAPI aura:id="prechatAPI"/>
15
16 <h2>Prechat form</h2>
17 <div class="prechatUI">
18 <div class="prechatContent">
19 <ul class="fieldsList">
20 <!-- Look in the controller's onInit function. This component dynamically creates the pre-chat field components -->
21 {!v.prechatFieldComponents}
22 </ul>
23 </div>
24 <div class="startButtonWrapper">
25 <ui:button aura:id="startButton" class="startButton" label="{!$Label.LiveAgentPrechat.StartChat}" press="{!c.handleStartButtonClick}"/>
26 </div>
27 </div>
28
29</aura:component>Controller Code
1({
2 /**
3 * On initialization of this component, set the prechatFields attribute and render pre-chat fields.
4 *
5 * @param cmp - The component for this state.
6 * @param evt - The Aura event.
7 * @param hlp - The helper for this state.
8 */
9 onInit: function(cmp, evt, hlp) {
10 // Get pre-chat fields defined in setup using the prechatAPI component
11 var prechatFields = cmp.find("prechatAPI").getPrechatFields();
12 // Get pre-chat field types and attributes to be rendered
13 var prechatFieldComponentsArray = hlp.getPrechatFieldAttributesArray(prechatFields);
14
15 // Make asynchronous Aura call to create pre-chat field components
16 $A.createComponents(
17 prechatFieldComponentsArray,
18 function(components, status, errorMessage) {
19 if(status === "SUCCESS") {
20 cmp.set("v.prechatFieldComponents", components);
21 }
22 }
23 );
24 },
25
26 /**
27 * Event which fires when start button is clicked in pre-chat
28 *
29 * @param cmp - The component for this state.
30 * @param evt - The Aura event.
31 * @param hlp - The helper for this state.
32 */
33 handleStartButtonClick: function(cmp, evt, hlp) {
34 hlp.onStartButtonClick(cmp);
35 }
36});Helper Code
1({
2 /**
3 * Map of pre-chat field label to pre-chat field name (can be found in Setup)
4 */
5 fieldLabelToName: {
6 "First Name": "FirstName",
7 "Last Name": "LastName",
8 "Email": "Email",
9 "Phone": "Phone",
10 "Fax": "Fax",
11 "Mobile": "MobilePhone",
12 "Home Phone": "HomePhone",
13 "Other Phone": "OtherPhone",
14 "Asst. Phone": "AssistantPhone",
15 "Title": "Title",
16 "Lead Source": "LeadSource",
17 "Assistant": "AssistantName",
18 "Department": "Department",
19 "Subject": "Subject",
20 "Case Reason": "Reason",
21 "Type": "Type",
22 "Web Company": "SuppliedCompany",
23 "Web Phone": "SuppliedPhone",
24 "Priority": "Priority",
25 "Web Name": "SuppliedName",
26 "Web Email": "SuppliedEmail",
27 "Company": "Company",
28 "Industry": "Industry",
29 "Rating": "Rating"
30 },
31
32 /**
33 * Event which fires the function to start a chat request (by accessing the chat API component)
34 *
35 * @param cmp - The component for this state.
36 */
37 onStartButtonClick: function(cmp) {
38 var prechatFieldComponents = cmp.find("prechatField");
39 var fields;
40
41 // Make an array of field objects for the library
42 fields = this.createFieldsArray(prechatFieldComponents);
43
44 // If the pre-chat fields pass validation, start a chat
45 if(cmp.find("prechatAPI").validateFields(fields).valid) {
46 cmp.find("prechatAPI").startChat(fields);
47 } else {
48 console.warn("Prechat fields did not pass validation!");
49 }
50 },
51
52 /**
53 * Create an array of field objects to start a chat from an array of pre-chat fields
54 *
55 * @param fields - Array of pre-chat field Objects.
56 * @returns An array of field objects.
57 */
58 createFieldsArray: function(fields) {
59 if(fields.length) {
60 return fields.map(function(fieldCmp) {
61 return {
62 label: fieldCmp.get("v.label"),
63 value: fieldCmp.get("v.value"),
64 name: this.fieldLabelToName[fieldCmp.get("v.label")]
65 };
66 }.bind(this));
67 } else {
68 return [];
69 }
70 },
71
72 /**
73 * Create an array in the format $A.createComponents expects
74 *
75 * Example:
76 * [["componentType", {attributeName: "attributeValue", ...}]]
77 *
78 * @param prechatFields - Array of pre-chat field Objects.
79 * @returns Array that can be passed to $A.createComponents
80 */
81 getPrechatFieldAttributesArray: function(prechatFields) {
82 // $A.createComponents first parameter is an array of arrays. Each array contains the type of component being created, and an Object defining the attributes.
83 var prechatFieldsInfoArray = [];
84
85 // For each field, prepare the type and attributes to pass to $A.createComponents
86 prechatFields.forEach(function(field) {
87 var componentName = (field.type === "inputSplitName") ? "inputText" : field.type;
88 var componentInfoArray = ["ui:" + componentName];
89 var attributes = {
90 "aura:id": "prechatField",
91 required: field.required,
92 label: field.label,
93 disabled: field.readOnly,
94 maxlength: field.maxLength,
95 class: field.className,
96 value: field.value
97 };
98
99 // Special handling for options for an input:select (picklist) component
100 if(field.type === "inputSelect" && field.picklistOptions) attributes.options = field.picklistOptions;
101
102 // Append the attributes Object containing the required attributes to render this pre-chat field
103 componentInfoArray.push(attributes);
104
105 // Append this componentInfoArray to the fieldAttributesArray
106 prechatFieldsInfoArray.push(componentInfoArray);
107 });
108
109 return prechatFieldsInfoArray;
110 }
111});