> ## Documentation Index
> Fetch the complete documentation index at: https://help.emergent.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Twilio Integration

> Send SMS messages and phone calls with Twilio

## What is Twilio?

Twilio lets you send text messages (SMS), make phone calls, and even send WhatsApp messages from your app. It's the most popular service for adding phone/SMS features.

**Perfect for:**

* SMS notifications and alerts
* Two-factor authentication (2FA)
* Phone verification
* Order updates
* Appointment reminders

## What You'll Need

<Steps>
  <Step title="Twilio Account">
    Sign up at [twilio.com](https://twilio.com) - free trial available!
  </Step>

  <Step title="Phone Number">
    Get a Twilio phone number
  </Step>

  <Step title="API Keys">
    Copy your credentials
  </Step>

  <Step title="10 Minutes">
    Quick setup!
  </Step>
</Steps>

## Step 1: Get Your Twilio Credentials

### Create Account

1. Go to [twilio.com/try-twilio](https://www.twilio.com/try-twilio)
2. Sign up for free
3. Verify your email and phone
4. You get **\$15 free credit!**

### Get a Phone Number

1. In [Twilio Console](https://console.twilio.com)
2. Go to **Phone Numbers** → **Manage** → **Buy a number**
3. Select your country
4. Check: **SMS** (and Voice if needed)
5. Click **Buy** (uses your free credit)
6. Copy your new phone number

### Get Your API Credentials

On the Twilio dashboard, you'll see:

<CardGroup cols={2}>
  <Card title="Account SID" icon="id-card">
    **Starts with:** `AC`

    **Example:** `ACxxxxxxxx`

    Identifies your account
  </Card>

  <Card title="Auth Token" icon="key">
    **Random string**

    **Secret!** Keep it safe

    Click to reveal it
  </Card>
</CardGroup>

Copy both - you'll need them!

<Note>
  **Trial Account Limits:** You can only send to verified phone numbers. Upgrade to send to anyone.
</Note>

## Step 2: Tell the Agent What You Want

Describe what you need:

### Example 1: SMS Notifications

```
I need to send SMS notifications to users.

Twilio credentials:
- Account SID: ACxxxxxxxx
- Auth Token: xxxxxxxx
- Phone Number: +1234567890

Features:
- Send order confirmations via SMS
- Send shipping updates
- Send account alerts

Please set this up.
```

### Example 2: Phone Verification (2FA)

```
I need phone number verification for user signup.

Twilio credentials:
- Account SID: ACxxxxxxxx
- Auth Token: xxxxxxxx  
- Phone Number: +1234567890

Flow:
1. User enters their phone number
2. Send 6-digit code via SMS
3. User enters code
4. Verify and activate account

Features:
- Code expires in 5 minutes
- Limit resend attempts
- Show countdown timer

Please build this.
```

### Example 3: Appointment Reminders

```
Send SMS reminders for appointments.

Twilio credentials:
- Account SID: ACxxxxxxxx
- Auth Token: xxxxxxxx
- Phone Number: +1234567890

Reminders:
- 24 hours before appointment
- 2 hours before appointment
- Include appointment details

Please set this up.
```

<Tip>
  **That's all!** The agent will set up SMS sending, verification codes, everything.
</Tip>

## Step 3: Test SMS Sending

### For Trial Accounts

<Steps>
  <Step title="Verify Your Phone">
    In Twilio Console → **Phone Numbers** → **Verified Caller IDs**

    Add your personal phone number
  </Step>

  <Step title="Click Preview">
    In Emergent, click **Preview**
  </Step>

  <Step title="Send Test SMS">
    Try sending an SMS to your verified number
  </Step>

  <Step title="Check Phone">
    You should receive the text message!
  </Step>
</Steps>

### After Upgrade

Once you upgrade (add payment method), you can send to any phone number!

## Step 4: Go Live (Upgrade Account)

To send to anyone (not just verified numbers):

<Steps>
  <Step title="Upgrade Account">
    In Twilio Console → **Upgrade**
  </Step>

  <Step title="Add Payment">
    Add credit card
  </Step>

  <Step title="Complete Upgrade">
    Follow the steps
  </Step>

  <Step title="Start Sending!">
    Now you can send to any number
  </Step>
</Steps>

## Common Questions

<AccordionGroup>
  <Accordion title="How much does Twilio cost?">
    **Very affordable!**

    **SMS (US):** \~\$0.0079 per message

    * 100 messages = \$0.79
    * 1,000 messages = \$7.90

    **SMS (India):** \~\$0.0070 per message

    **Phone numbers:** \~\$1-2/month to keep the number

    Most apps spend under \$20/month.
  </Accordion>

  <Accordion title="Can I send WhatsApp messages?">
    Yes! Tell the agent:

    ```
    I want to send WhatsApp messages instead of SMS.

    Twilio credentials: [same as above]

    Please set up WhatsApp messaging.
    ```

    (Requires Twilio WhatsApp sandbox or approved business account)
  </Accordion>

  <Accordion title="Users say they don't receive SMS. What's wrong?">
    Tell the agent:

    ```
    Some users aren't receiving SMS. Can you:
    1. Add better error handling
    2. Log delivery status
    3. Show if message was delivered
    4. Handle international numbers properly
    ```
  </Accordion>

  <Accordion title="Can I customize the sender name?">
    In some countries, yes. Tell the agent:

    ```
    Instead of showing a phone number,
    show "MyCompany" as the sender name.
    ```

    (Availability depends on country)
  </Accordion>
</AccordionGroup>

## Something Not Working?

### SMS Not Sending

**Tell the agent:**

```
SMS messages aren't sending. Error:
[paste error message]

Can you check the Twilio setup?
```

### "Unverified Number" Error

**Tell the agent:**

```
Getting "unverified number" errors.

I'm on trial account - can you:
1. Add instructions for users to verify their number
2. Or remind me I need to upgrade
```

### Wrong Phone Format

**Tell the agent:**

```
Users entering phone numbers wrong.

Can you:
1. Auto-format phone numbers
2. Add country code selector
3. Validate format before sending
```

## Real Examples

### Example 1: E-commerce Order Updates

```
Send SMS for order status updates.

Twilio credentials: [will provide]

Messages to send:
- Order placed confirmation
- Payment received
- Shipped (with tracking)
- Out for delivery
- Delivered

Each SMS should include:
- Customer name
- Order number
- Relevant details

Please build this.
```

### Example 2: Two-Factor Authentication

```
Add 2FA to user login.

Twilio credentials: [will provide]

Flow:
1. User logs in with password
2. Send 6-digit code via SMS
3. User enters code
4. Grant access if correct

Security:
- Code expires in 5 minutes
- Max 3 attempts
- Rate limiting

Please set this up.
```

### Example 3: Booking Reminders

```
SMS reminders for bookings.

Twilio credentials: [will provide]

Send reminders:
- When booking is confirmed
- 1 day before
- 1 hour before

Include:
- Booking details
- Date/time
- Location/link
- Cancel/reschedule option

Please build this.
```

## Advanced Features

Once basic SMS works:

### Delivery Tracking

```
Track SMS delivery status:
- Sent
- Delivered
- Failed
- Read (if available)

Show status in admin dashboard.
```

### Two-Way SMS

```
Users can reply to SMS messages.
Handle their responses in the app.
```

### Scheduled Messages

```
Schedule SMS to send later:
- Daily reminders at 9 AM
- Birthday messages
- Appointment reminders
```

## Quick Checklist

Before going live:

* Tested SMS on verified number
* Messages arrive within seconds
* Text format looks good
* Links work (if included)
* Phone validation works
* Upgraded account (if sending to all numbers)
* Set spending limits in Twilio

## Remember

**Free trial includes \$15 credit** - Good for \~2,000 SMS

**Very affordable** - Most apps spend under \$20/month

**Upgrade to reach everyone** - Trial only sends to verified numbers

**Track delivery** - Know if messages were received

**Set spending limits** - Avoid surprise bills

<Info>
  Stuck? Tell the agent: "I need help with Twilio SMS" and explain what's not working.
</Info>