Installing the Dropzone Connector for Intercom

Our Dropzone Connector for Intercom integrates your SendSafely Hosted Dropzone with Intercom and can be used to update both Intercom tickets and conversations. The connector is an AWS Lambda function and is installed using a CloudFormation template. This Intercom integration is available to subscribers on the SendSafely Enterprise plan.

Once configured, the Dropzone connector will:

• Generate a formatted Dropzone URL and posts it to the conversation via a Custom Action. This URL directs customers to a SendSafely Hosted Dropzone form, where they upload sensitive files.
• Once the customer upload is complete, the Dropzone connector updates the Intercom conversation with a link to the files. This links agents to the SendSafely portal to view and/or download the actual files

The connector uses the Dropzone lookup field (Conversation ID) to associate inbound files with the appropriate conversation or ticket in Intercom. This lookup value is embedded in the ticket specific Dropzone URL posted to the conversation by the agent using a Custom Action

Below are the steps for

1. Creating and configuring the AWS Lambda connector using CloudFormation,
2. Creating the Custom Action to generate ticket specific Dropzone URLs.

Prerequisites

The steps outlined in this article assumes the following prerequisites:

• You already have a SendSafely account with a Dropzone enabled. Refer to the “Initial Dropzone Setup” section of the Hosted Dropzone article for steps on how to enable. 
• You have permissions within AWS to setup and deploy new resources. Specifically you will need permission to:
  • Create a new Lambda Function 
  • Create a new DynamoDB Table 
  • Create a new SNS Topic (Simple Notification Service)
  • Create a new API (API Gateway Service)
  • Create a new AWS Secret (AWS Secrets Manager )
  • Define a custom IAM Role for the Lambda Function 

Prior to beginning this setup please contact [e-mail] for instructions on how to obtain the CloudFormation template file, which is required for Step 1 below.

Configuring the AWS Lambda connector using CloudFormation

Step 1: Create stack and specify template (AWS CloudFormation)

First, create a stack by logging into your AWS account and browsing to the CloudFormation console. Choose:  AWS -> CloudFormation -> Create stack -> With new resources (standard)

Under "Step 1: Specify template" select the following options and click next:

• Prepare template: Template is ready

• Template source:  Upload a template file 

• Template file: The YAML obtained from your SendSafely account representative or SendSafely Support 

Step 2: Specify stack details (AWS CloudFormation)

Next, name the stack and populate the following mandatory parameters:

• errorReportingEmail: This is the email address to notify when the Dropzone Connector encounters an errors

• intercomPortal: The URL for your Intercom portal. Defaults to https://api.intercom.io/ (US region).

• resourcePrefix: A value prepended to resources created by this template so that you can uniquely identify them (must begin with a letter and contain only alphanumeric characters)

NOTE: After the stack is created, the address specified in errorReportingEmail (in this example [e-mail]) will receive an email to confirm the SNS subscription. 

Step 3: Configure stack options (AWS CloudFormation)

For this step we recommend that you leave the default values and click the "Next" button. CloudFormation will automatically create a new role for the connector that has the minimum permissions needed for it to run correctly. 

Step 4: Review and Create (AWS CloudFormation)

Review and acknowledge the required resources and capabilities then click "Create stack"

The Stack may take several minutes to create. You can view the status from the CloudFormation > Stacks screen. Once the entire process completes successfully, the stack will have a status of "CREATE_COMPLETE". You can view a complete list of the resources that were created from the "Resources" tab.  This includes the Lambda function and supporting AWS resources.

Step 5: Confirm the SNS subscription for Error Reporting 

The address specified for the errorReportingEmail should have received an email to confirm the SNS subscription. Click the Confirm subscription link to enable the alerts. 

Step 6: Configure Webhook URL in SendSafely

On the Stack "Outputs" tab, copy the WebhookUrl to your clipboard, as per the screenshot below.

Log in to your SendSafely portal as either the Dropzone owner or as a SendSafely Admin and navigate to the Dropzone profile.

• Under Notification Settings, select the "Use a Webhook for notifications" option and paste in the WebhookUrl.
• You should also make sure that the "Form Input Label" value is set to something intuitive like "Conversation ID" or "Ticket Number". 

Step 7: Update Environment Variables (AWS Lambda)

Within AWS, click on the Lambda link of the Stacks Resources tab in CloudFormation, then go to the Configuration tab and choose Environment Variables on the left side of the screen to update the following environment variables. An explanation of each and the allowable values is included below. Once the fields are updated, click Save.

• DROPZONE_URL: This is the URL of the dropzone you are using to receive files from customers. This value MUST be updated as the default value is invalid. 

  • e.g. https://demo.sendsafely.com/dropzone/your-dropzone-name

• POST_DROPZONE_LINK_AS: This variable controls how the Dropzone Link is added to the conversation when the Action/Macro is invoked. Valid values are:

  • comment (default) - The link to upload files to the Dropzone is posted as a comment that both the agent AND end-user can see.
  • note - The link to upload files to the Dropzone is posted as a private note that only the agents can see. This option requires the agent to copy the link and then re-send to the customer in their own reply. 

• POST_PACKAGE_LINK_AS: This variable controls how the Package Link is added to the conversation after the user is done uploading their files. Valid values are:

  • comment- The link to the package is posted as a comment that both the agent AND end-user can see.
  • note (default) - The link to the package is posted as a private note that only the agents can see

