# 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 DogBot 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://getdogbot.com/docs/api)**: Your own code calls DogBot’s REST API and listens to its signed webhooks.
- **[Text Hook](https://getdogbot.com/docs/text-hooks)**: A Text Hook is a DogBot 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://getdogbot.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 dogbot SDK.
3. Keep the key on the server and never import it into a client component.

### Map the fields

| DogBot 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://getdogbot.com/api/v1/messages" \
  -H "Authorization: Bearer $DOGBOT_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 DogBot from '@getdogbot/sdk';

const client = new DogBot({ apiKey: process.env.DOGBOT_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 dogbot import DogBot

client = DogBot(api_key=os.environ["DOGBOT_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 (DogBot’s message.received webhook)                   |
| Action           | A webhook for `message.received` starts it, and Vercel takes the text |
| Connects through | [API](https://getdogbot.com/docs/api)                                                      |

### Steps

1. Add a route handler and register its URL in DogBot as a webhook for message.received.
2. Verify the webhook-signature header with your whsec\_ secret before you trust the body.
3. Run npx dogbot listen to forward webhooks to localhost while you build.

### Map the fields

| From DogBot        | 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 `dogbot listen --forward-to http://localhost:3000/webhooks`, then text your DogBot number from another phone. The CLI forwards the event to your handler, signed. DogBot 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 DogBot **Text Hook** turns each post into a text |
| Connects through | [Text Hook](https://getdogbot.com/docs/text-hooks)                      |

### Steps

1. Make a Text Hook in DogBot 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 DogBot 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`. DogBot 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://getdogbot.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 DogBot cancels texts to them. [Stop words](https://getdogbot.com/docs/concepts/stop-words)
- A text that can’t go yet waits with a hold rather than failing: texting hours, your Mac away, a daily limit. [Holds](https://getdogbot.com/docs/concepts/holds)
- [Vercel with DogBot](https://getdogbot.com/integrations/vercel) on the integrations page says what else the two do together.
