Live Agent Deployment API

Introduction

In this blog, I am going to explain how to use the live agent deployment API  to find and create records and how to customize chat buttons and chat window. Live agent deployment API has the number of options to customize the live agent like Logging and controlling the live agent online and offline behaviors and allow automatically creating records and suggest the knowledge article etc. Below is the code from where you will launch your live agent normally it might be your webpage or visual force page from sites etc.

<apex:page sidebar="false">
    <head>
        
        <style> body { margin: 25px 0 0 25px; } </style>
        
         
        
    </head>    
    <body>
        <!--Deployments-->
        <script type='text/javascript' src='https://c.la1-c1-iad.salesforceliveagent.com/content/g/js/41.0/deployment.js'></script>
        <!--Chat Buttons & Invitations -->
        <!--Customize Chat Buttons with the Deployment APIs-->
        
        <img id="liveagent_button_online_5736A000000gBrn" style="display: none; border: 0px none; cursor: pointer" 
             onclick="liveagent.startChat('5736A000000gBrn')" src="https://5dfg34-developer-edition.na50.force.com/resource/1505938566000/ttttteee__Chat_Agent_Online" />
        <img id="liveagent_button_offline_5736A000000gBrn" style="display: none; border: 0px none; " 
             src="https://5dfg34-developer-edition.na50.force.com/resource/1505938566000/ttttteee__Chat_Agent_Online" />
        <script type="text/javascript">
        if (!window._laq) { window._laq = []; }
        window._laq.push(function(){liveagent.showWhenOnline('5736A000000gBrn', document.getElementById('liveagent_button_online_5736A000000gBrn'));
                                    liveagent.showWhenOffline('5736A000000gBrn', document.getElementById('liveagent_button_offline_5736A000000gBrn'));
                                   });</script>
        
        <script type='text/javascript'>
        /* Adds a custom detail called Contact Email and sets it value to testuser@gmail.com */
        liveagent.addCustomDetail('Contact E-mail', 'testuser@gmail.com');
        
        /* Creates a custom detail called First Name and sets the value to test */
        liveagent.addCustomDetail('First Name', 'test');
        
        /* Creates a custom detail called Last Name and sets the value to user */
        liveagent.addCustomDetail('Last Name', 'user');
        
        /* Creates a custom detail called Phone Number and sets the value to 415-555-1212 */
        liveagent.addCustomDetail('Phone Number', '415-555-1212');
        
        /* An auto-query that searches Contacts whose Email field exactly matches 'testuser@gmail.com'. If no result is found, it will create a Contact record with the email, first name, last name, and phone number fields set to the custom detail values. */
        liveagent.findOrCreate('Contact').map('Email','Contact E-mail',true,true,true).map('FirstName','First Name',false,false,true).map('LastName','Last Name',false,false,true).map('Phone','Phone Number',false,false,true);
        
        /* The contact that's found or created will be saved or associated to the chat transcript. The contact will be opened for the agent in the Console and the case is linked to the contact record */
        liveagent.findOrCreate('Contact').saveToTranscript('ContactId').showOnCreate().linkToEntity('Case','ContactId');
        
        /* Creates a custom detail called Case Subject and sets the value to 'Refund policy for products' and will perform a knowledge search when the chat is accepted for the agent */
        liveagent.addCustomDetail('Case Subject','Refund policy for products').doKnowledgeSearch();
        
        /* Creates a custom detail called Case Status and sets the value to 'New' */
        liveagent.addCustomDetail('Case Status','New');
        
        /* This does a non-exact search on cases by the value of the 'Case Subject' custom detail If no results are found, it will create a case and set the case's subject and status.
The case that's found or created will be associated to the chat and the case will open in the Console for the agent when the chat is accepted */
        liveagent.findOrCreate('Case').map('Subject','Case Subject',true,false,true).map('Status','Case Status',false,false,true).saveToTranscript('CaseId').showOnCreate();
        
             liveagent.addCustomDetail('InquiryDetails', 'Suport').saveToTranscript('Inquiry_Details__c');

        /* For internal or technical details that don't concern the agent, set showToAgent to false to hide them from the display. */
        liveagent.addCustomDetail('VisitorHash', 'c6f440178d478e4326a1', false);
        
        /* Sets the display name of the visitor in the agent console when engaged in a chat */
        liveagent.setName('Test User');
        
        /* Sets the width of the chat window to 500px */
        liveagent.setChatWindowWidth(10);
        
        /* Sets the height of the chat window to 500px */
        liveagent.setChatWindowHeight(10);
        
        liveagent.init('https://d.la1-c1-iad.salesforceliveagent.com/chat', '5726A000000gPLj', '00D6A000000vnuz');
        liveagent.enableLogging();
        
        </script>
        
        
    </body>
    
    
