# Dialer Setup Guide (explained simply)

Take your time. Do one step, check that it worked, then do the next one.
Menu names in Telnyx and cPanel move around sometimes. If you cannot find something, use the search box at the top of the page.

---

## What is what? (Words in plain English)

- **Telnyx** = the phone company. It makes the real phone calls.
- **Zoiper** = the phone on your computer. You talk and listen with it.
- **The dialer** = the brain. It picks who to call and connects the merchant to you.
- **cPanel** = the control panel of your server. It is where the dialer lives.
- **Node.js** = the engine that runs the dialer.
- **MySQL** = the filing cabinet where leads, calls and users are saved.
- **Webhook** = Telnyx knocking on the dialer's door to say "the merchant picked up!"
- **Subdomain** = a web address for the dialer, like `test-dialer.yourcompany.com`.
- **.env file** = a small secret notes file with passwords. Never share it.

---

## Before you start, get these ready

- [ ] Your Telnyx login
- [ ] Your cPanel login
- [ ] Zoiper working today with your Telnyx login
- [ ] One Telnyx phone number to use as caller ID
- [ ] Your own cell phone (for the test call)
- [ ] A text file or notebook to write down codes and passwords as you go

---

## PART A: Telnyx (about 15 minutes)

### Step A1. Find your Credentials connection
This is the connection your Zoiper already uses.
1. Log in to Telnyx.
2. Look for **Voice** then **SIP Connections** (or search "SIP Connections").
3. Open the connection that your Zoiper uses.
4. Write down the **SIP username** your Zoiper uses (the same one you type in Zoiper).
   Do NOT write the password anywhere here. It stays only in Zoiper.
5. Check that the connection has an **Outbound Voice Profile** chosen. If it is empty, choose your profile.

### Step A2. Make the Call Control Application
This is the door Telnyx knocks on.
1. Go to **Voice** then **Programmable Voice** (or search "Call Control" or "Voice API Application").
2. Click **Add new application**. Name it `Dialer`.
3. Webhook URL: type `https://YOUR-SUBDOMAIN/webhooks/telnyx`
   Example: `https://test-dialer.yourcompany.com/webhooks/telnyx`
   (You will create that subdomain in Part B. You can come back and fix this later.)
4. Make sure the API version is **v2**.
5. Choose your **Outbound Voice Profile** again here.
6. Save. Then open the application and **copy its ID**. Write it down as `CALL CONTROL APP ID`.

### Step A3. Get the keys
1. Go to **Keys & Credentials**.
2. Create an **API Key** if you do not have one. Copy it right away. Write it down as `API KEY`. It starts with `KEY`.
3. On the same page find **Public Key**. Copy it. Write it down as `PUBLIC KEY`.

### Step A4. Pick the caller ID
1. Go to **Numbers**. Choose one number you own.
2. Write it down. This is the number merchants will see.

You now have 4 things written down: SIP username, Call Control App ID, API Key, Public Key.

---

## PART B: cPanel (about 20 minutes)

### Step B1. Make the subdomain
1. Log in to cPanel.
2. Click **Domains** (or **Subdomains**).
3. Create a new one. Example name: `test-dialer`.
4. Now turn on **SSL** so it starts with `https`. Look for **SSL/TLS Status**, tick your new subdomain, and click **Run AutoSSL**. Wait a few minutes.
   Why? Without the lock (https) the microphone and Telnyx will not work.

### Step B2. Make the database (the filing cabinet)
1. In cPanel click **MySQL Databases**.
2. Under **Create New Database** type `dialer`. Click create. cPanel adds a prefix, so the real name looks like `cpuser_dialer`. Write the **full name** down.
3. Scroll to **MySQL Users**. Create a user `dialer` with a strong password. Write down the **full user name** and the **password**.
4. Scroll to **Add User To Database**. Choose that user and that database. Click Add.
5. On the next screen tick **ALL PRIVILEGES**. Click **Make Changes**.

### Step B3. Fill the filing cabinet
1. Go back to the cPanel home and click **phpMyAdmin**.
2. On the left, click your database name.
3. Click the **Import** tab at the top.
4. Click **Choose File** and pick `schema.sql`. (Unzip the dialer zip on your computer first and find it inside the folder.)
5. Scroll down and click **Import**.
6. You should see a green message and a list of tables on the left (users, leads, calls...). 

### Step B4. Upload the dialer files
1. Back in cPanel click **File Manager**.
2. Go to your home folder. Make a new folder called `dialer`.
3. Open it. Click **Upload** and upload `web-dialer.zip`.
4. Click the zip file, then click **Extract**.
5. Inside you will find another folder called `dialer`. Open it. You should see `server.js`, `package.json`, `schema.sql`, and a folder called `public`.
   Easy way to avoid a double folder: after extracting, you can select everything inside the inner `dialer` folder and **Move** it up one level, into the outer `dialer` folder.
   Remember where `server.js` is. That folder is your **app folder**.

---

## PART C: The secret notes file (.env)

### Step C1. Show hidden files
In File Manager click **Settings** (top right) and tick **Show Hidden Files (dotfiles)**. Click Save.

### Step C2. Make the .env file
1. In your app folder, find `.env.example`.
2. Right-click it and click **Copy**. Copy it to the same folder as `.env`.
   (Or rename a copy to `.env`.)
3. Right-click `.env` and click **Edit**.

### Step C3. Fill it in, line by line

