Recipes

Vercel recipes

Text from a Next.js app with the TypeScript SDK, and text yourself when a deploy fails.

Three recipes for Vercel. Each names its trigger and the BlueBot step, lists the fields to map and says how to test it with your own number before anyone else gets a text.

How Vercel connects

API: Your own code calls BlueBot’s REST API and listens to its signed webhooks.
Text Hook: A Text Hook is a BlueBot address the app posts its own webhook to. You map its fields to a recipient and a template, and each post becomes a text.

Text a confirmation from a Next.js form

Part	What it is
Trigger	Someone submits a form on your site
Action	`POST /v1/messages`
Connects through	API

Steps

Add your API key to the project’s environment variables.
In a server action or route handler, send the text with the bluebot SDK.
Keep the key on the server and never import it into a client component.

Map the fields

BlueBot field	Map it to
`to`	The person’s mobile number from Vercel. US numbers can leave off the +1.
`text`	Hi {{first_name}}, thanks for signing up! Reply here any time with questions.
`{{first_name}}` in the text	Vercel’s first name field.
`metadata`	`source` set to `vercel`, and `record_id` set to the record’s id, so the status and reply webhooks for this text can find the record again.
`service`	Auto, the default: iMessage when the person uses it, otherwise SMS through your iPhone.

POST/v1/messagesSend a text →

curl -X POST "https://usebluebot.com/api/v1/messages" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vercel-1042" \
  -d '{
    "to": "+15555550123",
    "text": "Hi Maria, thanks for signing up! Reply here any time with questions.",
    "metadata": {
      "source": "vercel",
      "record_id": "1042"
    }
  }'

Test it

Run the request with your own number in to. A text arrives on your phone from your own number.

Receive replies in a route handler

Part	What it is
Trigger	A text comes in (BlueBot’s message.received webhook)
Action	A webhook for `message.received` starts it, and Vercel takes the text
Connects through	API

Steps

Add a route handler and register its URL in BlueBot as a webhook for message.received.
Verify the webhook-signature header with your whsec_ secret before you trust the body.
Run npx bluebot listen to forward webhooks to localhost while you build.

Map the fields

From BlueBot	Into Vercel
`data.from`	The phone number to find the person by in Vercel. It’s in E.164 (`+15555550123`); search by the last 10 digits if Vercel stores numbers another way.
`data.text`	The words, for a note, a row or a message. Null when the person sent only a picture.
`data.received_at`	When it came in, in UTC.
`data.files`	Pictures and voice memos. Each `url` works for an hour, so copy a file you want to keep.
`data.chat_id`	Set when the text came in a group chat; null for a one-to-one text.

Test it

Run bluebot listen --forward-to http://localhost:3000/webhooks, then text your BlueBot number from another phone. The CLI forwards the event to your handler, signed. BlueBot copies texts from people you’ve texted through it, unless you set Which chats to copy to Everything.

Text me when a deployment fails

Part	What it is
Trigger	Vercel’s webhook for a deployment error
Action	A BlueBot Text Hook turns each post into a text
Connects through	Text Hook

Steps

Make a Text Hook in BlueBot with your own number as the recipient.
Add a webhook in Vercel that posts deployment errors to the hook’s address.
Once a payload comes in, map the project name and deployment URL from the payload BlueBot kept.

Map the fields

Text Hook setting	Set it to
Recipient	The field in Vercel’s post that holds the person’s phone number, written as a path such as `{{body.phone}}`.
Text	{{body.project}} failed to deploy: {{body.url}}
Metadata	`source` set to `vercel`. BlueBot adds the hook’s id by itself.

Test it

Post a sample to the hook’s address with your own number in the phone field, as below. A text arrives on your phone, and the hook’s page lists the post.

A test post shaped like Vercel’s

curl -X POST "https://usebluebot.com/h/YOUR_HOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+15555550123","project":"sample project","url":"sample url"}'

Before you turn it on

Text only people who asked to hear from you. Anyone who replies STOP goes on your stop list, and BlueBot cancels texts to them. Stop words
A text that can’t go yet waits with a hold rather than failing: quiet hours, your Mac away, a daily limit. Holds
Vercel with BlueBot on the integrations page says what else the two do together.