Dynamic Custom Apps

Dynamic Apps require two things in order to function properly:

  1. An HTTPS end-point URL on your server for Help Scout to call
  2. A secret key, used to generate message signatures

The secret key is a randomly generated (by you) 40-character or less string used to create signatures for each data request. Help Scout uses this secret key to generate a signature for each message. When the message is received at your callback url, you can calculate a signature and compare to the one Help Scout sends. If the signatures match, you know it's from Help Scout.

When a conversation is loaded and your custom App renders, Help Scout will build a JSON message with conversation data and call your endpoint URL. The data in the message will look like this:

ticket: {
    id: xxxx,
    number: xxx,
    subject: "the subject here"
},
customer: {
    id: xxx,
    fname: "",
    lname: "",
    email: null,
    emails: []
},
mailbox: {
    id: xxxxx,
    email: help@domain.com
}

Signature Validation

Help Scout will generate a signature using the secret key you provided. The Help Scout-generated signature will be available in the headers as X-HELPSCOUT-SIGNATURE. You can calculate the same signature on your side, using the same secret key. If the signatures match, you know the request is from Help Scout and can proceed with providing data. If the signatures do not match, we recommend discarding the request. It works exactly like how we handle webhooks (see the Verifying section).

Response

The response returned to Help Scout should be a JSON message containing your HTML.

{
    "html": "<ul><li>Some html here</li></ul>"
}

NOTE: Making sure your HTML is properly escaped is very important. Your response should be a validating JSON response. For example, if you're using PHP, this can be accomplished with json_encode:

$html =<<<EOF
<h4>Jan's Famous Cupcakes</h4>
<p class="muted">Paying customer since 24 May 2011</p>
<ul>
	<li>Unlimited Plan</li>
</ul>
EOF;
echo json_encode(array(
	'html' => $html
));

Please see the Style Guide tab for guidance on formatting your HTML so that it fits well within the web app.

Once you are all set, Build Your Custom App.

Need assistance?

We have a PHP client library that may help get you started. And we also have a Ruby example brought to you from our friends at KISSmetrics.