Live Agent Logo

Live Agent Pre-Chat API

The many different configuration options available and base out-of-the-box functionality make Salesforce Live Agent especially appealing for a web chat product. The Pre-Chat API in the Pre-Chat form is the focus of this article.

Collecting information from chat customers prior to them being connected to an agent is a common use case of web based chats. Providing that information to the agents before they interact with the chat customer will increase the agents’ productivity since they won’t have to take time to manually ask those questions. Live Agent has an optional Pre-Chat form that can be provided for the chat customer to fill out prior to the start of the chat. The methods available are documented as the Pre-Chat API in the Live Agent Developer’s Guide. The Pre-Chat API can be used to search for or create records automatically when a chat customer submits the Pre-Chat form. The Pre-Chat API is an API that is very powerful and interesting. The “code” that you write is actually just HTML input elements that conform to the API. Before you can use a Pre-Chat form there is some configuration set up that must be done. For a detailed look at all of the different options available for Live Agent see the Help Page: Setting Up Live Agent.

Configuration Set Up

The Pre-Chat form can be placed in a Visualforce page and accessed via a Site or you can place it in a non Salesforce website. Before the Pre-Chat form can be used you must specify its location in the Chat Button customization. There is a field called Pre-Chat form URL that allows you to specify the URL for the page that has your Pre-Chat form on it. That’s the field you should use to specify a non Salesforce URL. There is another field called Pre-Chat form Page that is a Lookup to a Visualforce page that has your Pre-Chat form in it, which you would use if you were hosting the Pre-Chat form on a Site. If you are deploying to your non Salesforce website then you can just leave that blank.

Chat Button Configuration
Chat Button Configuration

In the Deployment configuration you need to make sure that you add the domain where you deploy Live Agent to the Permitted Domains field. Note that you must also check the Allow Access to Pre-Chat API checkbox.

Chat Deployment Configuration
Chat Deployment Configuration

Pre-Chat Form Code

The Live Agent Developer’s Guide has a very basic Pre-Chat form code sample from which to start. I’ve created a Pre-Chat form that is much more complex to explore the different features available.  The code below is a Pre-Chat form that I created that collects input, searches for a Contact, creates one if not found, creates a Case, links the Contact to the Case, and the Case and Contact to the Live Chat Transcript record. Below is the Pre-Chat form screen, followed by the code and a detailed explanation.

Client Chat Window
Client Chat Window

The Live Agent HTML page code is available in this Gist.

The JavaScript takes the endpoint URL parameter passed from the deployment page and makes it the action for the form, so that the form is submitted to the proper place. There is nothing that needed to be changed from what was provided in the Developer’s Guide.

You can specify custom details on the live agent chat. These will be displayed in the Details of the Chat for the agent and the hover pop that is displayed when the agent mouses over the accept chat button. The format is name="liveagent.prechat:<detailName> and you can specify whatever values you want. When you are reading the Pre-Chat API documentation and you see reference to detailName, that’s referring to the value you specify after the colon in liveagent.prechat:<detailName>. These values will appear on the hover of request and on the Visitor Details screen.

Chat Connection Pop
Chat Connection Pop

The custom details values are not automatically saved on The Live Chat Transcript record. To do that you need to actually create a corresponding custom field on the Live Chat Transcript and use the save input, e.g., <input type="hidden" name="" value="Your_Custom_Field__c" />. Note that you can use hidden inputs for the custom details. The custom details in the code from above is:

Once you have the details set up, you can specify how they should get mapped into Salesforce. You create one Map per Object. In each map you specify the Object’s field name, custom detail name and you separate each pair with a semi-colon. In the code sample, the Contact and the Case are mapped:

Once you have the fields mapped you can specify that you want to search for an existing record using the doFind input. If you only want to find exact matches you can use the isExactMatch input. If more than one match is found Salesforce will dispaly a search results list. In the code sample, the Contact’s email is used to search:

If nothing is found in the search, Salesforce will not automatically create a new record. To do that you must use the doCreate input. If you use both the doFind and the doCreate, Salesforce will attempt to find and if it doesn’t it will create. If it does find it will not create. In the code sample, a Case is always created and a Contact is only created if the doFind doesn’t find one. The doCreate lets you specify which fields you want included on the new record. For instance, you might want to use a field in the doFind that you wouldn’t want on a newly created record. The code from above is:

You do not have to use the doFind.  You could just use the doCreate if you don’t want to search.  Likewise, you don’t have to use the doCreate, you could just use the doFind.

You can specify which records should be displayed in the console when found or created with the showOnCreate input. The code from above shows both the Contact and the Case:

The Live Chat Transcript Object has Lookup fields to both Case and Contact. Use the saveToTranscript method to have those Lookups set to the found or created records. The code from above is:

Lastly, of course, you want to link the Contact and the Case. The Pre-Chat API has a linkToEntity input that does just that. What’s really cool about this is that it links the Case to a found Contact or a newly created one. The code from above is:

You need to be careful about how you specify the fields that need to be created. They are case sensitive as @PepeFloyd noted on the SFSE (upvote it!).

Custom Fields

In the above example all of the fields are standard fields on standard objects.  If you need to map a custom field, you need to use the API name of the custom field.  For example, if you have a custom text field on the Case called Service Tag that has an API name of Service_Tag__c you would map it using Service_Tag__c.  The above mapping for the Case would change to the following.


