Back to top

CRM Integration Documentation

Introduction

Overview

Sparkcentral CRM integration provides a way to pull customer contact data from CRMs, or other internal business applications, into Sparkcentral. In order to integrate your CRM with Sparkcentral, you will need to provide an HTTPS endpoint for lookups. You can also provide an optional HTTPS endpoint for handling write back requests and an HTTP endpoint for Sparkcentral to send notifications from our application to your CRM.

Lookup

Create Contact Attributes

  1. Create contact attributes inside Sparkcentral (Settings -> Contact Attributes).

  2. In the Edit Attributes dialog box, mark attributes as Managed by CRM. The CRM will be the source of truth for these attributes. Once they are imported into Sparkcentral, they will only change when the value changes in the CRM.

  3. Identify lookup attributes. In the Edit Attributes dialog box, mark attributes Use as Lookup Attribute. These will be used by the CRM to find a customer’s data. For example, if you want to find the customer by email address, create an attribute called “Email” and designate it as a lookup. When the request is made from Sparkcentral to your CRM, the lookup field(s) will be included in the request body.

  4. Create an alias for the attribute. In the Edit Dialog box, enter an alias for the lookup attribute. This will be used to map the response from your system to the attribute.

Configure Integration URL

In order to pull data from your CRM into Sparkcentral, you will need to implement a POST endpoint that accepts a JSON request and returns a JSON response. The request contains the lookup attributes and the response should contain the contact data from your CRM. Each request will also contain a X-Sparkcentral-Signature in its headers. This will allow you to verify the call comes from Sparkcentral.

Once that endpoint is implemented, configure it as the Lookup URL in the Manage CRM dialog box (Settings -> Contact Attributes). When the Lookup URL has been configured, you will receive a secret key. Using this key you will be able to calculate the same signature as in X-Sparkcentral-Signature. This will confirm that the request originated with Sparkcentral.

Handle the Request

When the endpoint in your system is ready, configured in Sparkcentral, and one or more lookup attributes have been identified, you can make a request via the Lookup button in the Conversation view. Here’s what the request would look like:

curl -X POST https://<your-host>/sparkcentral-lookup -H 'content-type: application/json' -H 'accept: application/json' -H 'X-Sparkcentral-Signature: e6f93239a06e46ae9654fc9ad2fb4e1cc4eb213830a0d94e711570c047e43c57'
 -d '{"email":"fj@example.com"}'

The signature is generated using the HMAC-SHA256 algorithm using the shared secret and the request body. Use your secret to calculate the signature and compare with the given signature. Both the secret key you received and the signature are encoded as hexadecimal strings. Make sure to convert the shared secret from its hexadecimal representation to its binary format before using it. Most languages come with libraries out of the box to verify this signature. For example, here’s how it looks in Javascript:

const crypto = require("crypto");

const sparkcentralSecret = "..."; //do not share!
const expectedSignature = request.headers["X-Sparkcentral-Signature"];
const actualSignature = crypto
  .createHmac("sha256", Buffer.from(sparkcentralSecret, "hex"))
  .update(request.body, "utf-8")
  .digest("hex");

if (actualSignature !== expectedSignature) {
  throw new createError.Unauthorized("X-Sparkcentral-Signature wrong");
}

console.log(JSON.parse(request.body).email);

Once you’ve done the lookup in your system, pass attributes back to Sparkcentral as a JSON response. The keys in the attributes object correspond to the aliases that were previously added in Sparkcentral. If a CRM Managed attribute is missing from the object or the key has a null value, its value will be deleted in Sparkcentral. Sparkcentral expects the response in this format:

  • Response 200 (application/json)

    {
      "autoConfirm": false,
      "attributes": {
            "email": "fj@example.com",
            "id": "98765432",
            "first_name": "Fred",
            "last_name": "Jones",
            "last_order_number": null
          }
    }

Confirm Your Attributes

The CRM attributes sent back in the response need to be confirmed before they are saved in Sparkcentral. There are two ways to do that:

  1. Hit the Confirm button when you see the CRM attributes displayed in Sparkcentral after the lookup request.

  2. Add an autoConfirm field to the response:

  • Response 200 (application/json)

    {
      "autoConfirm": true,
      "attributes": {
            "email": "fj@example.com",
            "id": "98765432",
            "first_name": "Fred",
            "last_name": "Jones"
          }
    }

The autoConfirm field tells Sparkcentral to automatically save the attributes without having to use the Confirm button.

Writeback

Writeback

You can be notified whenever a conversation has taken place in Sparkcentral or an agent sets a current conversation to pending state. This allows you to save conversation details to your existing CRM system. Other use cases include triggering CSAT surveys, Case Creation, and expanded customer insights from social media profiles.

Configure Writeback URL

In order to push data from Sparkcentral into your CRM, you will need to implement a POST endpoint that accepts a JSON request and returns a JSON response. The request contains write back payload and the response’s status code represents your ability to parse the payload and the CRM’s ability to ingest the data. Each request will also contain a X-Sparkcentral-Signature in its headers. This will allow you to verify the call comes from Sparkcentral.

Configure the endpoint as the Write Back URL in the Manage CRM dialog box (Settings -> Contact Attributes). When the Write Back URL has been configured, you will receive a secret key. Using this key you will be able to calculate the same signature as in X-Sparkcentral-Signature. This will confirm that the request originated with Sparkcentral.

Handle the Request

When the endpoint in your system is ready, configured in Sparkcentral, and relevant events occur within Sparkcentral, requests will be sent to the configured endpoint. All decoded write back payloads have the following fields:

  • type : A string that defines what kind of write back request is being processed. Used to suggest the structure of the data field.

  • version : A number designating the version of the type of request. Used to mark changes to the data field structure.

  • idempotencyKey : A string that uniquely identifies each event to write back, to help ensure each request is processed only once.

  • data : An object that contains structured data for the specific type of write back. For example, a CONVERSATION_RESOLVED type event has fields such as medium, channel, messages*, notes, topics, contactProfile*, attributes* and agent, among others.

