# Twilio Voice & SMS — Setup Guide
## (No Composer / No dependencies needed)

The Twilio PHP SDK is already bundled in `lib/`. Just upload and configure.

---

## File structure after upload

```
your-web-root/
├── autoload.php          ← loads the SDK, no Composer needed
├── config.php            ← YOUR CREDENTIALS GO HERE
├── lib/
│   └── Twilio/           ← bundled SDK (don't touch)
├── data/
│   ├── .htaccess         ← blocks public access to messages
│   └── messages.json     ← SMS storage (auto-managed)
├── api/
│   ├── token.php         ← issues Voice SDK tokens
│   ├── voice.php         ← TwiML for outgoing calls
│   └── sms.php           ← SMS send/receive/poll
└── public/
    └── index.html        ← the app UI
```

---

## Step 1 — Get your Twilio credentials

Log in at [console.twilio.com](https://console.twilio.com).

| What | Where in console | Looks like |
|---|---|---|
| Account SID | Dashboard → Account Info | `ACxxxx...` |
| Auth Token | Dashboard → Account Info (click eye) | 32-char string |
| Phone Number | Phone Numbers → Manage → Buy a number | `+1xxxxxxxxxx` |
| API Key SID | Account → API Keys → Create Standard Key | `SKxxxx...` |
| API Key Secret | Shown once when you create the key | 32-char string |
| TwiML App SID | Voice → TwiML Apps → Create new | `APxxxx...` |

---

## Step 2 — Edit config.php

Open `config.php` and fill in all six values:

```php
define('TWILIO_ACCOUNT_SID',   'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
define('TWILIO_AUTH_TOKEN',    'your_auth_token_here');
define('TWILIO_PHONE_NUMBER',  '+1xxxxxxxxxx');
define('TWILIO_API_KEY',       'SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
define('TWILIO_API_SECRET',    'your_api_key_secret_here');
define('TWILIO_TWIML_APP_SID', 'APxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
```

---

## Step 3 — Upload everything

Upload the entire folder to your server via FTP/SFTP/cPanel.

Make sure the `data/` folder is **writable** by PHP:
- In cPanel File Manager: right-click `data/` → Permissions → set to **755**
- Or via SSH: `chmod 755 data/`

---

## Step 4 — Create the TwiML App (for Voice)

1. Console → **Voice → TwiML Apps → Create new TwiML App**
2. Name it anything (e.g. "My Dialer")
3. Set **Voice Request URL** to:
   ```
   https://yourdomain.com/api/voice.php
   ```
4. Save → copy the **TwiML App SID** (`AP...`) into `config.php`

---

## Step 5 — Set the SMS webhook

1. Console → **Phone Numbers → Manage → Active numbers → click your number**
2. Scroll to **Messaging Configuration**
3. Set **"A message comes in"** to:
   ```
   https://yourdomain.com/api/sms.php
   ```
4. Method: **HTTP POST** → Save

This is what makes incoming SMS work. Every time someone texts your Twilio number, Twilio calls this URL and your PHP saves the message. The app picks it up within 5 seconds via polling.

---

## Step 6 — Open the app

Go to `https://yourdomain.com/public/index.html`

In the config bar at the top, enter your backend URL:
```
https://yourdomain.com/api
```

Click **Connect**. The status dot should turn green and say "Ready".

---

## How incoming SMS works

```
Someone texts your Twilio number
    ↓
Twilio POSTs to api/sms.php  (your webhook)
    ↓
sms.php appends message to data/messages.json
    ↓
index.html polls sms.php?action=poll every 5 seconds
    ↓
Message appears in the thread — no page refresh needed
```

---

## Troubleshooting

| Problem | Fix |
|---|---|
| Blank page / PHP errors | Check PHP version is 7.1+ (cPanel → PHP Selector) |
| "Permission denied" on data/ | Set data/ folder permissions to 755 |
| SMS not arriving | Double-check webhook URL in Twilio console — must be exact HTTPS URL |
| Voice "token error" | Verify API Key SID, API Secret, and TwiML App SID in config.php |
| Free trial SMS blocked | Add test numbers to Verified Caller IDs in Twilio console |
| CORS error in browser | Make sure you're loading index.html from the same domain as your API URL |

---

## Security

- `config.php` contains sensitive credentials — don't share it or commit it to Git
- `data/.htaccess` prevents direct browser access to messages.json
- For extra security, move the `data/` folder above your web root and update `MSG_FILE` path in sms.php