Step 8: Generate an Intercom API Token

In this step you will create an API Token that the connector can use to read and update Intercom conversations.

• Log into your Intercom account and navigate to the Developer Hub
• Click the New app button to create a new app
  
  • Name the app "SendSafely Dropzone Connector" 
  • Choose the Intercom Workspace where you want to the Dropzone to integrate with 
  • Press the Create button and you will be sent to the Authentication screen 

On the authentication screen, you'll notice that ALL permissions are enabled by default. Press the Edit button and un-check all of the default permissions except for the following: 

• Read conversations 
• Read tickets
• Write conversations
• Write tickets 

Press the Save button and then copy the API token. The token is masked within the UI but there is a copy button next to it. This token will be required for the next step. 

Step 9: Update Secrets Manager (AWS) 

Within AWS, click on the SecretsManager link of the Stacks Resources tab in CloudFormation. From the Secrets Manager screen, choose Retrieve Secret Value and then press Edit to update the following values: 

• sendsafely_validation_key - Enter the Dropzone Validation Key for the account that owns the Dropzone. You can obtain this value from the Dropzone profile in the SendSafely portal.
• intercom_global_api_token: This is the Intercom Access Token generated in Step 7 above. 
• intercom_action_token: This is a custom token value that will be used authenticate request that get made by the Intercom Custom Action you will create in the next step. This value should be randomly generated and include a mix of upper and lowercase letters and numbers and be at least 20 characters long. You will need this value in the next step as well. 

Press the Save button to save the Secrets Manager values.

Step 10: Set up a Custom Action in Intercom 

In this step you will create a Custom Action that will be used by agents to insert a Dropzone link into any conversation. Custom actions can be created from Settings > Integrations > Actions. The Custom Action will make a request to the Lambda Intercom Dropzone connector that will automatically post back a link to the Dropzone that includes the correct conversation ID. 

Press the Create an Action button. At the top of the screen, change the Action name from "Unamed action" to something descriptive like "Add link to SendSafely Dropzone". 

Next, populate the following values when prompted: 

• About: Under Usage choose "Workflows and Help Desk" and type "This action can be used to add a SendSafely Dropzone link to any conversation or ticket" for the description. 
• Request:
  • Choose POST as the method and enter the Lambda function URL (from Step 6 above) as the HTTPS URL
  • Under HTTP Headers choose Add a key value pair 
    • For the Key type "intercom-action-token"
    • For the Value type the intercom_action_token value generated in the previous step 
  •  For the Request Body copy/paste the following string (case-sensitive)

    • {"conversationId":Conversation ID}

    • Intercom should auto-populate the Conversation ID attribute in a grey box as shown below. If it does not, you can click the icon on the right of the text field to insert the Conversation ID attribute manually 
• Testing:  Next, you will be forced to test the action. For the test value, provide a valid Conversation ID from your Intercom workspace and press the Test button. 
  • If the test is successful, you will see a green "200 OK" message. Press Next to continue.
  • If the test is NOT successful, you should get an error message indicating a problem with the Lambda configuration. If you are unsure what caused the error based on the message, you can also look at the CloudWatch logs for the Lambda for more verbose error logging. 
• Response: No configuration is required on this step. Press Save in the top right corner of the screen and then press Set Live. 

Step 11: Set up a Macro in Intercom (optional) 

A macro will let you define custom text that will be added to the message before the link to the Dropzone gets inserted. This can be helpful if you want to provide some standard instructional text to the user before they get the Dropzone link. 

Macros's can be created from Settings > Help Desk > Macros. 

• Press the New Macro button
• Change the name from "Untitled Macro" to something descriptive like "Insert link to SendSafely Dropzone" 
• In the "Add a response" box, type the text you want to insert into the conversation before the link gets added. The text =should contain helpful user instructions like "Please use the following link to to securely upload files to this conversation."
• Press the Add an action button and choose Custom Action and then select the action you created in the previous step.
• Press Save to save the macro. 

Step 12: Add SendSafely portal hostname as a Trusted Domain 

In this step you will add the hostname for your SendSafely portal as a Trusted Domain. This is important to prevent SendSafely Dropzone and Package links from including a warning when inserted into a conversation.

• Go to Settings > Workspace > Security. Look for the section labeled Links. 
• Under Trusted Domains, type the hostname for your SendSafely portal (ie yourcompany.sendsafely.com) and press Save.

Step 13: Test the Connector (Final Step)

Once you complete the steps above, you should be able to use the macro to add a Dropzone URL specific to a ticket, and successfully upload tickets.

When composing a reply to a conversation or ticket, open the shortcuts menu by clicking the bolt icon or pressing ctrl + K. 

• If you are using a Macro, type the Macro name in the search box or choose Use Macro. The macro text will appear in the reply editor. Press Send to send the reply and invoke the action. 
• If you are not using a Macro, type the Custom Action name in the search box or choose Trigger Custom Action. 

In both of the above cases, you should see a link to the Dropzone get posted to the conversation. That link will be used by your customer to submit files to the conversation. The following diagram depicts the logic implemented within the connector and shows what actions will result after files are submitted. 

For additional assistance setting up the Intercom Dropzone Connector, contact [e-mail].