</apex:page>

Understand the code

Live agent logging will be very useful if you wanted to troubleshoot the live agent. You can enable the Logging by simple liveagent.enableLogging(); the method which results in the debugging as shown below on browser console.

The below piece of code shown what to do when the agent is online or offline.The showWhenOnline or showWhenOffline method to specify customers see when a particular button is online or offline based on the agent status. the below code we specify the button id to show the status  liveagent_button_online_5736A000000gBrn , liveagent_button_offline_5736A000000gBrn  .

liveagent.showWhenOnline('5736A000000gBrn', document.getElementById('liveagent_button_online_5736A000000gBrn'));

liveagent.showWhenOffline('5736A000000gBrn', document.getElementById('liveagent_button_offline_5736A000000gBrn'));

The below code request a chat from a button in a new window when you click on chat button by calling liveagent.startChat method.

<img id="liveagent_button_online_5736A000000gBrn" style="display: none; border: 0px none; cursor: pointer" 
             onclick="liveagent.startChat('5736A000000gBrn')" src="https://5dfg34-developer-edition.na50.force.com/resource/1505938566000/ttttteee__Chat_Agent_Online" />

Find and Create Records
Use the Deployment API to search for or create Salesforce records like a case, contact, account, or lead automatically when an agent begins a chat with a customer.addCustomDetail methods as  Adds a new custom detail for the chat visitor.

   /* Adds a custom detail called Contact Email and sets it value to testuser@gmail.com */
        liveagent.addCustomDetail('Contact E-mail', 'testuser@gmail.com');
        
        /* Creates a custom detail called First Name and sets the value to test */
        liveagent.addCustomDetail('First Name', 'test');
        
        /* Creates a custom detail called Last Name and sets the value to user */
        liveagent.addCustomDetail('Last Name', 'user');
        
        /* Creates a custom detail called Phone Number and sets the value to 415-555-1212 */
        liveagent.addCustomDetail('Phone Number', '415-555-1212');

The Custom Detail is displayed to agents in the footer widget and in the Chat Details page in the Salesforce Console while the chat is active as shown below.

 

Use the findOrCreate method to find existing records or create new ones based on certain criteria. The findOrCreate method begins the API call that finds existing records or creates new records when an agent begins a
chat with a customer. The below code show to find and create records and store it to the live agent transcript and suggesting the knowledge articles.

  /* An auto-query that searches Contacts whose Email field exactly matches 'testuser@gmail.com'. If no result is found, it will create a Contact record with the email, first name, last name, and phone number fields set to the custom detail values. */
        liveagent.findOrCreate('Contact').map('Email','Contact E-mail',true,true,true).map('FirstName','First Name',false,false,true).map('LastName','Last Name',false,false,true).map('Phone','Phone Number',false,false,true);
        
        /* The contact that's found or created will be saved or associated to the chat transcript. The contact will be opened for the agent in the Console and the case is linked to the contact record */
        liveagent.findOrCreate('Contact').saveToTranscript('ContactId').showOnCreate().linkToEntity('Case','ContactId');
        
        /* Creates a custom detail called Case Subject and sets the value to 'Refund policy for products' and will perform a knowledge search when the chat is accepted for the agent */
        liveagent.addCustomDetail('Case Subject','Refund policy for products').doKnowledgeSearch();
        
        /* Creates a custom detail called Case Status and sets the value to 'New' */
        liveagent.addCustomDetail('Case Status','New');
        
        /* This does a non-exact search on cases by the value of the 'Case Subject' custom detail If no results are found, it will create a case and set the case's subject and status.
The case that's found or created will be associated to the chat and the case will open in the Console for the agent when the chat is accepted */
        liveagent.findOrCreate('Case').map('Subject','Case Subject',true,false,true).map('Status','Case Status',false,false,true).saveToTranscript('CaseId').showOnCreate();
        
        /* Saves the custom detail to a custom field on LiveChatTranscript at the end of a chat.  Assumes a custom field called Company__c was added to the Live Chat Transcript object */
        liveagent.addCustomDetail('InquiryDetails', 'Suport').saveToTranscript('Inquiry_Details__c');

In the above code, we are trying o find the contact and if not available the create a new contact also searches for records that contain customer data specified by the addCustomDetail Deployment API method.  findOrCreate.saveToTranscript method to save the record you find or create the chat transcript associated
with the chat. Use the findOrCreate.showOnCreate method to automatically open the record you create in a subtab in the Salesforce console.   findOrCreate.linkToEntity method to link the record you found or created to another record type. The below image shows the search results on the console chat

 

liveagent.addCustomDetail(‘Case Subject’,’Refund policy for products’).doKnowledgeSearch() method search for Knowledge articles as shown below when customer is chat with agent.