Text everyone who fills in your Typeform or Jotform

Ask for a mobile number

In Typeform, add a Phone Number question, make it required and set its default country to the United States. In Jotform, add a Phone field and make it required.

Put the permission line in the question’s description, so it sits beside the number: “By sharing your number you agree that Brightside Remodeling may text you about your quote.”

Give the question for the person’s first name a clear title, such as “First name”. You’ll pick it by its title in a minute.

Make the Text Hook

In the BlueBot dashboard, open Text Hooks and press New hook. Name it after the form (“Quote form”) and pick the Typeform or Jotform preset. The preset knows how that app shapes its posts, so it can find the phone number and name answers for you.

Copy the hook’s address. It’s https://usebluebot.com/h/ followed by a long token. Treat it like a password: anyone who has it can make your hook text somebody.

Point the form at the hook

In Typeform, open the form, go to Connect, then Webhooks, press Add a webhook, paste the hook’s address and save. Turn the webhook on with its switch.

In Jotform, open the form, go to Settings, then Integrations, search for WebHooks, paste the hook’s address and press Complete Integration.

Fill in the form yourself

Open the form’s public link and fill it in with your own mobile number and your own first name. This post is how the hook learns the shape of your form.

Back on the hook’s page in BlueBot, the test panel lists the last 20 posts by their field names. BlueBot never shows or keeps the values in that panel, only the names, so you pick fields without anyone’s answers on screen.

Map the recipient and write the text

Set Recipient to the phone number answer. The preset picks it when the form has one phone question; check that it did.

Write the text. Press a field in the test panel to put its path into the template where your cursor is. A template reads the post under body, so a first-name field looks like {{body.first_name}} in the template, although Typeform’s and Jotform’s answers sit deeper in the post than that example. Let the picker write the path for you.

Hi {{body.first_name}}, this is Dana at Brightside Remodeling. Thanks for asking for a quote. What’s a good time for a quick call this week?

Keep it short and personal. A text that reads like a person wrote it gets answered; one that reads like an ad gets reported, and reports are what get an Apple account flagged.

Add the person to your contacts

Turn on Create a contact and add the tag quote-form. Each person who fills in the form becomes a contact with that tag, so you can see who came from the form and add them to a sequence later. Save the hook.

Make an API key and a Typeform secret

In BlueBot, open Developers, then API keys, and make a key with the messages:send scope. In Typeform, add a webhook pointing at your handler’s address (for example https://brightside.example/hooks/typeform), then edit the webhook and set a Secret. Typeform signs every post with it.

Put both in your server’s environment:

export BLUEBOT_API_KEY="bb_live_…"
export TYPEFORM_SECRET="the secret you typed in Typeform"

Write the handler

Typeform sends a Typeform-Signature header: sha256= and the base64 HMAC-SHA256 of the raw body, keyed with your secret. Check it before you read the body, then find the answers by their type and the question’s ref.

The handler sends with an Idempotency-Key built from Typeform’s token for the entry. Typeform tries a post again when your handler is slow or fails, and the same key means the same entry never texts the person twice.

// app/hooks/typeform/route.ts (Next.js). Any framework works: read the raw body first.
import { createHmac, timingSafeEqual } from 'node:crypto';
import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY });

type Answer = { type: string; field: { ref: string }; text?: string; phone_number?: string };

function signedByTypeform(payload: string, header: string | null): boolean {
  if (!header) return false;
  const expected = 'sha256=' + createHmac('sha256', process.env.TYPEFORM_SECRET!).update(payload).digest('base64');
  return header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

export async function POST(request: Request) {
  const payload = await request.text();
  if (!signedByTypeform(payload, request.headers.get('typeform-signature'))) {
    return new Response('Bad signature', { status: 401 });
  }

  const { form_response: entry } = JSON.parse(payload);
  const answers: Answer[] = entry.answers ?? [];
  const phone = answers.find((a) => a.type === 'phone_number')?.phone_number;
  const firstName = answers.find((a) => a.field.ref === 'first_name')?.text?.trim();
  if (!phone) return new Response(null, { status: 204 }); // nobody to text

  await client.messages.send(
    {
      to: phone,
      text: `Hi ${firstName ?? 'there'}, this is Dana at Brightside Remodeling. Thanks for asking for a quote. What’s a good time for a quick call this week?`,
      metadata: { source: 'typeform', form_id: entry.form_id, response_token: entry.token },
    },
    { idempotencyKey: `typeform-${entry.token}` },
  );
  return new Response(null, { status: 204 });
}

The ref of a question is its name in Typeform’s data. Typeform makes one up for each question; to find yours, look at one entry’s payload in your handler’s log (without the answers), or match on the question’s type as the phone lookup does.

Underneath, the SDK call is this request:

curl -X POST "https://usebluebot.com/api/v1/messages" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: typeform-a3f9c2e1b7d84d0f" \
  -d '{
    "to": "+15555550123",
    "text": "Hi Maria, this is Dana at Brightside Remodeling. Thanks for asking for a quote. What’s a good time for a quick call this week?",
    "metadata": {
      "source": "typeform",
      "form_id": "lT4Z3j",
      "response_token": "a3f9c2e1b7d84d0f"
    }
  }'