The request will also include a X-Sparkcentral-Signature which you can verify in the same way as for lookups.

* Applies to all mediums except Twitter. Twitter handle, tweets and DM transcripts, and Twitter medium contact attributes (e.g., Twitter Name, Number of followers etc) will not be sent in the payload in line with Twitter’s data use policies.

CONVERSATION_RESOLVED and CONVERSATION_SET_TO_PENDING Events

Events with a type of either ‘CONVERSATION_RESOLVED’ or ‘CONVERSATION_SET_TO_PENDING’ have the following data structure:

{
  "type": "CONVERSATION_RESOLVED",
  "version": 1,
  "data": {
    "medium": {
      "id": "twit"
    },
    "channel": {
      "id": "0-019a0b43ad3-000-471aa28a",
      "name": "twitter support channel"
    },
    "contactProfile": {
      "id": "0-01975d67fca-324-0a6a2cdb",
      "mediumContactProfileId": "3596363240",
      "primaryIdentifier": "hchavez016",
      "secondaryIdentifier": "Helen",
      "pictureUrl": "https://pbs.twimg.com/profile_images/645594530432711841/11icMBd__normal.png"
    },
    "conversation": {
      "id": "0-019a0f586a0-000-8506e8d2",
      "createdAt": "2018-06-28T00:17:07+00:00",
      "previousStatus": "new",
      "currentStatus": "resolved"
    },
    "statusUpdatedAt": "2018-06-28T00:17:12+00:00",
    "statusUpdatedReason": "agentResolved",
    "agent": {
      "id": "987654",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "test@email.com"
    },
    "contactAttributes": [
      {
        "attribute": "email",
        "value": "contact@email.com",
        "source": "CRM_CONFIRMED"
      },
      {
        "attribute": "test",
        "value": "contact2@gmail.com",
        "source": "CRM_UNCONFIRMED"
      },
      {
        "attribute": "rewards-number",
        "value": "11111111",
        "source": "AGENT"
      }
    ],
    "messages": [
      {
        "id": "cbag7408-b537-11e9-abb9-b1e2e0e67a09",
        "direction": "INBOUND",
        "text": "Can you help me?"
      },
      {
        "id": "abce7408-b537-11e9-bcb9-b1e2e0e67a09",
        "direction": "OUTBOUND",
        "text": "Of course, what do you need assistance with?"
      }
    ],
    "notes": [
      {
        "id": "8080a48b-3c70-11e1-8931-1e8999d73ad2",
        "text": "Here's a note on the conversation!",
        "creationUser": "0-019bd608cfc-001-0c6a2f5b",
        "creationTimestamp": "2018-06-28T00:17:09+00:00"
      }
    ],
    "topics": [
      {
        "id": "aa33389d-8a6a-11e8-b0d0-61f12b43ea29",
        "name": "Redeem Rewards"
      },
      {
        "id": "ee089cc2-8a6a-11e8-b0d0-942d249592dc",
        "name": "Account Rewards"
      }
    ]
  }
}

Write Back Retry

In case the write back request times out or the endpoint returns a non-success (2XX) status code, Sparkcentral will retry with exponential backoffs. The request will be sent again with a delay of 1, 2, 4, 8, 16, and 32 hours after each retry (a total of 6 requests) as long as the request continues to not succeed. If the request still has not succeeded after that timeframe, we store the failed request details for future reference. We recommend you inspect the endpoint logs regularly to ensure write back requests are properly processed the first time. To distinguish between unique events, each request is given an Idempotency Key.

Idempotency Key

The write back requests from Sparkcentral make use of an Idempotency Key which allows the write back endpoint to ensure it processes each request once. This key helps when requests are sent multiple times during the retry schedule, so the endpoint can handle our requests in an idempotent way. The key is unique per request.

Notification

Configure Notification URL

When you send your CRM managed contact attributes, Sparkcentral does some validation on the response. In order to see validation errors, we’ve provided a way to send notifications from Sparkcentral to your system. You will need to provide a POST endpoint that accepts a JSON request body. Configure a Notification URL on the same screen where you configured a Lookup URL (Settings -> Contact Attributes -> Manage CRM).

Handle the Request

When validation errors occur, Sparkcentral will send a request to the configured Notification URL. A request looks like this:

{
    "timestamp": "2019-01-30T15:49:10.630397Z",
    "version": 1,
    "eventType": "DATA_IMPORT_ERROR",
    "messages": [
        "testMessage1 key:testKey1 value:testValue1",
        "testMessage2 key:testKey2 value:testValue2"
        ]
    }

Use your secret to verify the X-Sparkcentral-Signature in the same way as for lookup and writeback. The request contains these two fields:

  1. eventType

  2. messages - an array of explicit error messages

Here are the current event types that can be sent by Sparkcentral:

Event Type Description
DATA_IMPORT_ERROR Error occured while pulling data from the CRM to Sparkcentral

The response to this request can be a 204. Sparkcentral is not expecting anything in the response body.

Other Actions

Refresh

The Refresh button in the conversation view will re-fetch managed attributes from the CRM. Since these attributes were previously confirmed, the confirmation step is not necessary.

The Unlink button in the conversation view will remove CRM managed attributes from Sparkcentral.

Confirm

The Confirm button will store the associated validated information from the CRM to Sparkcentral’s database.

Clear

The Clear button will reset the data that was pulled in by the lookup endpoint.

Generated by aglio on 31 Aug 2020