Connecting Y Meadows and Help Scout

Y Meadows has a pre-built integration with Help Scout that allows users to set Help Scout as a message source. The Y Meadows Help Scout connection is limited to a single Help Scout mailbox. To monitor multiple mailboxes users will need to create multiple connections. All folders in the mailbox are treated as directories in Y Meadows and all conversations in the folder are treated as messages.

Step 1 - Initial setup

In the Help Scout panel, go to the mailbox that users want to connect to Y Meadows.

Click on Mailbox Settings > Edit mailbox.

Check the URL of the settings page in the browser. It will be something like:

https://secure.helpscout.net/settings/mailbox/265894/

Take the part between /settings/mailbox/ and the next /, e.g. 265894 . Copy this down, as it will be used in a later step (this is the “Mailbox ID”).

Step 2 - Create an app on the Help Scout side

In the Help Scout panel, users should navigate to the mailbox they wish to connect with Y Meadows.

Click on the users profile picture ( in the top right corner) > Your Profile > My Apps.

Click on Create My App.

Enter Y Meadows App as the App Name

Enter any url e.g. https://ymeadows.com/ as the Redirection URL.

The Redirection URL is used by Help Scout to redirect to upon a successful authorization. Y Meadows does not use the explicit sign-in feature, so this URL is never used.

Click on Create.

Open the app configuration (it should be opened after creation by default).

Copy App ID in Credentials section. It will be needed it in a later on during the "App ID" step.

Copy App Secret in Credentials section. It will need it in a later on during the "App Secret "step.

Step 3 - Set up the connection on the Y Meadows side

Create a new connection based on Help Scout Messages Webhook connection type.

Enter the Mailbox ID that from Step 1 as Mailbox ID.

Enter the App ID from Step 2 as App ID.

Enter the App Secret from got from Step 2 as App Secret.

Make up a “password” and enter it as Webhook Secret. Note it down as it will be used as the “Webhook Secret” in a future step.

THIS PASSWORD SHOULD CONTAIN ONLY LETTERS AND NUMBERS to avoid problems saving in Help Scout in a later step.

The Webhook Secret is used by Help Scout to sign a request. The Y Meadows will verify that the message came from Help Scout by validating that signature.

Save the new connection.

Take a look at the URL in the browser. It will be something like https://tierzero-qa.ymeadows.com/components/connections/23e8d269-48f2-4be4-ad10-821e720637e2 . That last portion, 23e8d269-48f2-4be4-ad10-821e720637e2 is the “Connection ID”. Please save it as it will be needed in a later step.

Step 4 - Create the Webhook configuration on Help Scout side

In the Help Scout panel, go to the mailbox.

Go to Manage > Apps.

Search for Webhooks and click on it.

Click on Install app.

Enter the Webhook secret created in Step 3 as the Secret Key.

Enter https://SUB_DOMAIN.ymeadows.com/api/v1/webhooks/helpscout/CONNECTION_ID replacing CONNECTION_ID with the ID of the connection that was generated Step 3, as the Callback URL and replacing SUB_DOMAIN with the appropriate URL for the Y Meadows instance. (eg: for https://acme.ymeadows.com, acme is the SUB_DOMAIN).

Enable the checkbox labelled Webhook Enabled.

Choose Conversation Created in the Events section.

Be careful when choosing which events to listen to. When using a Help Scout connection in a Y Meadows path the user dictates which directory to listen to. It is possible to choose a Help Scout event and a directory to listen to that will conflict.

For example, choosing Conversation Created as event and Unassigned as directory filter will work fine, but choosing Conversation Assigned as event and Unassigned as directory will cause no events to flow as any time a conversation is assigned it will never be the Unassigned directory.

Click on Save .

Help Scout’s web hook setup is sensitive. If the Y-Meadows junction path is turned off for more than 10 messages the connection will be shut off from the Help Scout side. Sometimes, they enforce a 3 hour time-out before the connection can be restored.

This is of particular importance during any scheduled maintenance event. In order to avoid problems it is important to turn off the web hook automation from the Help Scout side before maintenance begins.