Adding in or changing the customer default information that is displayed on the right hand panel of your Groove inbox is easy with the widget API.

In addition to updating the Groove default fields, you can also pass through additional values to the Custom Fields you have created in your Groove Account which displays on the right hand panel of your inbox.

Note:

Anonymous VS Identified Users

In order to update the Custom Fields for Contacts and Companies in your Groove account, you first need to identify the user.

The advanced API behaves slightly differently for anonymous and identified users. We’ll outline how this varies for each feature in their respective documentation. First let’s define exactly what we mean by an anonymous and an identified user.

Anonymous Users

Anonymous users are users that have no unique identifying information on the server or the client. They might have a session ID generated in the browser but there is nothing on the server to identify them for setting Custom Field information to the correct Contact / Company.

Identified Users

Identified users have one or more identifiers that can be used to tie the information passed through the API to the correct user. This might be an email, social media handle, or an ID for a user account on your web site or application. 

To identify the user you will need to provide a custom field key that corresponds to a custom field that is defined as a unique custom field in you CRM settings.

The default fields that you can use are:

  • contact_email
  • contact_secondary_emails
  • contact_facebook
  • contact_twitter

Here is how you identify a user

/* Contact Email */
groove.widget.identifyContact('contact_email', 'fred@example.com')

/* Contact secondary email */
groove.widget.identifyContact('contact_secondary_emails', 'fred.flintstone@example.com')

/* Contact Facebook */
groove.widget.identifyContact('contact_facebook', 'the-flintstones')

/* Contact Twitter */
groove.widget.identifyContact('contact_twitter', 'fredflintstone')

 

Setting Custom Fields To Contacts

You can set custom field values for an identified user using the grooveWidget.setContact() function:

groove.widget.setContact(properties: Object)

Note: Any values for Custom Fields that do not exist in your CRM settings will be silently discarded. To create Custom Fields, you can view this article here.

/* First identify the user */
groove.widget.identifyContact('contact_email','tak@envoys.com')

/* Next, set the contact properties */
groove.widget.setContact({
  contact_first_name: 'Takeshi',
  contact_last_name: 'Kovacs',
  contact_address: {
    street: 'The Raven',
    city: 'Bay City',
    state: 'California',
    postal_code: 94110,
    country: 'The Protectorate',
  },
})

It is not possible to set properties on an anonymous user. If you call grooveWidget.setContact before grooveWidget.identifyContact the
values will be stored locally and not parsed to the server. As soon as you call grooveWidget.identifyContact any previously defined values will be sent to the server.

Updating Different Field Types

Custom fields are created with a set type, which helps ensure data sanitization. As this is the case, the different property types expect different objects passed to it:

/* First identify the user */
groove.widget.identifyContact('contact_email', 'tak@envoys.com')

/* Example of different types */
groove.widget.setContact({
  // Single line type
  contact_role: 'CEO',

  // Multi line type 
  contact_description: 
        "Tak is the CEO of Envoy Industry, \n
         a multinational spanning the APAC region",

  // Date type (in ISO 8601 format, i.e. YYYY-MM-DD)
  contact_dob: '1980/02/24',

  // Address type
  contact_home_address: {
    street: '1 Main street',
    city: 'Bay city',
    state: 'California',
    postal_code: 94110,
    country: 'USA',
  },

  // Link type
  contact_blog_url: {
    link: 'https://www.google.com',
    text: 'Google',
  },

  // Number type
  contact_personal_cell: '+15558234312',

  // Dropdown type
  contact_gender: 'Male',
})

 

Updating Company Values

Updating company values works exactly in the same manner as updating the contact values above.

First you need to identify the company, and then can subsequently update fields for the identified company.

If you have identified both the company and the contact the contact will be added to the company automatically.

To identify the company you will need to provide a custom field key that corresponds to a custom field that is defined as a unique field in you Custom Field settings. The default fields that you can use include:

  • company_domain
  • company_secondary_domains
  • company_facebook
  • company_twitter
  • company_linkedin

Here is an example of identifying and setting the custom fields of a company:

/* Identify the company */
groove.widget.identifyCompany('company_domain', 'envoys.com')

/* Set company properties */
groove.widget.setCompany({
  company_name: 'The Envoys',
  company_description: 'Envoys, powering the future!',
})

 

FAQ's

Contact Or Company Not Found

If a contact for the provided key and value cannot be found one will be created and the provided value will be set automatically.

Re-identifying Users And Logout

Calling grooveWidget.identifyContact or grooveWidget.identifyCompany multiple times will change the stored custom field value used to identify the contact and/or company (unless that new value is already set on the same user in the CRM contact) start pushing that data to a different contact profile.

If you wish to start using a new value for the same user use grooveWidget.setContact to update the new field value using the existing
one. If you are re-identifying as a different contact all the existing session and properties kept in local storage will be remain.

If you want to clear all of this use grooveWidget.logout() .