Question 1

What are Webhooks and how do I use them to receive notifications when Workflows are completed?

Accepted Answer

Webhooks allow you to set up your own integrations to Malcolm! Workflow.

Webhooks are endpoints on web servers you own. Whenever a Workflow is completed the configured Webhooks will be notified. The Payload will contain the completed Workflow Session, related Workflow and (optionally) the submitted Workflow Values.

Configuration

Webhooks are are configured in "Workflows > Edit > Configure > Webhooks" section of MyMalcolm.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/IWqLLH7kgn/Screenshot%202021-01-26%20at%2016.17.46.png (Screenshot 2021-01-26 at 16.17.46.png)

Webhook URL

The only requirement is to provide the URL of your Webhook. This is the URL Malcolm! will send the Payload to.

The URL should be a secure endpoint which means it should start with https://, although we do support http:// too. The endpoint should also be accessible which means hosted on a remote machine, not behind a firewall and not requiring Authentication.

Include the Workflow Values

There is an additional option to include the submitted Workflow Values in the Payload. This option is disabled by default for security reasons but available to use should you wish to enable it. By enabling the option you agree to the following terms -

(a) I would like the Workflow Values included in the Webhook Payload (b) the recieving web server is private and properly secured (c) I am aware the use of Webhooks can facilitate the transfer of end-user personal data to third party Data Processors and my use of Webhooks adheres to my responsibilities as Data Controller under applicable Data Protection Laws.

Secure your Webhook with a secret token

Webhook URLs can be called by anyone and are therefore insecure.

To ensure a request to your Webhook URL comes from Malcolm! a secret token known only by yourself and Malcolm! can be used to generate a Signature.

Malcolm! will take the Payload and the secret and create a Signature. This will be passed to your App as the request header X-Signature. Your App will use the same secret and the received Payload to generate a second Signature. If the Signatures match you know the request came from Malcolm! and not another source.

The secret token can be any string you like, but Malcolm! recommends using a random string of at least 36 characters. For example in a Terminal window run -

To validate the Payload from Malcolm! use the HMAC SHA-256 algorithm to create a hash using the Payload as the data and your secret as the key.

For example in PHP use the hash_hmac function to generate a binary hash.

Next encode the binary hash using a Base 64 encoder, in PHP this is the base64_encode function.

Finally prefix the encoded hash with "sha256=" and compare with the value of X-Signature. In PHP you can use the $_SERVER variable to access the headers.

Conditional settings

There are conditional controls available too. If you have a condition configured the Webhook will only be notified if the conditions at the end of the Workflow are satisfied.

Headers

The HTTP POST will contain the following Headers.

Payload

The Payload will be a JSON Body containing the Workflow Session.

Workflows are defined as -

Workflow Values are defined as -

Workflow Fields are defined as -

Example

Question 2

What is the Malcolm! widget and how do I implement it?

Accepted Answer

The Malcolm! widget is a great way to put your content in front of users. By using the widget you can float content over an existing website or application. Want to let your users find out answers to FAQs about a product or service you provide but don't want them to make them navigate from the screen they are on? The Malcolm! widget is what you need. Or perhaps you'd like to float a feedback or get in touch form over your website? Super easy to do with the Malcolm! widget. You can even make the content displayed contextual to the screen the widget is floating over. How cool is that?

We recommend you place the Malcolm! widget embed code on every page of your website. You can then configure whether the widget displays or not (and what it displays) from within MyMalcolm!

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/IdGAskGCq2/widget-fb%402x.png (The Malcolm! Widget)

Here is how to start using the Malcolm! widget.

Step 1: Create an embed

Go the Share section of MyMalcolm and select the Embed tab and then Create an embed. Select Widget as the type of embed you want to create.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/Ji7YZa6eF7/screenshot-my.malcolm.app-2019.11.05-11_16_34.png (Create an embed in MyMalcolm)

Give your embed a name.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/zZgVvihFmE/screenshot-my.malcolm.app-2019.11.05-13_14_38.png (Names your embed in MyMalcolm)

Step 2: Choose your content

From this area you can choose a single FAQ or Workflow to display in the widget, or you can choose collections of content. These collections can be a category, a tag or an author. You can also make a collection out of a search result including a search that is contextual to the meta content of the page that the widget is on - you can query content based on the page title, meta keywords, meta description or a meta search tag.

