Webform v1 Deprecation note

With introducing the attachment upload, our webform version 1 is being deprecated. In order for the attachment upload to work, make sure that you are targeting the v2/forms/ endpoint. Also, ensure that you are using the multipart/form-data type of form. You can see examples below which specify the type of form.


Description

You want to offer as many opportunities for your customers to engage with you. One of them is to fill in a branded webform on your website. Starting such conversations via a webform can now be a seamless experience: With our API, a new conversation in Dixa is created, whenever someone has filled out your webform.

  • Use your own custom webforms with your own branding to create conversations. 🎨ℹ️
  • Create conversations directly via the API - without converting to email first. 📧 ❌
  • Important attributes or text format won’t get lost in translation. 🤷‍♂️💪

Setup for Webform Endpoints in Dixa

In order to set up the new webform endpoints, you need to be a Dixa administrator, as you need access to the settings of your organisation in Dixa. From here you can use the email routing and make sure that flows are triggered for the new conversations that you create via the API endpoint.

1. Go to Settings > Integrations > Webform Endpoints

2. Choose "Add webform endpoint"

3. Fill in the required details:

  • Email: Choose the email address that will be used to route the conversations that you are creating from your webform.
  • Name: Type a name here, so you can recognise your webform integration easily later.
  • Redirect URL: In case you are using the webform integration directly in your website code, please choose a redirect URL where the user should be directed to after submitting the webform. Ideally this would be a success page with a thank you message. The redirect URL is optional but recommended, so that Dixa can redirect to the specified URL after a successful submission of the form.

4. Choose "Add new endpoint" to save the settings
 and reveal the uniquely generated URL that you can now insert in your webform:

Using Webform Endpoints

The webform endpoints can receive multiple fields:

  • Required fields (please make sure that the naming is correct here in order to avoid errors):
    • Email: <input type="email" name="email" required> (The email field input will be used for contact recognition or to create a new contact in Dixa.)
    • Message: <input type="text" name="message" required>
  • Optional fields:
    • Phone: <input type="text" name="phone_e164"> (The e164 format requires a +country code followed by the national phone number. Please make sure to convert phone numbers in your forms to this format before submitting.)
    • Subject: <input type="text" name="subject"> (This will be used as the conversation subject in Dixa.)
    • Name: <input type="text" name="name"> (This refers to first name and last name combined in one field. The name will not automatically overwrite an existing contact name, but will be used in case a new contact is created.)
    • Attachments: <input type="file" name="attachments"> (This will create a file upload input. Current limitation of files is set to 5 , while the allowed form size is up to 10MB. Important: Make sure that form is set to enctype="multipart/form-data" and the v2 endpoint is used to successfully make an attachment upload.)
    • Custom fields: <input type="text" name="my_custom_field"> (Here you can add as many fields as you like and name them however you like.)

All fields that are sent from the webform will be added as content to the created conversation in Dixa.

Webform response example:

csid - created conversation id

{
"csid": 1234
}

With introducing attachment upload, our webform version 1 is being deprecated. In order for the attachment upload to work, make sure that you are targeting the v2/forms/ endpoint. Also, ensure that you are using multipart/form-data type of form. You can see examples below which specify the type of form.

Example for how to use the webform endpoints:

Highlighted in purple you can see here how to add the URL that you received from the webform endpoint setup into your webform: 

<form method="post" action="https://forms.dixa.io/v2/forms/734UO5aJSvUB6t12XJeV1S/wnWMml0UgK7j1x5Yubh2s" enctype="multipart/form-data">
 <input type="email" name="email" required> <br>
 <input type="text" name="name"> <br>
 <input type="text" name="subject"> <br>
 <input type="text" name="message" required> <br>
 <input type="text" name="phone_e164"> <br>
<input type="text" name="my_custom_field"> <br>
 <input type="file" name="attachments"> <br>
 <input type="submit" value="Go!">
</form>

Example for how to use it via curl:

Using curl you can create conversations directly via the webform endpoints of the Dixa API, so you can create conversations from e.g. any of your internal systems:

curl -F "Cat+name=Figaro" -F "Order+No=343434" -F "email=akb@dixa.com" -F "message=I would like to know why my cat food order has not arrived yet?" https://forms.dixa.io/v2/forms/734UO5aJSvUB6t12XJeV1S/wnWMml0UgK7j1x5Yubh2s

Example for how to use it with JavaScript (in browser): 

You can also create a script to run from the browser. Make sure that the request does not contain any custom headers or Content-Type (the browser should automatically deduce the content type from passed FormData object to body), otherwise the request could fail with CORS error. In order to post a file with JavaScript, see article for details.  See example:

const formData = new FormData()
formData.append('name', 'Dixa')
formData.append('subject', 'Example subject')
formData.append('email', 'akb@dixa.com')
formData.append('message', 'Example message')

fetch('https://forms.dixa.io/v2/forms/734UO5aJSvUB6t12XJeV1S/wnWMml0UgK7j1x5Yubh2s', {method: 'POST', body: formData})
  .then(r => r.json())
  .then(v => console.log('Received data:', v))
  .catch(e => console.error('An error has occurred :(', e))

Webform Conversations in Dixa

In Dixa you will receive the conversations created via the webform endpoints as contact form submissions. The conversation will be routed according to the same flow as the email address that you have chosen during the setup.

The conversation will include all the form fields from your webform and will either be attributed to an existing contact with the same email address or to a newly created contact.

Limitations

  • Webform endpoints can currently not be edited, but only deleted.