← Documentation

Zulip

Zulip is an open-source team collaboration tool with unique topic-based threading that combines the best of email and chat to make remote work productive and delightful. Fortune 500 companies, leading open source projects, and thousands of other organizations use Zulip every day. The Zulip add-on enables seamlessly integrations of WordPress forms with your chat platform to get your teams automatically notified of new submissions.

The add-on

The Zulip REST API powers the Zulip web and mobile apps, so anything you can do in Zulip, you can do with Zulip’s REST API. To talk with this API, the add-on works with an extension of the generic REST bridge class.

A Zulip bridge will notify your form submissions to chat streams and topics, 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 streams 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 basic 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 Basic HTTP credential based on an API key. You can use the API key of a standard user or generate a bot for this purpose.

To generate a bot you have to open the account settings, switch to the Organization tab and open the Bots section. From there, click on Add a new bot and then create a new Generic bot with a name and an email. Once created, you can open the edit panel of the bot to get its API key.

To generate a user API key go to the Account and privacy section of the user account settings, and click on the Manage your API key button to get its API key shown in the screen.

Back on WordPress, you have to fulfill the credential step form with a unique name to identify the credential, the bot or user email and its API key.

2. Backend

The backend step will require you to set a unique name to identify the new connection and the URL of your Zulip workspace. If you’re using the Zulip Cloud service, the backend URL should looks like https://your-organization.zulipchat.com.

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 Zulip bridge will require the following components:

1. Credential

To configure the Zulip REST API as a backend to be used on your form bridges you will need an API key. You can use the API key of a standard user or generate a bot for this purpose.

To generate a bot you have to open the account settings, switch to the Organization tab and open the Bots section. From there, click on Add a new bot and then create a new Generic bot with a name and an email. Once created, you can open the edit panel of the bot to get its API key.

To generate a user API key go to the Account and privacy section of the user account settings, and click on the Manage your API key button to get its API key shown in the screen.

With your API key on the clipboard, go to Settings > Forms Bridge > HTTP > Authentication on your WordPress admin page and register a new authentication credential.

Select Basic as the authentication schema and set bot or user email as the Client ID and your API key as the Client secret. In addition, you have to choose a unique name to identify this new credential.

2. Backend

To configure the Zulip REST API as a backend follow this steps:

1. Add a new backend with a unique name (Zulip API, for example)
2. Set the backend URL to https://{workspace-name}.zulipchat.com replacing the workspace-name param with the name of your workspace or organization.
3. Select JSON as the Encoding Schema.
4. Add Accept as an HTTP header with application/json as value.
5. Select the Basic 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, a form, an endpoint and an HTTP method. 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 Zulip REST API. To get a comprehensive list of the available endpoints you can check the official documentation. For example, to get your subscription form bridged you have to set the bridge endpoint to /api/v1/messages.

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
   • Check the email and API key of the backend credential.
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 content field of the payload.

Templates

The add-on comes packed with the following templates:

• Contacts Stream 🔎
  Contact form template. The resulting bridge will notify form submissions in a Zulip stream

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

• Support Stream 🔎
  Support form template. The resulting bridge will notify form submissions in a Zulip stream

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

Workflow jobs

The addon comes packed with the following workflow jobs:

• Fields summary 🔎
  Format the payload fields field as a markdown 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