During the course of development you may run into a few issues.  I’ve noted some common ones that I’ve observed below.

  1. Your chat is showing up as offline to the chat customer. It could be that you don’t have any agents online. You must have at least one user in the Service Console with their Live Agent status set to Online. The Live Agent deployment is smart enough to know when no agents are available.
  2. Make sure that you added your domain to the permitted domains in the Deployment configuration.  If it isn’t there chat customers will not be able to connect.
  3. If you aren’t using an Online and Offline image, make sure that you’ve edited the Chat Button Code to add online and offline text inside the anchor/hyperlink tag. They default to an HTML comment.
  4. Build your form incrementally, one field/function at a time. The form will not work if you have syntax errors. It’s much easier to pinpoint causes of failure when you build incrementally.
  5. If you are attempting to create a record make sure that you have values for required fields set.  If you don’t the record can’t be created.
  6. Lastly, if you are still stuck, you can inspect the requests and responses with the Chrome Developer console. For example, I observed that if the domain hasn’t been permitted the response is “Domain is not whitelisted for this deployment”.

Live Agent also integrates nicely with Salesforce Knowledge!

The Live Agent HTML page code is available in this Gist.

158 thoughts on “Live Agent Pre-Chat API

  1. Hey Peter,

    Would you be able to provide any advice on how to pass the client’s email address (collected on the pre-chat form) to the case that is created with the code above. Case origin is carrying over just fine, but I am having no luck with email address.

    Thank you in advance!

    1. Hey Adam. The Email Address in my example will get set on the Contact and the Contact will get linked to the Case. The Contact Email field on the Case is just a display of the Contact’s Email field. It definitely works for me.

      The one gotcha is that the Contact has to be able to be saved. So, if you have a validation rule or required fields (e.g., Last Name) they must be sent as part of the form to the Contact. In my example the Last Name field is the only required field on the Contact in my org and there aren’t any validation rules.

      One thing to try is to comment out / remove everything from the form except the Contact fields and get the Contact to save. Once you have the Contact saving successfully, then bring back the Case fields and the linkToEntity to link them.

    2. HI Peter,
      I have copied, and i using vf page but when am clicking “Request submit” button, it not giving any pop-ups,
      Is their any controller is controlling i am very new to live agent.
      I need to populate the values in the chat pop-up , like below image.
      i need to change any code.
      Please suggest me on it.

  2. Thanks for the quick reply.

    Any suggestions on how to accomplish this without using Contact? We just need to pull the email address they provide into a custom email field on the Case.

    1. That can be done. The key is to use the API name of the custom field. If your custom field is Email__c then use that in the mapping and doCreate.

      Assuming a custom field called Email on the Case, you could add the following input and then update the mappings and the doCreate.

      <input type="text" name="liveagent.prechat:caseCustomEmail" />

      <input type="hidden" name="" value="Origin,caseOrigin;Subject,caseSubject;Email__c,caseCustomEmail;" />

      <input type="hidden" name="" value="Origin,true;Subject,true;Email__c,true;" />

      1. Peter,

        Thank you for this blog post and your very quick replies to my questions. I was able to successfully use your last post to make this work! I finally understand it as well.

        Thank you!

  3. One more question for you Peter. 🙂

    Do you know of a way to pull the buttonid, of the button the client clicked to initiate the chat, into the chat details pane or possibly to the case that is created.

    I see the option to pull it to the post chat survey and that works great, but I can’t seem to find a way to get it onto the case.

    1. Sorry Adam. I haven’t done that yet, so am not 100% sure how it would be done. The button id appears as an URL parameter “button_id” on the pre chat popup, so you might be able to use that, e.g., assign to hidden input and map that. If the user is manually selecting it from a select list you could use JavaScript to handle the onchange and assign it to a hidden input and map that.

      I do see the chat button name on the connection pop. It’s the “Website Button” text on the Chat Connection Image in my article.

  4. Hey Peter, great blog! My question is I don’t ask the user for their email but want to grab the email of the user that is currently signed in and then pass it through so the Contact associated with that email is opened in Live Chat.

    Anyway to do that?


    1. Thanks Nishant! Glad you like it. 🙂

      You can change the email custom detail input type from “text” to “hidden” and then set the value to wherever the current user’s email is stored.

      For example, if the current user’s email was in an expression of {!}, you’d have:
      <input type=“hidden” name=”liveagent.prechat:contactEmail” value=“{!}” />

      That would replace the email input line in my example code:
      <!– no longer needed –>
      Email: <input type=”text” name=”liveagent.prechat:contactEmail” />

      The rest of the code I have in the example does search for a Contact with that email address and shows it on the screen.

  5. Hi Peter,
    Thank you for this blog, its helped me understand the standard Live Agent Guide much better. What I can’t figure out is how the deployment code, button code and custom pre-chat code need to be layed out together. I was able to get the button code and deployment code to work as a test in an HTML file on my desktop and as a visualforce page. I can’t figure how/where to add the pre-chat code you posted above in relation to the button and deployment code.

    I’m thinking it would be useful to have the basic button show up, when clicked it takes you to the form which then you can click to start the chat. Would the button and pre-chat form need to be 2 different pages then?

    1. Hey Justin. You’re welcome for the blog. 🙂

      Yes. There needs to be two pages. The button and deployment code go on one page and the pre chat goes on another.

      The Pre-Chat form has to be specified in the Chat Button Configuration. There are two options.
      1. There is a field called Pre-Chat Form URL. You would specify the URL of wherever you have the pre chat html page (e.g.,
      2. There is a field called Pre-Chat Form Page. This is a Lookup to a Visualforce page. If your Pre-Chat Form is a Visualforce page in your org, you can set it this way. It needs to be a VF page that is in the site that you specify in the Site For Resources field.

      You would only specify a value for one of them. In fact, if you try to specify them both you’ll get an error and it won’t let you save.

      1. Awesome, thanks.

        I was able to get the first window be the button showing if an agent is online. If an agent is then clicking it takes you to the pre-chat page like I wanted. Filling out the form and submitting, however, does nothing but reset the form. This part I have never been able to get to work.
        * Both pages are supported on separate visualforce pages.
        * The ‘Pre-chat form page’ is set to the visualforce page containing the pre-chat code.
        * ‘Allow access to pre-chat API’ is checked on.
        * I’ve tried it with and without permitted domains with the same results.
        * I don’t have queuing activated.

        Not sure why the Submit Button doesn’t work.

        1. Hmmm…not sure what it could be. Sorry. It’s a stretch, but you could use something like the Chrome Developer Console to try to get more of an understanding of what’s going on when the Submit button is clicked. See if it is even POSTing the form and if it is what the response is. The example that I have in this article sets the action of the form dynamically using JavaScript.

          1. The demo code from the developers guide mentions the submit button takes the endpoint URL passed from the deployment code. Maybe I’m missing something in my deployment code. Would you be able to post or send your example if you still had it and I could compare against mine to see if it contained the proper syntax to pass the endpoint?

  6. Peter,

    First of all, thank you for this wonderful content that you’ve provided! I have a particular requirement that I am trying to satisfy: Find-a-matching Contact, Find-a-matching Lead. Create a new Lead ONLY if a matching Contact is NOT FOUND. I have accomplished finding both and creating the lead if not found. I am stuck, however, on finding supporting documentation for how to conditionally create ONE object if the exactmatch for a different object returns Nothing.

    Any suggestions?


  7. Hi Peter,

    Thanks for the great code example. I have used it to test out live agent, however I’m experiencing that the case is being created with the Case information but another case is also being created. Do you have any ideas as to why it would be doing this? I’ve been racking my brain for hours but can’t seem to get it not to create the additional case, which I think is by default at chat initiation.



    1. My initial guess would be that you have the Console App configured to create a new case.

      If you edit the Console App (Setup menu | Create | Apps) you’ll see an option “Choose Chat Workspace Options” under it, you can specify what should happen when a new chat is accepted in the “Choose the records or pages to open as subtabs of each chat session”. If the “New case” is checked then you’ll get the Case that Live Agent Pre-Chat API creates and the Case from the configuration of the Console, although it will be blank.

  8. Hello,
    I am creating a VF page to be the post chat page to redirect the user to a survey url. However I do not want to do this if the chat was cancelled. So I am looking at the Error in the parameters to determine action. Any advice on how to close the chat window ? For some reason even the default window (without the post chat page) does not close on completion. Or do you have something on the pre-chat page to close the window gracefully if the chat was canceled ?
    Thanks !

    1. Hi Maggie,
      I am trying to work on the same issue and have no idea how to gracefully show the customer that the chat could not connect. Were you able to find any solution for your issue ?

      Amit Sinha

      1. No graceful exit. What I did is if there is an error, made it not to redirect to survey but to a different page.

  9. Hi Peter,

    I have a few questions and it would be really great if you could point me in right directions on them.

    1. I have used the “{!User_FirstName}” in the Custom Agent Name and “{!LiveAgent_VisitorName” in the Auto Greeting field, however for some reason both of these fields are not populating anything in the chat window. Can you think of any reason why this would happen.

    2. Also I want to do a post chat survey like – “Please rate your experience” with values – Good / Bad / etc..How can i do that ?


      1. Hi Amit,

        I’m not sure if you’ve already found the answer but you need to specify the name with a period instead of a colon like this:

        Also, not split it into First Name and Last Name.

  10. Peter – great article. One quick question, when you do showOnCreate, it opens the record in read only mode, is it possible to open it directly in edit mode? Thanks.

  11. Hi

    Thanks for sharing this one.

    How can i auto attache chat transcript to case is created ? There is one option where agent can do it from console, but i have a requirement that transcript should be auto saved with case when chat gets ended.

    Thanks in Advance.


    1. Hi Hemant,
      The pre-chat form code actually does that automatically with the following:

      <input type="hidden" name="liveagent.prechat.findorcreate.saveToTranscript:Case" value="Case" />

      That sets the Case Lookup field on the Live Chat Transcript record to the Case that was created. You can see it if you view the Live Chat Transcript record or if you look at the Live Chat Transcripts related list on the Case detail page. You might need to add the related list to the page layout of the Case, if it is not already there.

      If you are looking for something else that doesn’t involve the pre-chat form described in this article, you may have better luck tapping into the power of the community and posting your question to the Developer Force Boards or Salesforce Stack Exchange

      1. Hi Peter,

        Thanks for the response. I think i was not able to clear my query but I think now I have found the answer but still just want to verify with you also that what I know is correct or not.

        Chat Transcript will only be created when “The chat is ended by either one” and “The console tab is closed by the Agent”? Is this correct?

        I was searching a way by which transcript can be saved without closing the console tab as sometimes Agent forgot to close the tabs and thus resulting in losing the chats.

        Please let me know if I am right or wrong.

        Thanks again for your time…

  12. Thanks so much for this post, it’s been invaluable to getting my pre-chat form up and running.

    The only issue I’m running into is that the contact record is not populating the look up on the case. When the records pop after the agent accepts the chat, there are no values in the lookup fields on the transcript, although the case and contact name do fill correctly on save. I’m wondering if this is the issue since the case is saving before the transcript.

    Thanks for any insight you may have!

    1. The Contact lookup should be set on the Case with the code that I have in the article. It can be challenging to troubleshoot the pre-chat functionality. I’ve spent a decent amount of time on problems like yours. The best advice that I can give is to try to reduce everything and get little pieces working independently and then try to bring them together. I included some troubleshooting steps in the article that I found helpful, too.

  13. Hi Peter,

    Great article!! 🙂 One quick question, can I search for an email on the Opportunity record instead of a Contact record? How would I do it?


  14. One more question, can I search for multiple fields on the same record? I want the record to show only when both the account name and email match.

    1. Yes. You can search for multiple fields on one Object. You just specify the fields in a semi-colon delimited list, e.g., “Email,true;Name,true;” I don’t recall off the top of my head if it does an AND match or an OR match. You’d have to experiment to see.

  15. Peter, do you know if the doFind method will work for Person Accounts? I tried to search for Account based on PersonEmail field and it doesn’t seem to be working. If I change the object to Contact and use regular Email field it works to search within Contact but not for Person Account.

  16. Thank you for posting this article as I have been pulling out my hair a bit trying to set pre-chat up. My question is in the original pre-chat code there are some option values for a drop down.
    Delegate Sales
    General information if online, otherwise Delegate Sales
    I am taking the option values from the portion of the code that refers to online button status that is given by creating online and offline buttons for each of the drop down selections shown above. Is this the correct way to do this to route to each department or is there another way I should be doing this?

  17. Hi,

    I am trying to create an Event, like u created a case in this post.

    What is going wrong with the above code ?
    Appreciate your help !

  18. Hi Peter Knolle,

    I’ve an issue. I’m getting ‘Authorised Error’ when I clicked on Button Image.I used the same code which you have provided in pre-chat form.Without the pre-chat form in the button is working fine.When I incorporate the same in the buttoncode,giving an ‘Authorised Error’
    Can you please help me on this.


      1. I’ve some different requirement.

        I’ve to create a case when the chat is initiated and if the inquiry is related to existing case,need to open the existing case with details. How can I achieve this,Please help on this.


  19. Hello,

    I have setup live agent similar to this example. Thanks for the help. 🙂

    My question is are there user permission requirements to have a case automatically created when the chat session is accepted by an agent?

    The cases are created when we test with a system administrator, but not with a ‘regular’ user and I cannot easily find a permission setting that would disallow this. There is nothing in the developer console that is indicating there is a permission issue, but I am not sure what else it would be.


  20. Hi Peter,

    Just wanted to comment to thank you for this great blog post – this was unbelievably helpful in making sure that Live Agent cases are created properly and do what we want them to do.


  21. When this code creates the contact will it create the person account as my clients org uses person accounts and would need to see if this is possible. Any help on this would be great.

      1. Hmm, the HTML tags got stripped: Add below and you can use this to create the Person Account

        input type=”hidden” name=”” value=”FirstName,First Name;LastName,Last Name;PersonEmail,Email;BillingPostalCode,Zip;Type,Customer Type;RecordTypeId,'{!PersonRTId}'” /

        input type=”hidden” name=”” value=”FirstName,true;LastName,true;PersonEmail,true;BillingPostalCode,true;Type,true;RecordTypeId,true” /

        input type=”hidden” name=”liveagent.prechat.findorcreate.saveToTranscript:Account” value=”AccountId” /

  22. Hi Peter, Thanks for this great blog. It was very helpful. I have question.

    I need to be able to block a customer for chat, based on a certain field value on contact record.

    So, basically the customer fills out a pre-chat form and submits it, system looks for the contact record, and based on a field value, chat should be disabled.

    How can this be done?

    1. Katherine,

      You could use javascript remoting to get the value of the field for the current user, if the user should be blocked you could change the value of the submit button to a VF page indicating they can’t initiate a chat for X reason.

  23. HI Peter,

    Firstly , thanks a ton for this code, which helped me a lot. I would like to know, if we can send an email to the email id entered in the prechat form, after the chat has been ended.

    Pavan Hegde

    1. Hi Pavan. Thanks you and I am not sure of the answer off the top of my head. You might be able to get more help from the SFDC dev community on the Salesforce Developer Boards or Salesforce Stack Exchange. 🙂

  24. Hi Peter,

    Could you please help me out in letting me know how can we re arrange the fields, getting displayed in the box. You have given Firstname, lastname, email. But while displaying, it is not displaying in the order of these input.

    Please help me.


  25. Hi Peter,

    Could you please help me out in letting me know how can we re arrange the fields, getting displayed in the box. You have given Firstname, lastname, email. But while displaying, it is not displaying in the order of these input.

    Please help me.


  26. Hi Pete, I have an interesting question for you:
    We do exactly what you describe above for case & contact (find or create and link to entity)

    We identified an issue, when the lvie chat is transferred to another agent – the linked entities are dropped (So the transcript moves to the new agent, with no case attached)
    Salesforce support tell us that ‘this is working as designed’ ..

    I wonder if you encountered the same, and if so – did you find a solution for this issue?

  27. Hi Peter

    I tried to use PersonAccounts for this, and was successfully able to do this. But we also have a validation rule that when the Case is created, the AccountID must be set. I tried the following two methods and it did not work, any suggestions?



  28. Hi Peter

    I tried to use PersonAccounts for this, and was successfully able to do this. But we also have a validation rule that when the Case is created, the AccountID must be set. I tried the following two methods and it did not work, any suggestions?



  29. Hi Peter,

    We have a requirement to add a new field to the Live Chat Transcript and this field should be editable by the Agent while he is talking to the Customer. This would mean we will have to display the live chat transcript record along with the Contact that was created. Can this be achieved thru pre-chat ? if so, what code needs to be added to the pre-chat to display the record and the ability to edit and save a field on the live chat transcript record.


  30. After filling up the pre-chat form, the visitor name is captured but it is not being displayed on the chat window. Capturing the name dynamically after the initialization method of button deployment, so cannot use the setName() method. Is there any other way to get the visitor’s name after the initialization method on the chat window?

    1. We had the same question and our Salesforce contact gave us this method, I haven’t tried it out yet. If this is what you are looking for,

      The pre-chat form has three fields that are visible to the customer, First Name, Last Name, and Email. In addition, there’s a hidden field for the
      The value of the can be set and it will override the Visitor name in the agent’s chat window.
      To accomplish this, the value of the field must be set. Let’s check out how to do this..
      First, we created a new javascript function deployed in the pre-chat page to set the value of the visitor’s name to the concatenation of the First Name and Last Name values
      provided by the customer.
      2 function setName() {
      3 document.getElementById(“prechat_field”).value =
      4 document.getElementById(“firstname”).value + document.getElementById(“lastname”).value;
      5 return true;
      6 }
      You may have noticed earlier that we added an onsubmit event attribute to call the setName function.

      When the user submits the form, the values she provided in the First Name and Last Name fields will set the Visitor name that appears to the agent.

  31. Hi All,
    what to pass in endpoint url ?
    do i need to pass ‘’ url?
    Please help

  32. Hi Peter,

    Your post has been very helpful in setting up our Live Agent. We are using our own page for the pre-chat form so the code was very helpful.

    If I have custom chat online and offline buttons and we are not using sites or visualforce, where do I configure the images for online and offline?


    1. Hi Jen,

      You cannot use Pre chat form without adding sites. You need to add sites and then you can configure the pre chat page and online, offline buttons.


  33. Hi Peter,

    Could you please let me know if there is a way of setting visitor name from pre-chat form so that it reflects in the LiveAgent.VisitorName. I am currently taking it as an input in pre-chat form. Hence not being able to set it using liveagent.setName() in deployment API.


    1. Hi Ayan,

      Use the below code in your Prechat form to get the name mapped in the agent window. It will display the name in the Pre chat form.


      1. Hi Ayan,

        Use the below code in your Prechat form to get the name mapped in the agent window. It will display the name in the Pre chat form.
        Name: input type=’text’ name=’
        Instead of :name, use .name


  34. Hi Peter,

    Can we display the details (like Location,ipAddress) in the hover pop up. I can see that information in the visitor detail but not able to fetch that in hover pop -up.? Can we do that.

  35. Hi Peter – Great article. I have a different question regarding prechat forms that maybe you could be of some assistance. Our prechat form has multiple skills as shown below, however they have different operating hours. The prechat form has multiple options for a customer to select, but we only want those options to appear if an agent is online.

    Any help would be appreciated


    Customer Service
    Technical Support

  36. I am working on Prechat object, when I accept the chat appears the new case created and contact information, and this is Ok for me. But my requirement is: “When Agent accepts chat, secondary tab ‘Case’ should be focused on alway”. Can I apply Tabs Methods into the prechat object as a Fuction or is not possible?

  37. Hi Peter

    Very nice article on the pre chat api. Thanks for sharing it.
    I am not able to set the client’s name using the merge field {!LiveAgent_VisitorName}. So when a chat starts, the agent doesn’t get to know with whom he is talking. Though I am using the merge field in my Chat Button, but it is coming as blank.

    Need your suggestion here.


    1. Amrender, I was looking for the same thing awhile back and found this how-to. It worked for me.
      Live Agent : How to display a visitor’s name in Agent’s Chat window using pre-chat form?
      Knowledge Article Number: 000206052

  38. Hi ,

    I am trying to create a case with prepopulated value. I have 2 deployment one for cancellation and one for registration with 2 different skills. I am giving this as a drop-down in my pre-chat form. Whatever the user select the same value needs to populated on a picklist field. So, if in the pre-chat form user selects cancellation, then the picklist of the case should be cancellation. I am passing the id’s from the deployment as the dropdown here. But it is not working.

    Please help


    1. Hi Abhi,

      Did you ever figure out a way to map the value from your drop-down on the pre-chat form to the Chat details page?


  39. Hi Peter,

    Is there a possibility of setting page dependent custom details in deployment api and passing them over to pre-chat form where we combine them with form dependent custom details and make a record for Case? I want information to be collected from deployment API but not map them immediately. I want to pass them on to the pre-chat page where i can gather some more information and finally map them to a case record.

  40. Hi Peter,

    thanks for the blog.
    I have an issue: I have created a page (for example: “RedirectingPage”). In this page I want to redirect the users on the LiveAgent chat. Hence, instead of putting the startChat(…) on the “onClick” I want just to put the code to automatically open the chat once you go on that page.

    This page should redirect on the LiveAgent chat.

    window.alert(“Stai per essere reindirizzato sul LiveAgent.”);

    //delete Array.prototype.toJSON;

    // info I need when the chat opens:
    liveagent.addCustomDetail(“IdAOL”, new Date().getTime());
    liveagent.findOrCreate(“Info__c”).map(“ID_AOL__c”, “IdAOL”, false, false,true);
    liveagent.findOrCreate(“Survey_Operatore__c”).map(“ID_AOL__c”, “IdAOL”, false, false,true);

    liveagent.init(‘’, ‘572250000008OKV’, ’00D25000000DJeh’);
    // ————————————————————– the guilty!!
    liveagent.startChat(‘573250000008OLT’, true);



  41. Hi Peter,

    Thank you so much for this post, it has been extremely pivotal in my LiveAgent implementation. I have used an adapted version of your pre-chat form that only creates/maps to case (since our org already has triggers in place that create accounts/contacts for orphan cases hinging off of the customer’s supplied info)

    My only issue is that I am trying to write the email input from the pre-chat form as the Web Email / SuppliedEmail. The other web/supplied field I am writing to works fine, but for some reason the email does not populate on the case. Do you have any advice here? I have heard that SuppliedEmail can be tricky to work with.

  42. Hi Peter,

    Do you have any idea how to display a different auto greeting when a chat is transferred?

    By default, when a chat is transferred, the customer sees again the same auto greeting as at the beginning of the chat. This is annoying for the customers as they have the feeling that they have to provide again the same information they have already provided to the first agent, not knowing that the new agent can already see that information.

    I hoped to have a workaround by having different greetings in the Live Agent Configuration and Live Agent Button and to have the Configuration’s greeting when the chat is transferred, but looks like the greeting of the Live Agent Button from which the chat was initiated prevails over the Configuration’s greeting.


  43. Hi Peter

    The case is created only when an agent clicks Accept button . What i want is like case should also be created when agent does not clicks accept Button .

  44. Hi,
    I want to implement live agent in non-salesforce site with two skills
    so How many buttons I have to use and how to configure the chat from sales to sales agents and chat from support to support users
    How to keep validation on pre-chat form.

    Please help anyone.

      1. Thanks for your reply Alex Brady,

        So I need to use Two buttons,two deployments in one .html page and two pre-chat forms with two different url in Pre-Chat Form URL field in salesforce .Is it right?

        1. No problem!

          Unless you want to have different permitted domains, transcript saving permissions, or branding images, you can also use one deployment across both. If you’re gathering the same information from both your sales/support users, you should also be able to use one pre-chat form as well. (For example, if you just want a generic name/email/subject)


  45. Hi Peter,

    I created two buttons with two different skills and copied the button code & save as button.html for this I got one doubt that we have to create and copy two deployment codes or else only one will sufficient.
    Please respond immediately I have to solve this problem bcoz when we click on online it show connection lost error.

  46. Hi Peter,
    Thank you for the post. I am trying to test the pre chat form from my demo org. When I put the pre chat code in a visualforce page and refer ( in the pre chat url, the window works fine. However, is there a way to provide a local .html file path and get this working instead of hosting the pre chat page some where?

  47. Hi Peter, Your code looks like my code and it is not creating the case record. Do you recognize anything that I am missing?

    body { background-color:#F7F8F8 }
    #siteHeader { background-color:#333; display:block; }
    #nav { display:block; margin:0px auto; padding:10px; line-height:32px; font-size:24px; width:113px; }
    #prechatForm { margin:10px auto; display:block; width:200px; }
    #prechatForm .label { display: block; font-weight: 700; margin: 0 0 5px; }
    #prechatForm input { display: block; margin: 0 0 5px; width:200px; }
    .required { color: #999; }
    #prechatForm .submit { width:48%; background-color: #26AF3A !important; display: inline-block; padding: 0.3rem !important; font-size: 1em; font-family: Arial; border-radius: 3px; border-width: 0px; color: #fff; }
    #prechatForm .cancel { width:48%; float:right; background-color: #6D7391 !important; display: inline-block; padding: 0.3rem !important; font-size: 1em; font-family: Arial; border-radius: 3px; border-width: 0px; color: #fff; }

    (function() {
    function handlePageLoad() {
    var endpointMatcher = new RegExp(“[\\?\\&]endpoint=([^&#]*)”);
    if (window.addEventListener) {
    window.addEventListener(‘load’, handlePageLoad, false);
    } else {
    window.attachEvent(‘onload’, handlePageLoad, false);

    First Name: (required)

    Last Name: (required)

    Email: (required)

    Organization: (required)


    <!– –>

    <!– –>

    <!– –>

    Thank you so much for your help.

    1. So I’m implementing the pre-chat form with a Visualforce page. I’ve got:

      (function() {
      function handlePageLoad() {
      var endpointMatcher = new RegExp(“[\\?\\&]endpoint=([^&#]*)”);

      and so on. I’m wondering where this stuff goes (from your example above):

      body { background-color:#F7F8F8 }
      #siteHeader { background-color:#333; display:block; }
      #nav { display:block; margin:0px auto; padding:10px; line-height:32px; font-size:24px; width:113px; }
      #prechatForm { margin:10px auto; display:block; width:200px; }
      #prechatForm .label { display: block; font-weight: 700; margin: 0 0 5px; }
      #prechatForm input { display: block; margin: 0 0 5px; width:200px; }
      .required { color: #999; }
      #prechatForm .submit { width:48%; background-color: #26AF3A !important; display: inline-block; padding: 0.3rem !important; font-size: 1em; font-family: Arial; border-radius: 3px; border-width: 0px; color: #fff; }
      #prechatForm .cancel { width:48%; float:right; background-color: #6D7391 !important; display: inline-block; padding: 0.3rem !important; font-size: 1em; font-family: Arial; border-radius: 3px; border-width: 0px; color: #fff; }

      My main objective is to set the size of the pre-chat form pop-up.

  48. Hi,
    I implemented liveagent in sandbox nw we are deploying everything into production by changset.
    In changeset components can I add my buttons,skills which is created for liveagent are I supposed to create new button,skills,deployments for new ids in production bcoz there is mis match in ID’s for button,deployment which we are using.

    Please help anyone it’s urgent.


  49. Here is a problem i have two chat button with pre form url. One is working fine other giving me error that chat can only be launched from button. If i make both button url same they work fyn

  50. How do you make the name and email fields required on the prechat page? I’ve tried a lot of different things but the customer can still hit chat without filling in any information.

  51. Hi Peter,
    thank you for your guide. I have a question: how can you created html form? did you create it in Salesforce as a visualforce page? or did you create it in your local machine?

  52. Hi Peter,

    Can you please help me with this requirement:

    1) I want to search for the case number first ( there is a field on the pre chat form where the customer can fill in the case number) and pop the case page if there is a match.

    2) If there is no match, search should happen on the person account email ( there is a field on the pre chat form where the customer can fill in the email) and pop the account page.

    Can you provide a code snippet which covers both the above points.

  53. Hello Peter,
    Is there a way to set the chat window name to the visitor name instead of the default IP address appearing in salesforce?

    1. Use Javascript. This might not be the most efficient way of doing this but…

      document.title = liveagent.chasitor.getDetails().prechatDetails.filter(function(obj){ return obj.label === “FirstName”; })[0].value;

  54. Invaluable writing . BTW , if anybody requires to combine PDF files , my friend found piece here

  55. For the love agent chat i am not able to auto populate case values . when a case from client side contact get created for that client but case values do not get auto populate. pLease help me and let me know why case values are not auto populating.

  56. Hi,

    I have the same requirement like above exanple,i have copied the same code and pasted in vf page, when I click the submit button pop-up is not opening .
    I am new to liveagent concept
    Please suggest me on it, it is little urgent


  57. I have to implement same in napili community page , but finding issues with it, I have created button in lightning and kept onclick url to prechat visual force page , I’m able to open prechat page , but on submission of details and click on chatnow, nothing happening ,can you please guide me on this where I’m going wrong

  58. Need the Chat Button to live on the Prechat form

    All this while I have seen and played around with the chat button to open up the pre-chat form and then send the chat request out to the agent but my needs are the opposite now- My clients need a way in which the help form(which acts like the pre-chat form) should display the live chat button if an agent is available to chat. I have created a sample pre-chat form in html, also embeded the chat button code on the same page which displays if the agents are online, but how do I make the javascript logic work so that when the form is submitted(upon clicking on Chat Now) the chat button should carry forward the information to the Liveagent.

    1. Hi NJ – what you are describing is out-of-box functionality. The button is greyed out if no agent is available for chat, and becomes available the first time an agent becomes available (for the skill linked to your chat button)

      The best way I can suggest to learn how to enable live chat, other than Peter’s bog posts, is to take the following trailhead modules whcih take you step-by-step through the setup:
      you might also want to take this module first:

  59. I am trying to implement a pre-chat page where the customer can provide a case number and then the chat would open the existing case if found. If no matching case is found, the process should create a new case.

    This is the code snippet that tries to find a match:

    This is the code that creates a new case if not found, immediately following the above:

    Finally, the case, new or recovered, is linked to the transcript:

    This works fine if a matching case is found.

    But if no match is found, a new case is not created.

    If I comment out the code checking for CaseNumber match, the new case is created correctly.

    Any ideas?

  60. Nice to see this thread is still alive after a couple of years – good work Peter.

    I can get the chat button to work and I can get the pre-chat form to work. Of course my requirements differ just a bit.

    My support user is in SFDC Service console. My end user is logged in to an SFDC customer community. There is no guest or visitor access permitted. So in this situation we know who the end user is. I would like to pick up the contact ID based upon the user being logged into the community and do the balance of the work illustrated in the pre-chat (creating the case that sort of thing) – I just don’t want to have to ask the user who they are because technically we should know 100% of the time.

    Anyone ever try this?

    1. We had ours in the portal… Maybe community is similar.

      I think all you need is {!$User.FirstName} in your Visualforce page. Here’s what I did for ours. We also needed to check the contact had signed up to pilot live agent with us.

      Hello {!$User.FirstName}

      button code goes here

      deployment code goes here

  61. Hi Experts,

    Is it possible to hide certain details like (Visitor Details from the details page — IP address , Screen Resolution .. Network ) from the pre chat page.

  62. Hi Peter, Hi all, hope someone can help me with problem I’m having with Live Agent since february.
    in our org we have live agent enabled and 3 agents to answer the incoming chats. All of the 3 agents have the same profile.
    When a agent receive a chat request through the ‘prechat’ page a Lead, a Person Account and a Case are created in SF.
    The agents should then see the chat tab plus a another tab with the Lead and the chat details (transcript) (see screenshot ‘correct’). At the end of the chat from the agent side a Transcript is created, with a linked Case and Lead.
    Since Monday 13/02/2017 for two of our agents in the ‘chat page’ they see only the chat and chat details tab, not the Lead tab. At the end of the chat the Transcript is saved but it isn’t linked to any other Case nor Lead.
    We saw that all of this is cause at the start of the chat the Lead isn’t created anymore.

    We tried to analyze the debug logs but when the error appears the only thing recorded is an insignificant debug log with no details that can help me to troubleshoot the issue.

    In the last months or more we didn’t modify anything about Live Agent or about the Profile of the Agents. We also can’t comprehend how is it possible that 2/3 of our agents are having problems and the other one have no problems at all.

    Is it possible that during the Spring ’17 there were changes that disrupted our Live Agent implementation? What can we do to track down the error and fix it?
    Thank you in advance
    Maria Alberti

  63. Hi,

    We have a requirement within Live Agent, wherein after the Customer has hit the Start Chat button(which is visible when an agent is online) to accept Terms & Conditions before the chat is actually routed to an agent.

    I know this maybe doable in a pre-chat form which happens before the Customer hits the Start Chat. However I am not sure if we can introduce a pop up or some kinda VF page between the Start Chat and the Agent finally seeing the chat request.

    Please let me know if there is any way to achieve this..


  64. Hello Peter,

    How will the pre Chat form be displayed? Is it when the user clicks on Chat now from Chat Button page then the Pre Chat page will be displayed first?
    Can I test these both the pages from my desktop if I dont have a external website?

  65. Hi Peter,

    How can we pull the records from the 2 objects on accepting the chat by Live Agent.
    Below is my JSON format which I am using to pull the records in the pre-chat details. It is perfectly working for one record to pull. when I add code to pull 2 records, I am getting the ERROR : An Internal Server Error has occurred.

    JSONGenerator Jsongen = JSON.createGenerator(true);
    gen.writeStringField(‘organizationId’, ‘Test Id’);
    gen.writeStringField(‘deploymentId’, ‘Test Id’);
    gen.writeStringField(‘buttonId’, ‘Test Id’);
    gen.writeStringField(‘sessionId’, ‘Test Id’);
    gen.writeStringField(‘userAgent’, ‘Test User’);
    gen.writeStringField(‘language’, ‘en-IND’);
    gen.writeStringField(‘visitorName’,’Test visitor’);

    /*** Pre-chat Value – Phone Number – Start ***/
    gen.writeStringField(‘label’, ‘Phone Number’);
    gen.writeStringField(‘value’, ‘98765436454’);
    gen.writeStringField(‘entityName’, ‘Account’);
    gen.writeStringField(‘fieldName’, ‘Phone’);
    gen.writeBooleanField(‘isFastFillable’, false);
    gen.writeBooleanField(‘isAutoQueryable’, true);
    gen.writeBooleanField(‘isExactMatchable’, true);
    gen.writeBooleanField(‘displayToAgent’, true);
    /*** Pre-chat Value – Phone Number – End ***/

    /*** Pre-chat Value Email – start ***/
    gen.writeStringField(‘label’, ‘Email’);
    gen.writeStringField(‘value’, ‘’);
    gen.writeStringField(‘entityName’, ‘Contact);
    gen.writeStringField(‘fieldName’, ‘Email’);
    gen.writeBooleanField(‘isFastFillable’, false);
    gen.writeBooleanField(‘isAutoQueryable’, true);
    gen.writeBooleanField(‘isExactMatchable’, true);
    gen.writeBooleanField(‘displayToAgent’, true);
    /*** Pre-chat Value Email – End ***/

    gen.writeBooleanField(‘receiveQueueUpdates’, true);
    gen.writeBooleanField(‘isPost’, true);

  66. Hi Peter,

    While using your pre chat api code I’m getting method not exist 405 error.

    kindly explain me the issue I’m facing .


  67. Hi Peter ,

    Could you please me troubleshoot this issue.
    Denver users are not able to auto generate cases nor auto associate chats.
    However , this works perfectly fine for other location users .
    Could you please advice.

  68. Hi Peter,
    which URL we need to give on Prechat-form URL, currently we are not using sites, BUT our website is external website, which is in .Net, if i want to test this code in on My side before putting in to the external website which local url i need to use? what are all the prerequisites it would be very much helpful for me.

  69. Thank you for the code it puts the first name/last name email/subject and request chat on my site but the request chat button doesn’t direct me into the chat and when i use my chat with us the details put in don’t show up on the agents side

  70. how to do in live agent form.
    that Does not auto create case or contact, but could search for contact record and auto populate case fields without saving case record.

  71. I’ve been trying to map a custom pre-chat filed so that it is saved on to the chat transcript but haven’t been successful in getting it to save as such.

    I created the input detail:

    and added the map to the chat transcript.

    but the value from pre-chat protocol never saves.

    Any thoughts on where I’m going wrong?

  72. Sorry had to add quotes around my code.

    I’ve been trying to map a custom pre-chat filed so that it is saved on to the chat transcript but haven’t been successful in getting it to save as such.

    I created the input detail:
    ” Protocol:

    and added the map to the chat transcript.


    but the value from pre-chat protocol never saves.

    Any thoughts on where I’m going wrong?

  73. Ok last time hopefully removing html tags fixes the post
    I’ve been trying to map a custom pre-chat filed so that it is saved on to the chat transcript but haven’t been successful in getting it to save as such.

    I created the input detail:
    label style=”margin: 50px;font-size: 125%;” for=”Protocol_Name_Number__c”>Protocol:
    input style=”margin-left: 18px;” type=’text’ name=’liveagent.prechat:Protocol_Name_Number__c’

    and added the map to the chat transcript.

    input type=”hidden” name=”” value=”Protocol_Name_Number__c”

    but the value from pre-chat protocol never saves.

    Any thoughts on where I’m going wrong?

Leave a Reply

Your email address will not be published. Required fields are marked *