CuBoulder/cu_helpscout_api

Name: cu_helpscout_api

Owner: University of Colorado Boulder

Description: Drupal module that interfaces with the HelpScout API v1

Created: 2018-02-16 20:56:38.0

Updated: 2018-02-16 21:23:21.0

Pushed: 2018-02-16 21:33:03.0

Homepage: null

Size: 25

Language: PHP

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

cu_helpscout_api

Drupal module that interfaces with the HelpScout API v1.

Setup

You will need to get a HelpScout API key from your profile, e.g. https://secure.helpscout.net/users/authentication/your-uid/security, to authenticate your requests.

Once you have that key setup, you need to add it to the settings.php file of the site you have this module installed.

elpScout API access key. Get it from your profile dashboard.
RVER['HSC_API_ACCESS_KEY'] = 'xxxx';

How It Works

The module looks for HelpScout conversations that have been created in the last two days and adds fields from the Beacon Javacsript API's identify() function, https://developer.helpscout.com/beacons/javascript-api/#identify, to a conversation during a cron run via the HelpScout API.

terday = date("Y-m-d", strtotime("-1 day", time()));
ields something like "2018-02-16".

t_updated = variable_get('hsc_last_updated', $yesterday);
ry = "query=(createdAt%3A%5B". $last_updated. "T00%3A00%3A00Z%20TO%20*%5D)";

rab conversations that have been created since last cron run.
 = new HelpScoutUpdater($api_url, $auth);
versations = $hsc->getConversationsByQuery($query);

ap Beacon fields to custom fields.
->setMappings($mappings);
ified_conversations = $hsc->mapBeaconFieldsToConversations($conversations);

end updated conversations to HelpScout.
->updateConversations($modified_conversations);

The Beacon fields are generated by the cu_helpscout module: https://github.com/CuBoulder/express/blob/dev/modules/custom/cu_helpscout/cu_helpscout.module#L71.

They are prefixed and suffixed with two dollar signs, $$ to make it easier to parse the HTML tables containing Beacon fields returned from the HelpScout API. HelpScout considers the Beacon as part of a “thread” where all data (rendered HTML) is smooshed together into a “body” field.

You can add or remove fields from the Beacon by updating them in the cu_helpscout module as well as in the cu_helpscout_api module.

rom cu_helpscout_preprocess_page(&$vars) function...
= '
eacon.ready(function() {
.beacon.identify({
name: \''. $name. '\',
email: \''. $user->mail. '\',
$$roles$$: \''. $roles. '\',
$$site_name$$: \''. $site_name. '\',
$$site_url$$: \''. $base_url. '\',
$$user_name$$: \''. $name. '\',
$$user_email$$: \''. $user->mail. '\',
$$organization_level_one$$: \''. 'one' . '\',
$$organization_level_two$$: \''. 'two' . '\',
$$organization_level_three$$: \''. 'three' . '\',
$$organization_level_four$$: \''. 'four' . '\',
$$topic$$: \'24596\',
;



rom cu_helpscout_api_cron() function...
pings = [
ite_url' => 4965,
ser_name' => 5223,
ser_email' => 5224,
rganization_level_one' => 6672,
rganization_level_two' => 6673,
rganization_level_three' => 6674,
rganization_level_four' => 6675,
opic' => 5222,

ap Beacon fields to custom fields.
->setMappings($mappings);

You will need to decipher the field IDs stored in HelpScout to add a new custom field to be updated. It is easiest to do this by filling out a conversation in the HelpScout UI and checking out the JSON response for that conversation.

l -u access-token:X https://api.helpscout.net/v1/conversations/conversation-id.json  

The new field IDs you need to add to the mappings array will be in a customFields array in the API response.

ustomFields": [
{
  "fieldId": 4965,
  "name": "Website URL",
  "value": "http://127.0.0.1:8068",
  "type": "SINGLE_LINE",
  "label": "http://127.0.0.1:8068"
},