Integrating Wix Forms with SendSquared: A Technical Overview

This guide explains how to integrate your Wix forms with the SendSquared API using Velo by Wix (formerly Corvid). When a form is submitted on your Wix site, the integration will send the visitor's information to SendSquared, allowing you to build your contact list automatically.

warning

IMPORTANT: Before implementing this integration, you will need a Wix site with Editor X or Wix Editor, the Velo development environment enabled, and your SendSquared API token.

Prerequisites

• A Wix site with Velo development enabled
• A form on your Wix site
• Your SendSquared list group UUID (token)
• Basic knowledge of JavaScript

Implementation Steps

1. Enable Velo by Wix

If you haven't already enabled Velo for your site:

1. Open your Wix site in the Editor
2. Click on the Dev Mode icon in the top bar (it looks like </>)
3. Click Turn on Dev Mode

2. Add Custom Code to Your Form

Follow these steps to add the integration code:

1. In the Wix Editor, click on your form to select it
2. Click on Settings (the gear icon)
3. Note the ID of your form (e.g., #contactForm)
4. Click on the Dev Mode icon again
5. Select Page Code from the menu

3. Add the Integration Code

Copy and paste the following code into your page code editor. Make sure to customize it with your form's ID and field IDs, as well as your SendSquared token.

import {fetch} from 'wix-fetch';

$w.onReady(function () {
  // Replace 'contactForm' with your form's ID
  $w('#contactForm').onSubmit((event) => {
    
    // Get the form data - update these with your actual field IDs
    const email = $w('#emailInput').value;
    const name = $w('#nameInput').value;
    
    // Set the API URL with your SendSquared token
    const token = "your-list-group-uuid";
    const apiUrl = `https://app-api.sendsquared.com/v1/pub/popup?token=${token}`;
    
    // Set up the API data
    const apiData = {
      email: email,
      name: name
    };
    
    // Send the data to the SendSquared API
    return fetch(apiUrl, {
      method: 'post',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(apiData)
    })
    .then((response) => {
      if (response.ok) {
        // Optionally show a success message
        $w('#successMessage').show();
        return response.json();
      } else {
        // Handle errors
        $w('#errorMessage').show();
        throw new Error('Failed to send data to SendSquared');
      }
    })
    .catch((error) => {
      console.error('Error:', error);
      $w('#errorMessage').show();
    });
  });
});

4. Create Success and Error Messages

Add text elements to your page for success and error messages:

1. Add two text elements to your page
2. Set their IDs to #successMessage and #errorMessage
3. Set their default visibility to "Hidden" in the Properties panel
4. Customize their text content as needed

5. Save and Publish Your Changes

1. Click Save in the Velo editor
2. Publish your site to make the changes live

Additional Customization

Adding More Form Fields

You can modify the code to include additional fields from your Wix form:

// Example of adding additional fields
const apiData = {
  email: $w('#emailInput').value,
  name: $w('#nameInput').value,
  phone: $w('#phoneInput').value,
  '-custom_field': $w('#customInput').value
};

Make sure that any additional fields you add are supported by the SendSquared API.

Conditional Form Submission

You can add conditions to only send certain form submissions to SendSquared:

$w('#contactForm').onSubmit((event) => {
  // Get form data
  const email = $w('#emailInput').value;
  const subscribeChecked = $w('#subscribeCheckbox').checked;
  
  // Only send to SendSquared if the subscribe checkbox is checked
  if (subscribeChecked) {
    // Your SendSquared API code here
  }
  
  // Always submit the form normally
  return true;
});

Handling Different Forms on the Same Page

If you have multiple forms on the same page:

$w('#contactForm1').onSubmit((event) => {
  // First form submission code
});

$w('#contactForm2').onSubmit((event) => {
  // Second form submission code
});

Advanced Integration: Using Lead With Contact API

For more advanced use cases where you need to capture leads in SendSquared, you can use the Lead With Contact API. This allows you to create both a contact record and a lead record in a single API call, which is ideal for businesses that want to track potential customers through the sales process.

Prerequisites for Lead Integration

• Your SendSquared API key (different from the list group UUID)
• Your SendSquared lead type ID
• Your SendSquared lead status ID
• Your SendSquared user ID (for lead assignment)
• Your SendSquared source ID (optional)

Implementation Steps for Lead Integration

1. Create a new form in Wix with fields for name, email, phone, and other relevant information
2. Add the following Velo code to handle the form submission:

import {fetch} from 'wix-fetch';

$w.onReady(function () {
  // Replace 'leadForm' with your form's ID
  $w('#leadForm').onSubmit((event) => {
    
    // Get the form data - update these with your actual field IDs
    const email = $w('#emailInput').value;
    const firstName = $w('#firstNameInput').value;
    const lastName = $w('#lastNameInput').value;
    const phone = $w('#phoneInput').value; // Must be in E.164 format (+1XXXXXXXXXX)
    const interest = $w('#interestInput').value;
    const notes = $w('#notesInput').value;
    
    // Format current date in ISO format
    const now = new Date().toISOString();
    
    // Contact data structure
    const contactData = {
      'email': email,
      'first_name': firstName,
      'last_name': lastName,
      'mobile_phone': phone // must be in E.164 format (+1XXXXXXXXXX)
    };
    
    // Lead data structure
    const leadData = {
      // Update these IDs with your actual SendSquared IDs
      'lead_type_id': 116, // Update with your lead type ID
      'lead_status_id': 504, // Update with your lead status ID
      'subject': `Interested in ${interest}`,
      'interest_start_at': now,
      'interest_end_at': now,
      'quantity_1': 1, // Number of adults - customize as needed
      'quantity_2': 0, // Number of children - customize as needed
      'notes': [notes],
      'user_id': 1446, // Update with your agent user ID
      'source_id': 0,  // Update with your source ID if needed
    };
    
    // Prepare request data
    const requestData = {
      'contact': contactData,
      'lead': leadData
    };
    
    // Send data to the SendSquared API
    return fetch('https://api.sendsquared.com/v1/leads/lead-with-contact', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        // Update with your actual API key
        'x-api-key': 'your-api-key-here'
      },
      body: JSON.stringify(requestData)
    })
    .then((response) => {
      if (response.ok) {
        // Optionally show a success message
        $w('#successMessage').show();
        return response.json();
      } else {
        // Handle errors
        $w('#errorMessage').show();
        throw new Error('Failed to send lead to SendSquared');
      }
    })
    .catch((error) => {
      console.error('Error:', error);
      $w('#errorMessage').show();
    });
  });
});

