Docs›Integrations›Twilio

Twilio SMS

Field supports two-way SMS messaging with clients via Twilio. Send from Field, receive replies in /messages.

Architecture

Outbound: Field /messages → POST /api/sms/send → Twilio API → client's phone
Inbound:  client's phone → Twilio webhook → POST /api/sms/inbound → Supabase → Field /messages

All messages are stored in the messages table in Supabase, grouped by conversation_id.

Setup (One-Time)

Only needed once. If Twilio is already configured (check Settings → Twilio SMS), skip this.

Step 1 — Create a Twilio account

Go to twilio.com and sign up.

Step 2 — Buy a phone number

  • Navigate to Phone Numbers → Manage → Buy a number
  • Choose a 415 area code (local SF)
  • Cost: ~$1.15/month

Step 3 — Add Vercel env vars

In Vercel dashboard → cdb-field project → Settings → Environment Variables:

| Variable | Value | |----------|-------| | TWILIO_ACCOUNT_SID | From Twilio Console dashboard | | TWILIO_AUTH_TOKEN | From Twilio Console dashboard | | TWILIO_FROM_NUMBER | Your Twilio number in E.164 format: +14155551234 |

Redeploy Field after adding env vars.

Step 4 — Configure inbound webhook

In Twilio Console:

  • Phone Numbers → Manage → Active numbers → click your number
  • Under Messaging → A message comes in:
    • Webhook URL: https://buildbase.vercel.app/api/sms/inbound
    • HTTP Method: POST
  • Save

Step 5 — Test

Send a test SMS from Field /messages. Reply from a phone — it should appear in the thread within seconds.

Usage

Sending a message

  • Go to /messages
  • Click New Conversation → select a contact → type a message
  • Or use the Send SMS button on any contact or job page

Templates

  • In the compose area, click the ⚡ Templates button to pick a saved template
  • Manage templates at /sms-templates

Receiving messages

Client replies are delivered via Twilio webhook to /api/sms/inbound. They appear in the conversation thread automatically. No polling needed.

Number Porting

If David wants to port his existing business number to Twilio:

  1. Request port from current carrier — get an LOA (Letter of Authorization)
  2. Submit porting request in Twilio Console → Phone Numbers → Port a number
  3. Process takes 2–4 weeks
  4. Update TWILIO_FROM_NUMBER env var after porting is complete

There's a task in Field → Tasks tracking the number porting work.

Troubleshooting

Messages aren't delivering:

  • Check TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN are set in Vercel
  • Check Vercel logs for /api/sms/send
  • Check Twilio Console → Monitor → Logs for errors

Inbound messages not appearing:

  • Verify the webhook URL is correct in Twilio Console
  • The URL must be https://buildbase.vercel.app/api/sms/inbound (not staging, not localhost)
  • Check Vercel logs for /api/sms/inbound

"Unverified" number error during testing: During Twilio trial, you can only SMS to verified numbers. Upgrade to a paid account to remove this restriction.