| Line | What to type |
|---|---|
| `PORT=3000` | Leave it. |
| `PUBLIC_URL=` | Your subdomain with https, like `https://test-dialer.yourcompany.com` |
| `DB_HOST=localhost` | Leave it. |
| `DB_USER=` | The full database user name from B2 |
| `DB_PASS=` | The database password from B2 |
| `DB_NAME=` | The full database name from B2 |
| `JWT_SECRET=` | Mash the keyboard to type 40 or more random letters and numbers |
| `ADMIN_USER=` | The login name you want, like `admin` |
| `ADMIN_PASS=` | A strong password for you (8+ characters) |
| `TELNYX_API_KEY=` | The API Key from A3 |
| `TELNYX_CALL_CONTROL_APP_ID=` | The Call Control App ID from A2 |
| `TELNYX_PUBLIC_KEY=` | The Public Key from A3 |

No spaces around the `=` sign. No quote marks. Click **Save Changes**.

---

## PART D: Turn the dialer on

1. In cPanel click **Setup Node.js App**.
2. Click **Create Application**.
3. Fill in:
   - **Node.js version:** choose 18 or newer (the highest you have is fine)
   - **Application mode:** Production
   - **Application root:** `dialer` (the folder that has `server.js`)
   - **Application URL:** choose your subdomain
   - **Application startup file:** `server.js`
4. Click **Create**.
5. Click **Run NPM Install**. Wait until it finishes. This downloads the parts the dialer needs.
6. Click **Restart** (or **Start**).
7. Open your subdomain in a new browser tab. You should see the **Sign in** page.

If you see an error page, go to the "If something goes wrong" part at the bottom.

---

## PART E: First setup inside the dialer

1. Sign in with `ADMIN_USER` and `ADMIN_PASS`. You land on the admin page.

### Make the campaign
2. Click **Campaigns**. Type a name like `Test` and your caller ID number from A4. Click **Create**.
3. Leave it **stopped** for now.

### Tell the dialer about your Zoiper
4. Click **Users**. Find your own user in the list.
5. In the **SIP username** box, type the Zoiper SIP username from A1. Click **Save**.

### Add a few test leads (optional for now)
6. Open `sample_leads.csv` in Excel or Notepad. Replace the phone numbers with your own phone numbers (use your cell, a friend's, or a second phone). Save it.
7. Click **Lists & upload**. Make a list called `Test list`, pick your campaign, click **Create list**.
8. Click the file box on that list and choose your CSV. You should see "Upload finished".

---

## PART F: Your first test call (to your own cell)

1. Open **Zoiper**. Check it says it is **registered / connected**. (Green light.)
2. In the dialer, click **Open dialer screen** (top of the admin page).
3. Choose your campaign and click **Log in**.
4. **Zoiper will ring.** Press **Accept**. 
5. The dialer shows a green **Phone connected**. This means you are in your private room.
6. Look at **Manual dial** on the right. Type your own cell phone number. Click **Dial**.
7. Your cell rings. Answer it. Say hello. You should hear each other in Zoiper.
8. Hang up using the red **Hang up** button.
9. A box appears: "CALL ENDED, CHOOSE A RESULT". Click one (or press its number key).
10. Go to the admin page, click **Reports**, choose **Call log**, and click **Run**. Your call should be there. After a minute, the recording should be playable.

If steps 4 to 7 work, the hard part is done!

---

## PART G: Test the auto-dialer

1. Make sure your test leads are only your own phones.
2. Admin page, **Campaigns**, click **Start** on your campaign.
3. Dialer screen, click **Resume (go ready)**.
4. The dialer calls your test leads. When one answers, it connects to you at once.
5. Pick a result. Try different results (No answer, Call back, Do not call) and look at **Leads** to see what happened to the lead.
6. Click **Pause** when you are done. Click **Stop** on the campaign.

---

## If something goes wrong

| What you see | What to try |
|---|---|
| Subdomain shows a blank page or error | In **Setup Node.js App**, click **Restart**. Then look at the file `stderr.log` in your app folder. Send me what it says. |
| "Startup problem (did you import schema.sql?)" in the log | Redo Part B3. Check that DB_NAME, DB_USER and DB_PASS in `.env` are the full names with the prefix. |
| Cannot sign in | Check `ADMIN_USER` and `ADMIN_PASS` in `.env`. The admin is only created the first time, when the users table is empty. |
| Zoiper does not ring when you log in | Is Zoiper green/registered? Is your SIP username typed exactly in the Users tab? Is the caller ID set on the campaign? Is `TELNYX_CALL_CONTROL_APP_ID` correct? |
| Zoiper rings but badge never turns green | The webhook URL in Telnyx (A2) must be exactly `https://your-subdomain/webhooks/telnyx`. Check SSL works. |
| Dial does nothing, or an error pops up | Read the message. Common ones: number on DNC list, no caller ID, or phone not connected. |
| You hear nothing during the call | Check Zoiper's microphone and speaker settings. Check your headset. |
| No recording in Call log | Wait a few minutes. Check the campaign has "Record calls" ticked. Tell me if it is still missing. |
| Auto-dial does not dial anyone | Is the campaign **Started**? Did you press **Resume**? Is the list **Active**? Is it inside calling hours and allowed days? Click **Next in queue** on the campaign to see if any lead is eligible. |

When you ask me for help, always send: (1) what step you were on, (2) the exact words of any error, (3) the last lines of `stderr.log`.

---

## Before using real merchants

- [ ] Test calls, recording and rules all work
- [ ] DNC list uploaded
- [ ] Calling hours and allowed days are right
- [ ] A "this call may be recorded" notice is handled
- [ ] Daily cPanel backup is turned on
- [ ] A lawyer has looked at your calling rules (calling laws differ by state)
- [ ] Start with 1 or 2 agents on a small list first