Customizing the Lead Data

You can modify various aspects of the lead data to match your business needs:

// Example of customized lead data
const leadData = {
  'lead_type_id': 116,
  'lead_status_id': 504,
  'subject': `${firstName} ${lastName} - ${interest} Inquiry`,
  'interest_start_at': now,
  'interest_end_at': addDays(now, 30), // Set end date 30 days in future
  'quantity_1': parseInt($w('#adultsInput').value) || 1,
  'quantity_2': parseInt($w('#childrenInput').value) || 0,
  'notes': [
    `Interest: ${interest}`,
    `Budget: ${$w('#budgetInput').value || 'Not specified'}`,
    `Additional notes: ${notes}`
  ],
  'user_id': 1446,
  'source_id': 0
};

// Helper function to add days to date
function addDays(dateString, days) {
  let date = new Date(dateString);
  date.setDate(date.getDate() + days);
  return date.toISOString();
}

Troubleshooting

If your integration isn't working properly, check these common issues:

1. Verify that your Wix form IDs and input element IDs match exactly what you've specified in the code
2. Confirm that your SendSquared token or API key is correct
3. Check your browser console for any JavaScript errors (use F12 to open Developer Tools)
4. Ensure your Wix site has proper permissions to make outgoing HTTP requests
5. Verify that the SendSquared API endpoint is accessible
6. For the Lead API, ensure phone numbers are properly formatted in E.164 format (+1XXXXXXXXXX)
7. Check that the Lead Type ID, Lead Status ID, and User ID are valid in your SendSquared account

Debugging Tips

You can add logging to help debug issues:

$w('#contactForm').onSubmit((event) => {
  const email = $w('#emailInput').value;
  
  console.log('Form submitted with email:', email);
  
  // Rest of your code...
  
  return fetch(apiUrl, {
    method: 'post',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(apiData)
  })
  .then((response) => {
    console.log('SendSquared API response status:', response.status);
    return response.json();
  })
  .then((data) => {
    console.log('SendSquared API response data:', data);
    // Rest of your code...
  });
});

For additional support, contact SendSquared support at support@sendsquared.com or +1.855.340.7363.

Frequently Asked Questions

