Legacy Dynamic 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 with a POST request. The data in the message will look similar to this:

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

Please note:

1. The ticket response object definitions match those of the Get Conversation Mailbox API endpoint.
2. If you load a conversation that doesn’t include a value for any of these fields, they will be removed from the custom app request. Draft conversations will return a false value for the ticket object.

Redirects

Server redirects are not followed by default. However, we will follow a server redirect when in debug mode to assist with debugging.

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.

Using Debug Mode

To assist with testing, you’ll have access to Debug Mode from your custom app settings. When enabled, the app debugger panel can be launched by loading any conversation, then clicking View Debugger.

From the debugger panel, you can test your custom app against alternate non-HTTPS URLs as needed. You can also test various scenarios in realtime by modifying the request body parameters. Click Refresh from the panel and the modified request values will be sent to your server, updating your custom app with new data.

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.