Skip to main content

  Article updated: February 04, 2022

Sparkcentral CRM API

Sparkcentral CRM integration allows you to pull customer contact data from CRMs or other internal business applications into Sparkcentral. To integrate your CRM with Sparkcentral, you 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.

Security and Authentication

When sending or receiving data from Sparkcentral we provide two Authentication options. Both mechanisms are in place so that you can make sure the request originates from Sparkcentral.

Shared Secret

When you choose the shared secret mechanism and you configure an URL, you are given a secret. With the given secret, you can calculate the signature which allows you to verify that the call originated from Sparkcentral. With this mechanism, every single request from Sparkcentral contains the X-Sparkcentral-Signature header. Here’s an example of a request:

Copy

curl -X POST https://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 with 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:

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

OAuth

If your endpoints support OAuth2, you can configure your client credentials, a Token URL and optionally a Scope in Sparkcentral.

We use the OAuth2 Client Credentials flow to authenticate against your CRM. The Token URL is the endpoint where we can authenticate with these credentials and retrieve an Access Token. To do the actual Lookup, write back or notification requests we use the token in the Authorization Header to Authenticate.

Lookup

Create contact attributes

  1. In Sparkcentral, go to Admin settings, expand Agent Workspace, select Contact Attributes, and then select Add Attribute.
  2. In the Edit Attribute box, select Managed by CRM. The CRM is the source of truth for these attributes. After they are imported into Sparkcentral, they only change when the value changes in the CRM.
  3. Identify lookup attributes by selecting Use as Lookup Attribute. These are used by the CRM to find a customer’s data. For example, if you want to find a 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 fields are included in the request body.
  4. Create an alias for the attribute. In the Unique Identifier box, enter an alias for the lookup attribute. This is used to map the response from your system to the attribute.

Configure integration URL

To pull data from your CRM into Sparkcentral, you 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

After that endpoint is implemented, configure it as the Lookup URL:

  1. Go to Admin settings.

  2. Expand Integration and APIs.

  3. Select CRM.

Handle the request

When the endpoint in your system is ready and 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.

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 is deleted in Sparkcentral. Sparkcentral expects the response in this format:

Response 200 (application/json)

Copy
{
"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 before they are saved in Sparkcentral. There are two ways to do that:

  • Select the Confirm button when you see the CRM attributes displayed in Sparkcentral after the lookup request.
  • Add an autoConfirm field to the response:

Response 200 (application/json)

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

Write back

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 write back URL

To push data from Sparkcentral into your CRM, you 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

Configure the endpoint as the Write Back URL:

  1. Go to Admin settings.

  2. Expand Integration and APIs.

  3. Select CRM.

Handle the request

When the endpoint in your system is ready and configured in Sparkcentral, and relevant events occur within Sparkcentral, requests are 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. Used 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.

* Applies to all mediums except Twitter. Twitter handle, tweets, and direct message transcripts, and Twitter medium contact attributes (Twitter name, number of followers, etc.), are not sent in the payload, to conform to 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
{
  "timestamp": "2021-04-28T09:43:26.635984618Z",
  "idempotencyKey": "6ebc6a78-d9e9-48be-b172-51eda40b7af8",
  "version": 1,
  "type": "CONVERSATION_RESOLVED",
  "data": {
    "conversation": {
      "id": "0ad42eef-a806-11eb-9642-f1ceb2f21def",
      "createdAt": "2021-04-28T09:42:27.004817183Z",
      "previousStatus": "new",
      "currentStatus": "resolved"
    },
    "medium": {
      "id": "smooch-whatsapp"
    },
    "channel": {
      "id": "0-02534c5ac04-000-261ad914",
      "name": "channelname"
    },
    "agent": {
      "id": "11599",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@Hootsuite.com"
    },
    "contactProfile": {
      "id": "693ed54b-a426-11eb-9363-cffd945b4b2f",
      "mediumContactProfileId": "bb7b0f8f00cc989b97f0725b",
      "primaryIdentifier": "John Smith",
      "secondaryIdentifier": "+32439487192",
      "pictureUrl": null
    },
    "statusUpdatedReason": "5fd023f6-2e66-11eb-be07-092841b0717d - Response Not Required",
    "statusUpdatedComment": "not a question",
    "statusUpdatedAt": "2021-04-28T09:43:26.532948586Z",
    "messages": [
      {
        "id": "0ad20c0d-a806-11eb-9642-f799d0e531de",
        "direction": "INBOUND",
        "text": "Figuur"
      },
      {
        "id": "10664516-a806-11eb-9642-fbd9d431bd78",
        "direction": "OUTBOUND",
        "text": "dsghkjsdgmhlknsdmglhkjmsdlgkhjmsdgkljhlmdkgjh"
      }
    ],
    "contactAttributes": [
      {
        "attribute": "smooch-whatsapp-profile-name",
        "value": "John Smith",
        "source": "MEDIUM"
      },
      {
        "attribute": "smooch-whatsapp-phone-number",
        "value": "+32471263345",
        "source": "MEDIUM"
      },
      {
        "attribute": "email",
        "value": "john.smith@Hootsuite.com",
        "source": "CRM_CONFIRMED"
      },
      {
        "attribute": "first_name",
        "value": "John",
        "source": "CRM_CONFIRMED"
      },
      {
        "attribute": "last_name",
        "value": "Smith",
        "source": "CRM_CONFIRMED"
      },
      {
        "attribute": "company",
        "value": "Hootsuite",
        "source": "CRM_CONFIRMED"
      },
      {
        "attribute": "spark-language",
        "value": "nl",
        "source": "CRM_CONFIRMED"
      }
    ],
    "notes": [],
    "topics": []
  }
}

Write back retry

If the write back request times out or the endpoint returns a non-success (2XX) status code, Sparkcentral retries with exponential backoffs. The request are 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 does not succeed. If the request still has not succeeded after 6 requests, 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 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 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. To see validation errors, we’ve provided a way to send notifications from Sparkcentral to your system. You 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:

  1. Go to Admin settings.

  2. Expand Integration and APIs.

  3. Select CRM.

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"
]
}

The request contains these two fields:

  • eventType
  • messages – an array of explicit error messages

The following are the event types that can be sent by Sparkcentral.

event types
Event typeDescription
DATA_IMPORT_ERRORError occurred while pulling data from the CRM to Sparkcentral.

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

Other actions

Refresh

The Refresh button in 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 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.

 

Can't find what you're looking for? We're here to help