How do I test the Wix integration without affecting live data?

To test safely:

1. Create a test list in SendSquared for development purposes
2. Use the test list's UUID/token during development
3. Submit test data with obvious test names (e.g., "Test User Test")
4. Use Wix's preview mode to test before publishing
5. Check browser console for any JavaScript errors or API responses
6. Test with a staging site or unpublished page first
7. Switch to production credentials only after thorough testing

What happens if the SendSquared API is temporarily down?

The Wix Velo integration includes error handling that will:

• Log errors to the browser console without breaking the form submission
• Allow the form to still submit normally to Wix's form handling system
• Display appropriate error/success messages to users based on your implementation
• Not prevent the user from completing their form submission
• You can implement retry logic or local storage for failed submissions

Can I integrate multiple Wix forms with different SendSquared configurations?

Yes! You can handle multiple forms in your Velo code:

import {fetch} from 'wix-fetch';

$w.onReady(function () {
  // Newsletter form
  $w('#newsletterForm').onSubmit((event) => {
    return handleFormSubmission('newsletter-form', 'newsletter-list-uuid');
  });
  
  // Contact form
  $w('#contactForm').onSubmit((event) => {
    return handleFormSubmission('contact-form', 'contact-list-uuid');
  });
  
  // Lead form using Lead API
  $w('#leadForm').onSubmit((event) => {
    return handleLeadFormSubmission();
  });
});

function handleFormSubmission(formType, token) {
  // Your integration logic here
}

How do I handle form validation errors from the SendSquared API?

You can enhance error handling for better user experience:

return fetch(apiUrl, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify(apiData)
})
.then((response) => {
  if (response.ok) {
    $w('#successMessage').show();
    $w('#errorMessage').hide();
    return response.json();
  } else {
    return response.json().then(err => {
      let errorMsg = 'There was an error submitting your form.';
      if (response.status === 422) {
        errorMsg = 'Please check your email format and phone number.';
      } else if (response.status === 401) {
        errorMsg = 'Authentication error. Please try again.';
      }
      $w('#errorMessage').text = errorMsg;
      $w('#errorMessage').show();
      $w('#successMessage').hide();
      throw new Error(err.message || 'API Error');
    });
  }
})
.catch((error) => {
  console.error('Error:', error);
  $w('#errorMessage').show();
  $w('#successMessage').hide();
});

What data formats are required for SendSquared API fields?

• Email: Valid email format (Wix provides built-in email validation)
• Phone: Must be in E.164 format (+1XXXXXXXXXX for US numbers) for Lead API
• Names: String values, can handle Unicode characters
• Dates: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) for Lead API
• IDs: Integer values (lead_type_id, lead_status_id, user_id, source_id)
• Notes: Array of strings for Lead API
• Boolean values: true/false for checkboxes and radio buttons

Is the Wix integration GDPR compliant?

The integration respects GDPR requirements:

• Only processes data after explicit form submission by the user
• Doesn't store data locally beyond Wix's standard form handling
• Transmits data securely via HTTPS to SendSquared
• You should add GDPR consent elements to your Wix forms
• Consider adding privacy policy links near your forms
• Wix has built-in GDPR compliance features you can enable in your site settings

Can I update existing contacts instead of creating duplicates?

Yes, both SendSquared APIs handle this automatically:

• Popup API: Updates existing contacts with matching email addresses
• Lead with Contact API: Updates existing contacts and creates new leads linked to them
• Email serves as the unique identifier for contact matching
• Multiple leads can be associated with the same contact

What are the API rate limits for SendSquared?

SendSquared API limits:

• 1000 requests per hour per API key
• 10 concurrent requests maximum
• For high-volume forms, consider implementing:
  • Request queuing for peak times
  • Client-side throttling of form submissions
  • Contact SendSquared support for higher limits if needed
• The integration handles rate limiting through error handling and user feedback

Can I track form submissions with analytics?

Yes! You can integrate with various analytics platforms:

.then(data => {
  console.log('SendSquared success:', data);
  
  // Google Analytics 4
  if (typeof gtag !== 'undefined') {
    gtag('event', 'form_submission', {
      'event_category': 'engagement',
      'event_label': 'contact_form'
    });
  }
  
  // Wix Analytics
  import { analytics } from 'wix-analytics';
  analytics.track('Form Submission', {
    formType: 'contact',
    source: 'website'
  });
  
  $w('#successMessage').show();
});