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 test this, select a service scenario in setup and to that snippet add the below. This would cause a merge and the extraPrechatInfo and extraPrechatFormDetails would override the first name, last name and subject passed in from the chasitor.

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: In case your business needs an entity which is not available in the standard scenarios that Embedded Service for Web exposes e.g. you need to be able to create an account when a chat comes in you can do that by defining that entity in the extraPrechatInfo 
 

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: If you want to just find and not create a contact on each incoming chat you can disable contact creation by just adding this extraPrechatInfo.

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}];