← Documentation

Slack

Slack is a cloud-based communication hub built for productivity with instant messaging, voice and video calls, and numerous app integrations. The Slack add-on enables seamlessly integrations of WordPress forms with your chat platform to get your teams automatically notified of new submissions.

The add-on

Every Slack app and workflow has access to a range of APIs that provide access to read, write, and update many types of data in Slack. To talk with this APIs, the add-on works with an extension of the generic REST bridge class. This APIs use the OAuth 2.0 protocol for authentication and authorization.

A Slack bridge will notify your form submissions to slack channels or as direct messages. The add-on comes with a suit of templates to set up different types of forms to be bridged to user support channels or new contacts feeds. In addition, the add-on has a special workflow job to summarize form submissions as markdown lists that allows you to crawl user responses as chat messages.

How to use

The first step to use the add-on is to activate it on the add-ons table on the general settings tab.

Once activated, a new tab will be visible on the settings page. If it’s your first time, it should looks like this:

The template wizard

The recommended way to set up a new bridge is to use a template as a starter point. The add-on’s template wizard will set up a new backend connection, a Bearer HTTP credential and a form, all of them linked on a new bridge.

With this setup ready, you can edit the bridge’s form to fit your requirements or manually add new forms and bridge them with the backend you’ve configured on the previous step.

The template wizard will lead you through four steps:

1. Credential

On this step, Forms Bridge will register a new Bearer HTTP credential. To set up this authentication, you have to register a new Slack app and get its Client ID and Client Secret.

To properly create the app, go to the Slack apps manager and click on Create New App to create a new app From scratch. Set a name to identify it (Forms Bridge, for example) and bind it to your workspace.

Once created, open the app settings, go to OAuth & Permissions and register the URL https://example.coop/wp-json/forms-bridge/v1/oauth/redirect replacing example.coop with your WordPress site domain as a Redirection URL.

Next, you’ll need to request scopes for your app. To work properly, Forms Bridge requires this app to have the following scopes:

• chat:write.public To send messages to public channels without the need of being a member.
• chat:write: To send messages.
• channels:read To retrieve the list of available channels.
• users:read To retrieve the list of available users.
• files:write To upload form submission attachments to Slack.

Now return to the Basic Information section of the app management page and copy the Client ID and Client Secret. With this to tokens on the clipboard, go back to WordPress and fulfill the credential fields with them.

Once you’ve done with the form, the wizard will ask you to authorize the new credential. Click on the Authorize button and you will be redirected to the consent screen of Slack. Install the app in your workspace and then you will be redirected to the plugin settings page.

2. Backend

The backend step will require you to set a unique name to identify it and then it will check if the authorization is granted.

3. Form

In this step you have to choose the title of the form the template are going to create. If there is a compatible form, the wizard allows you to reuse the existing form and skip the form creation.

4. Bridge

On the last step of the wizard, you have to set a unique name for the new bridge. In addition to the name, and depending on the template you are using, this step will require more or less fields to be informed. The required fields will be marked with a red asterisk

After that, click on submit and Forms Bridge will generate the credential, backend, form and bridge settings. It only remains to publish the new form on a public page and wait for a new form submission!

Manual set up

With templates, you can save a lot of time while configuring your bridges, but you can achieve the same result with a manual set up.

A Slack bridge will require the following components:

1. Credential

To configure the Slack Web API as a backend to be used on your form bridges you should have an Slack app registered in the Slack apps managers as it has been described before.

Once you get the Client ID and Client secret of the app, you have to go to Settings > Forms Bridge > HTTP > Authentication and register a new authentication credential.

Select Bearer as the authentication schema and put the Client ID and Client secret in the respective fields. For the Authorization URL, you have to set https://slack.com/oauth/v2, and chat:write,chat:write.public,channels:read,users:read,files:write as the value for the Scope.

Once registered, Forms Bridge will ask you to Authorize the new credential. Click on the button and a new browser’s tab will be opened asking you for the authorization to Forms Bridge to be installed in your slack workspace. Click on Install and then you will be redirected again to the HTTP tab of the plugin settings page with your credential authorized.

2. Backend

To configure the Slack Web API as a backend follow this steps:

1. Add a new backend with a unique name (Slack API, for example)
2. Set the backend URL to https://slack.com.
3. Select JSON as the Encoding Schema.
4. Add Accept as an HTTP header with application/json as value.
5. Select the Bearer credential you’ve configured on the previous step.

3. Form

Get your preferred form builder and create a new form. Once created, you can choose it as the target form to be bridged on the bridges panel of the add-on and use field mappers to make your form submissions conform with the messages endpoint interface.

4. Bridge

The add-on’s bridge is an extension of the generic REST bridge. Because of this they looks so similar. Like the REST bridge, the add-on’s bridge requires a unique name, a backend and a form. In addition, we encourage you to use the summary workflow job of the add-on to get your form submission formatted as markdown text.

The bridge endpoint has to exists on the Slack APIs. To get a comprehensive list of the available endpoints you can check the official documentation. For example, to get your subscription form notified as channel messages you have to set the bridge endpoint to /api/chat.postMessage.

Troubleshooting

To troubleshooting your bridges you can use the plugin’s debug console from the General Settings page. Enable the debug mode and submit a sample form response to see what’s going on under the hood. Take a look to our tutorial about how to use the debug console.

Common issues

1. Authentication failures
   • Verify OAuth credentials
   • Check scope permissions
   • Check the credential has granted authorization
2. Missing data
   • Verify that the endpoint exists with the official documentation.
   • Validate field mappings using the bridge endpoint introspection.
   • User responses should be passed formatted as a string value inside the text or markdown_text field of the payload.

Templates

The add-on comes packed with the following templates:

• Contacts Channel 🔎
  Contact form template. The resulting bridge will notify form submissions in a Slack channel

• Direct Messages 🔎
  Contact form template. The resulting bridge will send form submissions as direct messages on Slack

• Support Channel 🔎
  Support form template. The resulting bridge will notify form submissions in a Slack channel

• Woo Orders 🔎
  WooCommerce orders form template. The resulting bridge will notify new woocommerce customers to Slack channels

Workflow jobs

The addon comes packed with the following workflow jobs:

• Fields MD summary 🔎
  Format the payload fields field as a markdown list

• Fields summary 🔎
  Format the payload fields field as a text list

• Format date fields 🔎
  Gets date, hour and minute fields and merge its values into a date with format Y-m-d H:M:S

• ISO2 country code 🔎
  Gets the ISO2 country code from country names and replace its value

• ISO3 country code 🔎
  Gets the ISO3 country code from country names and replace its value

• Skip submission 🔎
  Skip submission if condition is not truthy

Supported form builders