# 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](https://usebluebot.com/docs/api)**: Your own code calls BlueBot’s REST API and listens to its signed webhooks.
- **[Text Hook](https://usebluebot.com/docs/text-hooks)**: 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](https://usebluebot.com/docs/api)                    |

### Steps

1. Add your API key to the project’s environment variables.
2. In a server action or route handler, send the text with the bluebot SDK.
3. 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.                                                     |

```bash
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"
    }
  }'
```

```ts
import BlueBot from '@usebluebot/sdk';

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

const message = await client.messages.send({
  to: '+15555550123',
  text: 'Hi Maria, thanks for signing up! Reply here any time with questions.',
  metadata: {
    source: 'vercel',
    record_id: '1042',
  },
}, { idempotencyKey: 'vercel-1042' });
console.log(message);
```

```python
import os
from bluebot import BlueBot

client = BlueBot(api_key=os.environ["BLUEBOT_API_KEY"])

message = client.messages.send(
    to="+15555550123",
    text="Hi Maria, thanks for signing up! Reply here any time with questions.",
    metadata={
        "source": "vercel",
        "record_id": "1042",
    },
    idempotency_key="vercel-1042",
)
print(message)
```

### 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](https://usebluebot.com/docs/api)                                                      |

### Steps

1. Add a route handler and register its URL in BlueBot as a webhook for message.received.
2. Verify the webhook-signature header with your whsec\_ secret before you trust the body.
3. 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](https://usebluebot.com/docs/text-hooks)                       |

### Steps

1. Make a Text Hook in BlueBot with your own number as the recipient.
2. Add a webhook in Vercel that posts deployment errors to the hook’s address.
3. 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.

```bash title="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](https://usebluebot.com/docs/concepts/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](https://usebluebot.com/docs/concepts/holds)
- [Vercel with BlueBot](https://usebluebot.com/integrations/vercel) on the integrations page says what else the two do together.