Users can navigate content within the widget via clicking on items in the user interface eg categories, tags or authors.

If you don't choose a specific FAQ, Workflow or collection of content the default content displayed will be the most popular content.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/jbX8ylorUd/screenshot-my.malcolm.app-2019.11.05-13_16_07.png (Choose the content for your widget)

Step 3: Configure the visual style of your widget

You can configure various options about the visual appearance and behaviour of your widget. The options include what the widget looks like in it's pre-expand state (a button or a drawer), the text used on the pre-expand, the colours and logo plus the location of the widget on your screen. You can also configure whether you want the search and footer used on expanded widget and whether the transition from pre-expand to post-expand and vice versa are animated or not.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/UEdVkI4MOo/screenshot-my.malcolm.app-2019.11.05-13_16_42.png (Configure the visual style of your widget)

Step 4: Set up URL rules and visibility settings

We recommend you put the Malcolm! widget embed code on every page of your website. But you might not want the widget to appear on every page. Using URL rules you can mangage and easily change which pages the widget does appear on from within MyMalcolm!

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/rVDvNjLQrJ/screenshot-my.malcolm.app-2019.11.05-13_17_22.png (Manage URL rules for your widget)

You may not want the widget to display on mobile browsers, or you may want the widget to only appear at certain times (for example when your office is closed) - you can configure these options in visibility settings.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/GWsPKq5LZ4/screenshot-my.malcolm.app-2019.11.05-13_19_13.png (Manage your widget visibility settings)

Step 5: Publish and place code on site

Finally when you are happy publish your widget.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/g4why3UaJ5/screenshot-my.malcolm.app-2019.11.05-13_20_01.png (Publish your embed)

Finally collect your code - you can cut and paste this or have it emailed to you (or the person who is responsible for implementation).

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/KyYO8MKguT/screenshot-my.malcolm.app-2019.11.05-13_47_41.png (Collect your widget embed code)

If you use Google Tag Manager you can also deploy the embed code via this system. See here for more details.

Question 3

How do I use Make (formerly Integromat) to connect Malcolm! to other applications or services I use?

Accepted Answer

Malcolm! now integrates with Make (formerly Integromat). Make is an integration platform - it connects thousands of apps to other apps.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/0HPOpP331Q/make.jpg (Malcolm! and Make)

In the context of Malcolm! this means that when a Workflow is completed you can use our Make integration to route some or all of the data that has been collected from that Workflow through into Make and then in turn onto thousands of other apps or services.

Here is how to set things up:

Firstly set up and publish a workflow in Malcolm! that collects the data you wish to move into other applications.
In MyMalcolm go to the Settings Section, then Workflows, then Integrations, then click on Make.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/9ZMkRdBXkW/screenshot-my.malcolm.app-2022.05.24-11_51_26.png (Make in MyMalcolm)

Sign up for an account at Make if you don't already have one - it is free - or login if you do have an account.
In Make click "Create a new scenario".
Search or browse to the third party app/s or service/s you wish to link to your Workflow, select them, then click continue.
You will then find yourself in new scenario dialogue of Make. This is where you connect Make to Malcolm! and also your third party apps or services (ie by providing your credentials). Note that Make calls the connection to Malcolm! a webhook.
You then set up the sort of interactions you want to happen when a Malcolm! Workflow is completed. For example you may wish to connect to Google Sheets and have a new row containing the data submitted each time a Workflow is completed. There are also many other powerful options and settings that can be configured from this area. For more detals see Make's guides.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/gh0ZuJlWP4/Screenshot%202021-05-01%20at%2011.26.37.png (Creating a scenario)

Once you have set things up, you can test the integration by clicking "Run Once" in the Make interface, then complete the Malcolm! Workflow in question. The actions you have configured in Make should then happen, or you may see details of errors that need correcting.
When you are happy you can then set the scenario to run immediately (ie each time a Workfow is completed) or periodically.
Back in MyMalcolm, if you find the Workflow you set up with Make in the Library, select it, then go to Configure then Integrations you should be able to see Make as been added. You can turn the integation off here if you want and/or configure it to be conditional (for example to only run when certain choices have been made on a Workflow).

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/hDb4itCeGp/screenshot-my.malcolm.app-2022.05.24-12_24_42.png (A set up Make integration in MyMalcolm)

