Skip to main content

Airtable setup guide

StatusKindHow you connect
Coming soonOtherA Make template, an n8n template or a Zap

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

What it does​

When a record is added to an Airtable table, an Airtable automation (or Zapier) sends it on. Make, n8n or a Zap signs it with your bubbl3 lead source's secret and sends it to bubbl3, so each record becomes (or updates) a bubbl3 contact and can start the source's workflow.

Before you start​

  • An Airtable table with a phone number field.
  • A bubbl3 Lead URL for Airtable: in Settings, Integrations, under Lead sources, add a Lead URL source, set its labels, owner, consent setting and workflow, and copy its id (src_...) and signing secret, which is shown once.

Setup​

With Make or n8n​

  1. Import the Make blueprint or the n8n workflow below, and paste the source 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 Airtable, add an automation: trigger When a record is created (or enters a view), action Run a script that posts the record to that address, with input variables for the record's id and fields:

    const { id, phone, first_name, last_name, email } = input.config();
    await fetch('YOUR_TEMPLATE_WEBHOOK_ADDRESS', {
      method: 'POST',
      // With n8n, the same header and value as the Webhook node's Header Auth credential.
      headers: { 'content-type': 'application/json', 'X-Webhook-Key': 'YOUR_HEADER_VALUE' },
      body: JSON.stringify({ id, phone, first_name, last_name, email }),
    });

  4. Test the automation with a record that has a test phone number. The lead shows on the source as received.

  5. Turn the scenario on (Make) or activate the workflow (n8n), then turn the automation on.

With Zapier​

  1. In Zapier, create a Zap with the Airtable trigger New Record.
  2. Add a Code by Zapier step (Run JavaScript) with the code below. In Input Data, add source_id, source_secret, tool set to airtable, record_id mapped to the record's id, and phone, first_name, last_name and email mapped to its fields.
  3. Test the step, then turn the Zap on.

Templates​

Each template takes Airtable's webhook, sets the lead's fields, signs the lead with your lead source's secret and sends it to bubbl3, with Airtable'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 Airtable 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.

The Zap's Code step​

Zap templates are made in Zapier's own editor, so this is a recipe: add a Code by Zapier step (Run JavaScript) after your Airtable trigger, map the Input Data names in the code's first lines, and paste this code. It signs the lead and sends it to your lead source, with Airtable's record id as the idempotency key.

Code by Zapier
// Code by Zapier (JavaScript): sends one lead to a bubbl3 lead source, signed with its secret.
// Input Data: source_id, source_secret, tool, record_id, phone, first_name, last_name, email.
const crypto = require('crypto');

// Without the record id every later lead would look like a duplicate, so stop instead.
if (!inputData.record_id) throw new Error("Map record_id to the trigger's record id");

const lead = {
  event_id: `${inputData.tool}-${inputData.record_id}`,
  phone: inputData.phone,
  first_name: inputData.first_name,
  last_name: inputData.last_name,
  email: inputData.email,
};
const body = JSON.stringify(lead);
const t = String(Math.floor(Date.now() / 1000));
const v1 = crypto
  .createHmac('sha256', inputData.source_secret)
  .update(`${t}.${body}`)
  .digest('hex');

const res = await fetch(`https://api.bubbl3.com/v1/inbound/leads/${inputData.source_id}`, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'bubbl3-signature': `t=${t},v1=${v1}`,
    'Idempotency-Key': lead.event_id,
  },
  body,
});
if (!res.ok) throw new Error(`bubbl3 refused the lead (${res.status}): ${await res.text()}`);
output = { received: true, event_id: lead.event_id };

Data shared​

From Airtable to bubbl3: the record's id and the fields you send: phone, name and email.

From bubbl3 to Airtable: nothing.

Sending rules that still apply​

Airtable 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 Airtable can turn them off.

  • Consent. When you connect Airtable 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 Airtable is told when bubbl3 doesn't send​

Airtable 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.

ReasonCodeWhat you see
A link before the contact repliespre_reply_link_blockedNot sent: "Links can't be sent until the contact replies"
A photo or file before the contact repliespre_reply_media_blockedNot sent: "Photos and files can't be sent until the contact replies"
A phone number before the contact repliespre_reply_phone_blockedNot sent: "Phone numbers can't be sent until the contact replies"
An email address before the contact repliespre_reply_email_blockedNot sent: "Email addresses can't be sent until the contact replies"
A first message that is too longpre_reply_too_longNot sent: "First messages must be 300 characters or fewer"
Too many texts without a replypre_reply_message_limitNot sent: "Already sent 3 texts without a reply. Wait for the contact to reply"
The same text to too many people todayidentical_text_limitNot sent: "This exact text went to 20 people from this line today"
The line is paused after unanswered textsunanswered_streak_limitNot sent: "This line is paused after too many unanswered texts"
The contact opted outcontact_opted_outNot sent: "The contact opted out of texts"
The workspace texts only opted-in contactsconsent_requiredNot sent: "This workspace only texts contacts who opted in"
No line can reach the contactline_unavailableNot sent: "bubbl3's line for this contact isn't available"
Quiet hoursquiet_hoursHeld: "Scheduled for 9:00 AM America/Chicago, quiet hours"
The line's daily limitdaily_new_contact_capHeld: "Scheduled for Oct 15, 9:00 AM America/Chicago: today's limit for this line is reached"
The line's hourly limit of new contactshourly_new_contact_capHeld: "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​

  • One lead per Airtable record id: running the automation again for the same record is the same lead.
  • Airtable's Run a script action is available on Airtable plans that include scripting in automations.
  • A record without a phone number is refused with "A lead needs a phone number".

Troubleshooting​

  • The script fails. Check the address and that the scenario or workflow is on.
  • 403 from bubbl3. Check the source id and secret, and that the source isn't paused.