WordPress forms setup guide

Status	Kind	How you connect
Coming soon	Lead source	The bubbl3 form snippet on your site, a Make template or an n8n template

This guide is coming soon: bubbl3 is still checking it end to end. It shows how WordPress forms will send leads to bubbl3, with nothing to install.

What it does

Each submission of a form on your WordPress site becomes (or updates) a bubbl3 contact, with the page, UTM parameters and the consent wording the visitor saw, and can start the lead source's workflow. Either paste the bubbl3 form snippet into the page, or send your form plugin's webhook through a Make or n8n template.

Before you start

• A bubbl3 lead source: a website form source for the snippet (with your site's address in its allowed origins), or a Lead URL source for Make or n8n. In Settings, Integrations, under Lead sources, set its labels, owner, consent setting and workflow.
• For Make or n8n, a form plugin that can send a webhook with a JSON body you choose (for example the webhooks add-ons of WPForms or Gravity Forms).

Setup

With the form snippet

1. Copy the form source's snippet from its page in bubbl3.
2. In the WordPress editor, add a Custom HTML block where the form goes and paste the snippet, keeping each field's name: first_name, phone, email.
3. Publish, and send a test with a test phone number. It shows on the source as received.

The lead forms quick-start explains the snippet, its consent wording and its limits.

With Make or n8n

1. Create a Lead URL source, then import the Make blueprint or the n8n workflow below and paste its id and secret where the template says.
2. Copy the address of the template's first step (Make: the Webhooks module; n8n: the Webhook node's production URL).
3. In your form plugin's webhook settings, add that address with method POST, JSON format, (with n8n) a request header matching the Webhook node's Header Auth credential, and these body keys mapped to your form's fields: id (the entry id), phone, first_name, last_name and email.
4. Submit the form once with a test phone number. It shows on the source as received. Then turn the scenario on (Make) or activate the workflow (n8n).

Templates

Each template takes WordPress forms's webhook, sets the lead's fields, signs the lead with your lead source's secret and sends it to bubbl3, with WordPress forms's record id as the idempotency key, so a retry is the same lead. It never texts anyone itself: your lead source's consent setting and workflow decide what happens next.

• Make blueprint: in Make, create a scenario, open the … menu, choose Import Blueprint and pick the file.
• n8n workflow: in n8n, open a new workflow, open the … menu, choose Import from File and pick the file.

In the n8n workflow's Webhook node, replace the path replace-with-a-long-random-value with a long random value (a new UUID is fine) before you activate it. Anyone who knows the address can post to it, and the workflow would sign what they post, so the path must be one nobody can guess. The node also checks a header: create a Header Auth credential with a header name (such as X-Webhook-Key) and a long random value, choose it on the node (it's named "bubbl3 webhook header"), and have WordPress forms send that header, as the Setup steps say. Make's webhook address is random already.

After importing, replace PASTE_THE_SOURCE_ID with your lead source's id and PASTE_THE_SOURCE_SECRET with its signing secret. Anyone who can edit the scenario or workflow can read the secret, so share it only with people who could manage the lead source; rotate the secret in bubbl3 if it leaks.

Data shared

From WordPress to bubbl3: the submission's fields; with the snippet, also the page, UTM parameters and click ids, and the consent wording shown.

From bubbl3 to WordPress: nothing.

Sending rules that still apply

WordPress forms never texts anyone itself. What it sends bubbl3 can start the lead source's workflow, and every workflow text goes through the same checks as a text you send from bubbl3. Nothing in WordPress forms can turn them off.

• Consent. When you connect WordPress forms or create a lead source, you confirm that everyone you send to bubbl3 has agreed to receive texts from you, so its contacts can be texted straight away. bubbl3 never texts a contact who opted out, and a workspace set to text only opted-in contacts texts only them.
• Opt-out. Replying STOP opts a contact out at once.
• Quiet hours. No texts from 8:00 PM to 9:00 AM in the contact's own time zone (from the phone's area code). A text due then waits until the morning.
• Pacing. Each line texts at most 15 new contacts an hour and 50 a day (fewer while a new line warms up), and spaces texts 20 to 90 seconds apart. A big import or batch is queued and sent as the limits allow, never dropped.
• First messages. Until a contact replies, a text can't include links, photos or files, phone numbers or email addresses, must be 300 characters or fewer, and at most 3 texts go out.

What WordPress forms is told when bubbl3 doesn't send

WordPress forms isn't told when bubbl3 doesn't send a text: the reason shows on the message in bubbl3, and in the message.status webhook if you use one.

Reason	Code	What you see
A link before the contact replies	pre_reply_link_blocked	Not sent: "Links can't be sent until the contact replies"
A photo or file before the contact replies	pre_reply_media_blocked	Not sent: "Photos and files can't be sent until the contact replies"
A phone number before the contact replies	pre_reply_phone_blocked	Not sent: "Phone numbers can't be sent until the contact replies"
An email address before the contact replies	pre_reply_email_blocked	Not sent: "Email addresses can't be sent until the contact replies"
A first message that is too long	pre_reply_too_long	Not sent: "First messages must be 300 characters or fewer"
Too many texts without a reply	pre_reply_message_limit	Not sent: "Already sent 3 texts without a reply. Wait for the contact to reply"
The same text to too many people today	identical_text_limit	Not sent: "This exact text went to 20 people from this line today"
The line is paused after unanswered texts	unanswered_streak_limit	Not sent: "This line is paused after too many unanswered texts"
The contact opted out	contact_opted_out	Not sent: "The contact opted out of texts"
The workspace texts only opted-in contacts	consent_required	Not sent: "This workspace only texts contacts who opted in"
No line can reach the contact	line_unavailable	Not sent: "bubbl3's line for this contact isn't available"
Quiet hours	quiet_hours	Held: "Scheduled for 9:00 AM America/Chicago, quiet hours"
The line's daily limit	daily_new_contact_cap	Held: "Scheduled for Oct 15, 9:00 AM America/Chicago: today's limit for this line is reached"
The line's hourly limit of new contacts	hourly_new_contact_cap	Held: "Scheduled for 2:00 PM America/Chicago: this hour's limit of new contacts for this line is reached"

The numbers are the default limits; a line's own limits change them. bubbl3's other checks (no phone number, a number that doesn't match) have their own plain reasons.

Limits and known gaps

• A form source adds at most 500 new contacts a day, and a lead for someone you already have only records the lead and adds the source's labels. A Lead URL source has no cap.
• Caching and security plugins can strip scripts from a page; if the snippet's form does nothing, check them.
• A submission without a phone number is refused with "A lead needs a phone number".

Troubleshooting

• The snippet's form says it failed. Check the page's address is in the source's allowed origins, and your site's content security policy allows the bubbl3 API.
• 403 from bubbl3 in Make or n8n. Check the source id and secret, and that the source isn't paused.