Building a JSON-API for FactBranch

Contents

• Overview
• Request payload
• Request authentication
• Response payload
• Item data types

Overview

FactBranch allows you to display any information in Zendesk right next to your tickets. It works by sending information from your ticket to your API so you can return customer info or anything you want your support team to know. If you've already set up your API and want to link FactBranch to your API please specify your API endpoint in your account settings.

Request Payload

FactBranch sends an HTTP POST request to the endpoint you've specified in your account settings with the following JSON-payload. If you've defined custom fields in Zendesk the actual `customFields` might vary. `tags` might be an empty array.

{
  "apiVersion": "1.0",
  "origin": "zendesk",
  "sent_at": "2010-02-04T06:25:57.000Z",
  "params": {
    "customerEmail": "your_customer@customer_company.com",
    "ticketID": "12345678",
    "customFields": [
      {name: "custom_field_25768205", label: "Nickname", value: ""},
      {name: "custom_field_25768206", label: "Is a pro subsciber", value: "Yes"}
    ],
    "tags": ["tag1", "tag2", "tag3"],
    "userEmail": "your_support_agent@your_company.com"
  }
}

FactBranch extracts the following fields from your Zendesk ticket and forwards them to your API:

customerEmail	The email address of your customer who writes an email to you and who's ticket you have open in Zendesk. Eg "alice@your_customer.com"
userEmail	The email address of the Zendesk user currently viewing the ticket. Eg "ted@your_organization.com"
ticketID	The Zendesk ticket ID (number). Eg 2143
customFields	An array of objects. If you've defined custom fields in Zendesk tickets, they show up here. For an example take a look at the JSON payload above.
tags	An array of strings.

Request Authentication

Every request at your API is signed using the secret you provide in your account settings. We do this by passing the header `X-FactBranch-Signature`

Here's how you create the signature in Ruby:

HMAC_DIGEST = OpenSSL::Digest.new('sha1')
signature = 'sha1='+OpenSSL::HMAC.hexdigest(HMAC_DIGEST, secret, body)

And here in Python:

from Crypto.Hash import SHA, HMAC
hmac = HMAC.new(secret, body, SHA)
signature = 'sha1=' + hmac.hexdigest()

Our implementation is heavily influenced by GitHub's signing of payloads for webhooks so please also refer to that link if you are unsure how to implement the check.

Response Payload

You can define different data types to display inside the Zendesk app.

So this JSON response from your server ...

{
  "apiVersion": "1.0",
  "data": {
    "items": [
      { "label": "Account Type", "value": "Monthly Premium Plan (March 2015)" },
      { "label": "Active", "value": true },
      { "label": "Last Invoice", "value": "Feb 3, 2016" },
      { "label": "Customer Lifetime Value", "value": "3.725 $" },
      { "label": "Recent NPS", "value": 8 },
      { "type": "link", "label": "Open customer page in admin panel", "value": "https://en.wikipedia.org/wiki/Main_Page" }
    ]
  }
}

... produces this output in the FactBranch app in Zendesk:

You can define as many items as you need.

Item Data Types

Different data types look different. Here's what you can use:

	If you omit the "type" property and `value` is a string or a number it will be displayed as text. When it's a boolean value we'll display "Yes" or "No" and instead of `null` we'll display an "n/a". The string is rendered HTML-safe. So "<div>" will really be displayed as "<div>".
link	`label` will be displayed as the link-text and `value` will be the link's address.
button	Same as `link` but styled as a button. Use this for actions like "Renew subscription" and link to the page in your backend where the support person can do that.
html	Free form html. We take the string as we get it from your server. So feel free to style your text with HTML-tags. Many browsers even support using emojis with this data type.

Questions?

If you have any questions or have specific needs regarding your API, please drop us a line at support@factbranch.com