Skip to main content

  Article updated: September 13, 2021

Sparkcentral CRM integration

Integrating your CRM allows you to:

  • Pull in customer contact data via open RESTful API from any CRM or business apps, such as reservations systems, transactional information platforms, etc.
  • Give agents the customer information they need to speed up resolutions and time to response, without having to switch to the CRM to get customer information.
  • Identify and authenticate a customer and quickly resolve the most frequently asked questions.
  • Maintain the CRM as source of truth.
  • Provide agents with a direct link to the customer profile in CRM.

Integrate the CRM

To connect to the CRM, you'll need to create a contact attribute:

  • On the Settings tab, expand Agent Workspace, select Contact Attributes, and then select Add Attribute.
  • Make sure to select Managed by CRM and set a correct Unique Identifier.

For more information, see Sparkcentral contact attributes.

Manage the CRM

On the Settings tab, expand Integrations & APIs, and then select CRM.

Lookup URL

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 an X-Sparkcentral-Signature in its headers, which allows you to verify that the call comes from Sparkcentral.

After that endpoint is implemented, configure it as the Lookup URL on the CRM page. When the Lookup URL has been configured, you will receive a secret key that allows you to calculate the same signature as in X-Sparkcentral-Signature. This confirms that the request originated with Sparkcentral.

Handle the request

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

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 it 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:

Copy
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);

After 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:

Copy
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 must be confirmed in one of two ways before they are saved in Sparkcentralt:

  • Select Confirm when you see the CRM attributes displayed in Sparkcentral after the lookup request.
  • Add an autoConfirm field to the response:
Copy
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.

Notification URL

When you send your CRM managed contact attributes, Sparkcentral does some validation on the response. To see validation errors, you can send notifications from Sparkcentral to your system. You will need to provide a POST endpoint that accepts a JSON request body.

Handle the request

When validation errors occur, Sparkcentral sends a request to the configured notification URL. A request looks like this:

Copy
{
"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:

  • eventType
  • messages – an array of explicit error messages

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

event types seen by Sparkcentral

Event type

Description

DATA_IMPORT_ERROR

Error occurred 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.

Write Back URL

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.

  • 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 an X-Sparkcentral-Signature in its headers that allows you to verify that the call comes from Sparkcentral.
  • Configure the endpoint as the Write Back URLon the CRM page (on the Settings tab, expand Integrations & APIs, and then select CRM). When the Write Back URL has been configured, you will receive a secret key that allows you 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.
  • idempotency key: A string that uniquely identifies each event to write back, to help ensure that 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 an X-Sparkcentral-Signature that you can verify in the same way as for lookups.

* Applies to all mediums except Twitter. Twitter handle, tweets, direct message transcripts, and Twitter contact attributes (such asTwitter Name and Number of followers) will not be sent in the payload, in accordance 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:

Copy
{
"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

If 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 that you inspect the endpoint logs regularly to ensure that 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 use an idempotency key that allows the write back endpoint to ensure that it processes each request once. This key helps when requests are sent multiple times during the retry schedule, so the endpoint can handle requests in an idempotent way. The key is unique per request.

Notification URL

When you send your CRM managed contact attributes, Sparkcentral does some validation on the response. To see validation errors, you can 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 page where you configured a Lookup URL (on the Settings tab, expand Integrations & APIs, and then select CRM).

Handle the request

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

Copy
{
"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 write back. The request contains these two fields:

  • eventType
  • messages – an array of explicit error messages

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

event types sent by Sparkcentral
Event type Description
DATA_IMPORT_ERROR Error occurred 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 re-fetches managed attributes from the CRM. Because these attributes were previously confirmed, the confirmation step is not necessary.

Unlink

The Unlink button in the Conversation view removes CRM managed attributes from Sparkcentral.

Confirm

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

Clear

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