Override default behavior or create custom entities with Embedded Service pre chat API

Basics

There are two types of pre-chat information that get passed from the widget to LiveAgent: info (prechatInfo), and form details (prechatFormDetails).

Form details (prechatFormDetails) describe an individual field, such as “Email”. They have a label (“Email”), a value, an array of transcriptFields (API names of transcript object fields that will inherit the prechat field’s value), and a displayToAgent boolean (if the field is available in the little popup when you hover over a pending chat).

Info (prechatInfo) allows mapping from fields to entities. It has an entityName (“Lead”), a showOnCreate boolean (should the created object be shown to the agent?), a saveToTranscript string (what’s the label we should give for the transcript row that displays the newly created object), and an array of entity-field mappings. The ‘entityFieldMap’ has the following in it :

• fieldName - The name of the field you want to perform ‘FindOrCreate’ on. 
• isExactMatch - Should ‘FindOrCreate’ perform an exact match on the above field
• doCreate - If ‘FindOrCreate’ returns false, do you want to create the above entity with this field
• doFind - Do you want to ‘Find’ the entity based on this field before creating it
• label - The corresponding label in prechatFormDetails

More details of Prechat API and the fields can be found here.

Merging of prechat and extraPrechat

There are two sources of prechat info and prechat form details: setup values (“regular” prechatInfo and prechatFormDetails), and extra values provided in the snippet by the user (“extra” prechatInfo and prechatFormDetails). These values are merged into one array, with extra values taking precedence over regular values, and then sent to FindOrCreateCommand. 

IMPORTANT: If you have the same fields in prechat and extra prechat, the merge happens based on the label name. So if you want to override default settings for fields defined in the setup you need to make sure the label names match in the extraPrechatInfo 

Examples: 

1. Overriding fields from Setup: To override default Setup fields (e.g., First Name, Last Name, Subject), set extraPrechatFormDetails to an array containing objects for each field, with a label matching the Setup field name and a hardcoded value. Simultaneously, set extraPrechatInfo to define entity mappings for Contact and Case. The entity field maps in extraPrechatInfo must use the same labels as those in extraPrechatFormDetails for the merge to work. For example, setting First Name to "Marc" and Last Name to "Benioff" will override the values a chasitor would normally enter.

embedded_svc.settings.extraPrechatFormDetails = [{"label":"First Name","value":"Marc","transcriptFields":[],"displayToAgent":true},{"label":"Last Name","value":"Benioff","transcriptFields":[],"displayToAgent":false},{"label":"Email","value":"benioff@salesforce.com","transcriptFields":[],"displayToAgent":true},{"label":"issue","value":"Sales forecasts","transcriptFields":[],"displayToAgent":true}] ; 

embedded_svc.settings.extraPrechatInfo = 
[{"entityName":"Contact","showOnCreate":true,"linkToEntityName":"Case","linkToEntityField":"ContactId","saveToTranscript":"Contact","entityFieldMaps":[{"isExactMatch":true,"fieldName":"FirstName","doCreate":true,"doFind":true,"label":"First Name"},{"isExactMatch":true,"fieldName":"LastName","doCreate":true,"doFind":true,"label":"Last Name"},{"isExactMatch":true,"fieldName":"Email","doCreate":true,"doFind":true,"label":"Email"}]},{"entityName":"Case","showOnCreate":true, "saveToTranscript":"Case", "entityFieldMaps":[{"isExactMatch":false,"fieldName":"Subject","doCreate":true,"doFind":false,"label":"issue"},{"isExactMatch":false,"fieldName":"Status","doCreate":true,"doFind":false,"label":"Status"},{"isExactMatch":false,"fieldName":"Origin","doCreate":true,"doFind":false,"label":"Origin"}]}]

2. Add extraPrechatInfo with a new entity Account: To create an entity not available in standard Embedded Service scenarios (such as Account), add it to extraPrechatInfo with its own entityFieldMaps. For example, to find or create an Account based on the Last Name field, add an Account entry to extraPrechatInfo with fieldName: "Name", doCreate: true, doFind: true, and isExactMatch: true, with its label matching the corresponding entry in extraPrechatFormDetails.
 

embedded_svc.settings.extraPrechatInfo = [{"entityName":"Contact","showOnCreate":true,"linkToEntityName":"Case","linkToEntityField":"ContactId","saveToTranscript":"Contact","entityFieldMaps":[{"isExactMatch":true,"fieldName":"FirstName","doCreate":true,"doFind":true,"label":"firstName"},{"isExactMatch":true,"fieldName":"LastName","doCreate":true,"doFind":true,"label":"LastName"},{"isExactMatch":true,"fieldName":"Email","doCreate":true,"doFind":true,"label":"Email"}]},{"entityName":"Case","showOnCreate":true,"entityFieldMaps":[{"isExactMatch":false,"fieldName":"Subject","doCreate":true,"doFind":false,"label":"issue"},{"isExactMatch":false,"fieldName":"Status","doCreate":true,"doFind":false,"label":"Status"},{"isExactMatch":false,"fieldName":"Origin","doCreate":true,"doFind":false,"label":"Origin"}]},
{"entityName":"Account","showOnCreate":true,"entityFieldMaps":[{"isExactMatch":true,"fieldName":"Name","doCreate":true,"doFind":true,"label":"LastName"}]}];

embedded_svc.settings.extraPrechatFormDetails = [{"label":"firstName","value":"Usain","transcriptFields":[],"displayToAgent":true},{"label":"LastName","value":"Bolt","transcriptFields":[],"displayToAgent":false},{"label":"Email","value":"bolt@gmail.com","transcriptFields":[],"displayToAgent":true},{"label":"issue","value":"Laptop broken","transcriptFields":[],"displayToAgent":true}] ;

3. Disable creating Contacts on each chat: To find but not create a Contact on each incoming chat, set doCreate: false and doFind: true for each Contact entity field map (First Name, Last Name, Email) in extraPrechatInfo. This prevents duplicate Contact creation while still allowing Salesforce to find an existing Contact.

embedded_svc.settings.extraPrechatInfo = [{"entityFieldMaps":[{"doCreate":false,"doFind":true,"fieldName":"LastName","isExactMatch":true,"label":"Last Name"},{"doCreate":false,"doFind":true,"fieldName":"FirstName","isExactMatch":true,"label":"First Name"}, {"doCreate":false,"doFind":true,"fieldName":"Email","isExactMatch":true,"label":"Email"}],"entityName":"Contact","saveToTranscript":"Contact","showOnCreate":true}];