You can also see a video walkthrough below:

Remember that Malcolm! always stores your data (which you can download anytime) - so if Make goes down or your integration doesn't seem to work properly no data will be lost.

We are hugely excited about the possibilities opened up via Make - we hope you are too! If you have questions or need a hand setting things up just contact us and we'll be happy to help.

Question 4

Can I change the sender and email address in the emails Malcolm! sends my customers?

Accepted Answer

Malcolm! can send emails to your customers/users in the following situations:

Workflow email answers where you have configured the email answer to be sent to the email address specified in the Workflow
Email this answer functionality on an FAQ
Sending the resume later Workflow link
Payment confirmation email

By default these emails come from the sender "Malcolm!" with the email address noreply@malcolm.app

To do this, goto Settings --> Instance --> Emails and toggle Custom email sending to be active. You can then supply your Mailgun or SendGrid credentials and specify your desired sender name and email address.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/3dFvKHsdpC/screenshot-my.malcolm.app-2022.01.02-18_57_32.png (Adding MailGun or SendGrid credentials in MyMalcolm)

You can also change the look and feel of these emails - please see this FAQ for further details.

Question 5

I'd like to open the Overlay embed directly, how do I do this?

Accepted Answer

When you create an Overlay embed we give you two bits of code to add to your page. The first is the master code which you should place just before the closing tag. The second is the inline code which generates the button users click to open the overlay - this goes inside the tags where you want the button to appear. When the user clicks the button the Overlay embed will appear in a modal (pop-up) over your page.

The inline code we give you will look like this -

Sometimes you might want to call the overlay but not use our button. You might want to call it from text or use your own button/graphic or you might want to call it in the background when a user does something else on your page.

You can do this by calling mapi in JavaScript.

The mapi has four methods - open, close, trigger and toggle. Open, close and toggle all return promises (i.e., a function that resolves when the animation is complete or a rejects if something went wrong, e.g., no embed found for the param passed). Trigger is more "fire and forget" - it will call the open function if everything goes well, otherwise it silently fails.

Here is an example using an href link that uses the trigger method to open the Overlay -

Note that you must have our master embed code on your page for the above to work and you need to replace EMBED_ID with your embed ID.

The above may also be useful for customers who are using third party site building systems - sometimes putting inline code into a page on those systems can be restricted so you can't add our inline code to render your button. If you can create inline links you could try using the above example with the trigger method to open the Overlay (again remember you also need the master code on the page).

Question 6

How do I use Malcolm! with my own domain or sub-domain?

Accepted Answer

You can use your own domain or sub-domain with Malcolm! There is no extra cost for doing this.

To set this up go to the Settings Section in MyMalcolm then Custom Domains. Enter your custom domain and you will be given instructions on how to verify domain control/ownership and set up your DNS. We can host on SSL too and we'll automatically generate a secure certifcate for you. Once again, there is no extra cost for doing this!

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/x1cCpQ17Io/screenshot-my.malcolm.app-2019.07.30-19_35_49.png (Domain Settings)

Once you have set up your custom domain or sub-domain both that and your malcolm.support / malcolm.app URL will work and serve content. If you don't want the .malcolm domains to work just select the redirect option and any traffic will be redirected.

Watch a video guide to setting uo your own domain below.

Question 7

How does Password Protection of Content (FAQs or Workflows) work?

Accepted Answer

Malcolm! let's you password protect individual items of content (e.g. a particular FAQ or Workflow) and/or your Hosted Hub.

The best option for you will depend on how exactly you use and implement Malcolm!

Password Protection on Hosted Hub

You can add a "start of session" password to your Hosted Hub via the Visibility tab in the Settings section in MyMalcolm.

In this area you can add one or more passwords. For example you could add one password that all your users share, or you could give each user an individual password. You can supply a label/description next to the password in MyMalcolm to remind yourself who that password was created for. From the same area you can suspend or delete previously created passwords, as well as see when passwords were last used.

When a user visits any page on your Hosted Hub they create a web session. The first time they do this they will be asked for their password.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/f2uGLquUY3/Screenshot%202019-04-23%2010.55.25.png (Screenshot 2019-04-23 10.55.25 (2).png)

