Integration: HTML Forms by Ibericode

HTML Forms is an easy and powerful plugin to build custom forms. Zammad WP supports the free and premium version since version 0.8.0 and adds another action Create Zammad Ticket to individual forms. You can embed forms via shortcodes, editor blocks or code. Additionally Zammad WP supports your custom HTML forms as fallback for the Zammad Live-Chat. So you can add additional fields there, too.

Requirements

As this integration uses the Zammad API, you need to define authentification values as decribed here.

Create Zammad Ticket

When creating a new Create Zammad Ticket action, a first API call is done to fetch your user groups, ticket, states & priorities. So you can e.g. choose for which group a new ticket is created. Furthermore you can customize the subject, message and tags fields. E.g. if you add a custom product field to your form, you can add this to each field with the [PRODUCT] placeholder. This allows you e.g. to save the product value as a tag in the Zammad ticket.

Fields passed to Zammad

By default the form fields NAME, EMAIL, SUBJECT & MESSAGE are used to create the ticket and article as by the Zammad API documentation If a user does not exist, Zammad WP creates one first.

Pass additional fields

If you create a complex form and you have set up additional fields for Zammad objects (user or ticket), you propably want to pass some form values to that Zammad object:

Pass values to ticket object

Please use the zammad_wp:hf_action:ticket_fields filter. Let's say you have the form input PRODUCT and in Zammad an additional object field product for tickets set up.

/**
 * Maps additional ticket fields
 * HTML Form Values -> Zammad Ticket
 */
add_filter('zammad_wp:hf_action:ticket_fields', function ($fields, $subscription) {
	// Fields passed to Zammad Ticket
	$fields['product'] = $subscription->data['PRODUCT'];

	return $fields;
}, 10, 2);

Pass values to user object

Same concept as above, please use the zammad_wp:hf_action:user_fields instead:

/**
 * Maps additional user fields
 * HF Form Values -> Zammad User
 */
add_filter('zammad_wp:hf_action:user_fields', function ($fields, $subscription) {
	// Fields passed to Zammad User
	$fields['country'] = $subscription->data['COUNTRY'];

	return $fields;
}, 10, 2);

Custom Form as Chat Fallback

Zammad WP extends the native Zammad functionality e.g. with a fallback form in the live-chat, if no agent is online or the user waited too long. By default Zammad WP uses the default Form you can set up in your Zammad settings. However that form is very limited, e.g. you can not add additional fields. To overcome the limitations, you can define your own HTML which is displayed as fallback. This includes a custom HTML Form:

zammad_register_chat(1, [
	'formFallback' => true,
	'formFallbackHTML' => hf_get_form('my-custom-fallback-form'),
]);

Limitation

Currently you can only create tickets on your main Zammad instance, defined in wp-config.php. In a future version, we might add the possibility to choose custom Zammad credentials for each form action. Furthermore values are only passed to Zammad user & ticket object. We might support other objects such as Groups, Organization, etc. in the future, too.