Overview

By enabling authentication through contact insight OAuth security layer, the contact insight web application can be accessed externally from Campaign and embedded in host applications. Embedded inside a host application, the contact insight application is available on contact and lead forms.

At a high level, integrating contact insight with your host application involves the following steps.

1. Create an application in Acoustic Campaign
2. Configure your organization to enable contact insight
3. Construct the contact insight URLs

Contact insight integration requirements and methods

Integrator requirements

To install and configure contact insight, the embedded contact insight application within the host application must meet some of these requirements:

• Contact insight must be accessible from the individual CRM lead and contact screens when the lead or contact record is synced within Campaign.
• The contact insight endpoints must be configurable by the admin end user.
• Contact insight has the capability to proactively fetch a new access token in advance of the existing token's expiration. When you are requesting a new access token, the response message includes the access token and the amount of time (in seconds) before the access token expires.
• The host proactively acquires the new access tokens prior to the existing token's expiration date to avoid problems with the embedded URLs in the application that is breaking due to using the old token. Complete the following steps to acquire the new access token.
  • Divide the access token's number of seconds before it expires in half, then add it to the current time stamp and store it as the renewal time.
  • When the renewal time passes, initiate the process again to get a new access token.
  • If this approach is unsuccessful, then the host application must retry until the original access token truly expires.
  • If the current access token expires and no new ones can be granted to the host, the appropriate users must be notified of the situation.

• Display the content that is returned from Campaign just below the contact or lead information in the host application.

Integration methods

Read through the following section to understand the two integration methods that are used by contact insight.

Get Access Token

This method is used to retrieve a valid (time-limited) access token that can be used to get the contact insight application for an individual contact or lead. The HTTP POST requires the following parameters:

HEADER End Point: https://[Acoustic Campaign Server Address]/oauth/token

BODY:

• Parameter1: grant_type=refresh_token.
• Parameter2: client_id=Acoustic Campaign-provided client Id for contact insight (to be protected).
• Parameter3: client_secret=Acoustic Campaign-provided client secret for contact insight (to be protected).
• Parameter4: refresh_token=the refresh token that is sent to the integration user who is granted contact insight access.

Get contact insight

This method is used to retrieve the HTML-based contact insight application for an individual contact or lead. Since HTTP GET is permitted on this method, a simple URL with parameters can be used. If the HTTP GET method is used, the URL approach must look like one of the following examples:

• Contact insight through the CRM sync ID:

   https://[Acoustic Campaign Server
      Address]/mashup/oauth/contact/contactInsight?sync_id=[the contact's unique
      CRM Id used for the integration]&listId=[Engage CRM Database List Id]&access_token=[the
      access_token from getAccessToken]

• Contact insight through the Campaign recipient ID:

  https://[Acoustic
      Campaign Server Address]/mashup/oauth/contact/contactInsight?recipientId
      =[the contact's unique Acoustic Campaign Id that is used for the integration]&listId=[Acoustic
      Campaign CRM Database List Id]&access_token=[the access_token from above
      process].

Note: If the host prefers, a HTTP POST can be used to retrieve the HTML response data. In that case, the HTTP POST method would be constructed in the same as in the Get Access Token section.

Configure contact insight integration

Read through the following topic to understand how the contact or lead synchronized with Campaign in the host CRM application.

Complete the following steps to configure the contact insight integration.

1. Check to see whether an access token is stored in the host application. If not, check to see whether the contact insight integration is set up and the tokens are stored. If not, pass a null string to the contact insight endpoint URL and let the application render the result. Notifying the end user admin is at the discretion of the integrator.
2. Invoke a HTTP POST to the Campaign authorization server requesting a new access token by providing the Client Id, Client Secret, and Refresh Token in the BODY of the HTTP POST.
3. Take the new access token's expiration time, add that to the current timestamp, and store it as the expired time for the access token.
4. Determine whether the stored access token for contact insight passed its renewal time. If so, repeat Step 1.
5. Construct a URL by using a valid access token and a contact's CRM's sync ID or Campaign recipient ID.
   1. Contact insight through the Campaign recipient ID: https://[Acoustic Campaign Server Address]/mashup/oauth/contact/contactInsight?recipientId =[the contact's unique Acoustic Campaign Id that is used for the integration]&listId=[Acoustic Campaign CRM Database List Id]&access_token=[the access_token from above process].
   2. Contact insight through the CRM sync ID: https://[Acoustic CampaignServer Address]/mashup/oauth/contact/contactInsight?sync_id=[the contact's unique CRM Id that is used for the integration]&listId=[Acoustic Campaign CRM Database List Id]&access_token=[the access_token from above process].

Note: The URLs are case-sensitive.

6. Pass the URL to either the host application's standard web site that is rendering the object or to an iFrame.
7. Display the returned HTML in the embedded contact insight view in the host application.

Contact insight integration endpoints

Contact insight endpoints must be configured in such a way that the URL component can be changed at the runtime to accommodate the future changes to the service. The endpoint consists of server address, method, and query parameters.

Server Address

The server address element of the URL is the address of the Campaign pod where the host's database instance resides. Select the appropriate address for the host's database:

Method

The method element of the URL is the instruction communicating method to be used by the server. There are two main methods for contact insight:

• https://endpoint/oauth/token that is used to acquire a valid access token.
• https://endpoint/mashup/oauth/contact/contactInsight that is used to get the contact insight application.

The query parameters consist of more than one part, including the number of oAuth tokens and necessary parameters that the method needs to properly execute its function.

• The getAccessToken method must be invoked by using a HTTP POST and embed the parameters into the BODY of the request.
• The contactInsight method can be invoked by using HTTP GET by constructing the URL with the parameters that are embedded in the connect string.