Password Protection on Individual Content Items

You can also add configure password protection on individual items of content like an FAQ or a Workflow. You do this via the Visibility tab in the Configure section of the individual FAQ or Workflow (which you access via the library in the respective FAQ or Workflow section of MyMalcolm).

The default setting for items of content is that they inherit the settings from the Hub. So if no password is set at a Hub level no password is required to view the content. If a password is set at a Hub level then a password will be required at the start of the user session. If you want to ensure that a password is always required before a particular FAQ or Workflow is accessed you should set it at this content level. Bear in mind however that if you also have a Hub password set and a user starts their session with a direct link to individual content that is password protected they will need to enter two passwords: one to get them into the Hub session and a further password to view the content.

You can also set an individual item of content to never require a password, even if the Hub has a password set. This can be useful if, for example, you want to put all your content behind a Hub password but want to create a Workflow that lets people request access. In this scenario you would create a Workflow for the purpose of requesting access, set it to never require a password then link to it from the text you can configure on the Hub password request screen. When requests come in you can review them and if you approve you can manually set up the user's password.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/I3VJyQJ4IZ/Screenshot%202019-04-23%2010.57.05.png (Screenshot 2019-04-23 10.57.05.png)

Also worth noting

If a user makes three failed password attempts they will not be able to attempt a further password within that session for 30 minutes.

Auth0

We also support managing user passwords via Auth0- see more details here and via Memberstack - see more details here.

Question 8

When a Workflow is completed will I be sent an email?

Accepted Answer

When a user completes a Workflow, by default all the Team members of the instance (who are added and manged via the Team section of MyMalcolm) will receive an email.

You can also configure other people to receive an email on a Workflow by Workflow basis.

To do this:

In MyMalcolm go to the Workflow section
Click Library and then click on the Workflow you wish to configure email alerts for
Then click "Configure" on the black horizontal navigation then "Email Answers" on the left hand vertical navigation
Click "add a new email address" to add a new recipient. This can be a fixed email address you enter or, if you collect an email address on your Workflow, you can choose for the email to be sent to the supplied email
Note that you can also make a recipient conditional - this is very useful if you only want an email to be sent to a particular address when certain criteria on a Workflow are met

Question 9

What are tags for in the Media Section?

Accepted Answer

Tags are a way (along with folders) of helping your organise and label your media.

They can be useful when your media library becomes large. For example, if you use rights managed images in your FAQs you could use tags to help you remember the expiry dates of those rights.

Question 10

How do I add a Gallery, How-to or Step by Step to my FAQ or other content?

Accepted Answer

You can now add clickthrough or swipe through galleries to your content.

Hit the insert images icon in the markdown editor to begin, and then select the images you want to include from your media gallery.

Insert images in MyMalcolm

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/Gp51whKPhC/screenshot-my.malcolm.app-2022.06.09-13_41_40.png (Insert images in MyMalcolm)

You'll then see a dialogue where you can edit the order of the images plus add descriptive text, titles and caption.

Gallery / How-to dialogue in MyMalcolm

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/VmGuJfIuRb/screenshot-my.malcolm.app-2022.06.09-13_41_15.png (Gallery / How-to dialogue in MyMalcolm)

You can choose between a traditional image Gallery or a numbered How-to (sometimes called a Step by Step). These are subtly different and will also be marked up differently using Schema which means Google will see them slightly differently.

Choosing a Gallery or How-to in MyMalcolm

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/yWFMXqJm9Y/screenshot-my.malcolm.app-2022.06.09-13_42_13.png (Choosing a Gallery or How-to in MyMalcolm)

Once you've set things up as you want the markdown will be generated for your Gallery or How-to. If you want to change things just highlight that block of markdown and hit the insert media icon and you'll be taken back into the edit Gallery or How-to dialogue.

A How-to on a hosted hub page

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/bn4yI4KwR7/screenshot-tom-test-15.malcolm.app-2022.06.09-14_05_27.png (A How-to on a hosted hub page)

Remember, as with all content you put into Malcolm! you can surface your Gallery or How-to's in multiple ways - as well as your hosted hub pages they will work in pop up widgets, drawers, overlays and inline page embeds.

See the below video for a walkthrough: