{"id":16944393,"url":"https://github.com/jmkim/twilio-pbx","last_synced_at":"2025-04-11T19:33:11.779Z","repository":{"id":204871399,"uuid":"705482251","full_name":"jmkim/twilio-pbx","owner":"jmkim","description":"A Virtual PBX Server for Twilio (Supports standalone Node.js server and Firebase Cloud Functions)","archived":false,"fork":false,"pushed_at":"2024-01-11T00:54:37.000Z","size":433,"stargazers_count":4,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T03:35:57.460Z","etag":null,"topics":["node","pbx","twilio"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/twilio-pbx","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmkim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-16T05:13:10.000Z","updated_at":"2024-12-21T15:12:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"7d052346-5382-401e-9d59-b1153bcd9ac9","html_url":"https://github.com/jmkim/twilio-pbx","commit_stats":null,"previous_names":["jmkim/twilio-pbx"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmkim%2Ftwilio-pbx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmkim%2Ftwilio-pbx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmkim%2Ftwilio-pbx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmkim%2Ftwilio-pbx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmkim","download_url":"https://codeload.github.com/jmkim/twilio-pbx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248467230,"owners_count":21108611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["node","pbx","twilio"],"created_at":"2024-10-13T21:18:00.422Z","updated_at":"2025-04-11T19:33:11.768Z","avatar_url":"https://github.com/jmkim.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# twilio-pbx: A Virtual PBX Server for Twilio\n\nA Virtual PBX Server for [Twilio](https://www.twilio.com). Supports [standalone Node.js server](#option-1-nodejs-standalone-server) and [Firebase Cloud Functions](#option-2-firebase-cloud-functions).\n\n1. [How to use](#how-to-use)\n   1. [Call modes](#call-modes)\n   2. [Text modes](#text-modes)\n2. [How to install](#how-to-install)\n   1. [Node.js Standalone server](#option-1-nodejs-standalone-server)\n   2. [Firebase Cloud Functions](#option-2-firebase-cloud-functions)\n3. [APIs](#apis)\n4. [Environmental variables](#environmental-variables)\n\n## How to use\n\n### Call modes\n\n#### Call Command mode\n\n*(Make a call)*\n\n* To make a call:\n  1. Call to your Twilio number, from one of [`CALL_COMMAND_PHONE_NUMBER`](#call_command_phone_number).\n  2. In the call, you can dial the number.\n  3. In the call, a new call will be made with your Twilio number, to the dialed number.\n\n#### Call Forwarding mode\n\n*(Receive a call)*\n\n* Calls to your Twilio number will be forwarded to the desired number:\n  * If the call is from the US number, it will be forwarded to [`CALL_RECEIVE_US_PHONE_NUMBER`](#call_receive_us_phone_number).\n  * Otherwise, it will be forwarded to [`CALL_RECEIVE_INTL_PHONE_NUMBER`](#call_receive_intl_phone_number).\n  * Exceptions: the calls from the numbers in [`CALL_COMMAND_PHONE_NUMBER`](#call_command_phone_number) will be routed to the [Call Command mode](#call-command-mode).\n* [Call Alert](#call-alert) will be sent to your Twilio number, simultaneously.\n\n#### Call Alert\n\n*(Alert the call: incoming call and missed call)*\n\n* **With the call forwarding,** Call Alert will be sent to your Twilio number.\n  * If you have multiple Twilio numbers, this will help you identify the number which has the call.\n  * The message for incoming call looks like below:\n\n    ```plain\n    Incoming call: +12120007890 (US)\n    Name: KIM,JONGMIN\n    Carrier: T-Mobile USA, Inc. (mobile)\n    ```\n\n    * You can control the information included in the message:\n      * [`CALL_SHOW_CARRIER`](#call_show_carrier) controls the carrier lookup (0.005 USD per a call, billed by Twilio)\n\n        ```plain\n        Incoming call: +12120007890 (US)\n        Carrier: T-Mobile USA, Inc. (mobile)\n        ```\n\n      * [`CALL_SHOW_CALLER_ID`](#call_show_caller_id) controls the Caller ID lookup (0.01 USD per a call, billed by Twilio)\n\n        ```plain\n        Incoming call: +12120007890 (US)\n        Name: KIM,JONGMIN\n        ```\n\n      * If both flags disabled, the message would be like below:\n\n        ```plain\n        Incoming call: +12120007890 (US)\n        ```\n\n* **When you missed the call,** Call Alert will be sent to your email [`CALL_ALERT_TO_EMAIL_ADDRESS`](#call_alert_to_email_address).\n  * The email for missed call looks like below:\n\n    ```plain\n    Subject:    Missed call: +12120007890\n    From:       12120007890@example.com\n    To:         jmkim@jongmin.dev\n\n    Missed call: +12120007890\n    ```\n\n### Text modes\n\n#### Text Command mode\n\n*(Send a message)*\n\n* Text to your Twilio number, from one of [`TEXT_COMMAND_PHONE_NUMBER`](#text_command_phone_number).\n* The message format should follow below:\n\n  ```plain\n  TO_NUMBER:MESSAGE_BODY\n  ```\n\n  * `TO_NUMBER` must be [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164).\n\n* Examples:\n  * Single-line text example:\n\n    ```plain\n    +12120007890:Hi\n    ```\n\n    * will send below message to `+1 (212) 000-7890`:\n\n      ```plain\n      Hi\n      ```\n\n  * Multi-line text example:\n\n    ```plain\n    +821000337890:Hey, this is Jongmin.\n    Happy holiday o/\n    ```\n\n    * will send below message to `+82 10-0033-7890`:\n\n      ```plain\n      Hey, this is Jongmin.\n      Happy holiday o/\n      ```\n\n#### Text Forwarding mode\n\n*(Receive a message)*\n\n* Texts to your Twilio number will be forwarded to the desired number:\n  * If the text is from the US number, it will be forwarded to [`TEXT_RECEIVE_US_PHONE_NUMBER`](#text_receive_us_phone_number).\n  * Otherwise, it will be forwarded to [`TEXT_RECEIVE_INTL_PHONE_NUMBER`](#text_receive_intl_phone_number).\n  * Exceptions: the calls from the numbers in [`TEXT_COMMAND_PHONE_NUMBER`](#text_command_phone_number) will be routed to the [Text Command mode](#text-command-mode).\n* [Text Alert](#text-alert) will be sent to the email, simultaneously.\n\n#### Text Alert\n\n*(Alert the text: incoming text)*\n\n* **With the text forwarding,** Text Alert email will be sent to [`TEXT_ALERT_TO_EMAIL_ADDRESS`](#text_alert_to_email_address).\n  * The email for incoming text looks like below:\n\n    ```plain\n    Subject:    New message: +12120007890\n    From:       12120007890@example.com\n    To:         jmkim@jongmin.dev\n\n    Hey, this is Jongmin.\n    Happy holiday o/\n    ```\n\n## How to install\n\ntwilio-pbx supports two ways for deployment: one is **[Node.js Standalone server](#option-1-nodejs-standalone-server)** and another is **[Firebase Cloud Functions](#option-2-firebase-cloud-functions)**.\n\n### Option 1: Node.js Standalone server\n\n1. Install npm dependencies\n\n    ```bash\n    npm install\n    ```\n\n2. Copy the `.env` file from `.env.template`\n\n    ```bash\n    cp .env.template .env\n    ```\n\n3. Edit the `.env` file\n4. Run the server\n\n    ```bash\n    npm run start\n    ```\n\n### Option 2: Firebase Cloud Functions\n\n1. Make ready the Firebase Cloud Functions\n    * Create the project at [firebase.google.com](http://firebase.google.com).\n    * Make sure the billing is activated, which is required by the Firebase Cloud Functions.\n      * Note: Firebase Cloud Functions is only available with paid account. It does not offer the free trial.\n    * Install and login to Firebase\n\n        ```bash\n        npm install -g firebase-tools # Globally install the Firebase CLI Tools\n        firebase login                # Login\n        ```\n\n2. Copy the `.firebaserc` file from `.firebaserc.template`\n\n    ```bash\n    cp .firebaserc.template .firebaserc\n    ```\n\n3. Set the actual project name in `.firebaserc`\n    * Replace `FIREBASE_PROJECT_NAME_HERE` with the actual project name\n\n4. Copy the `.env` file from `.env.template`\n\n    ```bash\n    cp .env.template .env\n    ```\n\n5. Edit the `.env` file\n6. Emulate the server in local machine\n\n    ```bash\n    npm run serve\n    ```\n\n7. Deploy the server to the Firebase Cloud Functions\n\n    ```bash\n    npm run deploy\n    ```\n\n## APIs\n\n### `POST /calls`\n\n* Exchange the inbound call\n  * If the call is from one of [`CALL_COMMAND_PHONE_NUMBER`](#call_command_phone_number), route to [`/calls/command`](#post-callscommand).\n  * Otherwise, route to [`/calls/forward`](#post-callsforward).\n\n### `POST /calls/command`\n\n* **Call Command mode**\n* Let the user press the dial, to make the outbound call\n  * Uses [DTMF (tone dialing)](https://en.wikipedia.org/wiki/Dual-tone_multi-frequency_signaling).\n  * Dialing finishes on `#` key, or after the timeout with [`CALL_COMMAND_TIMEOUT`](#call_command_timeout).\n* After the dialing, route to [`/calls/dial`](#post-callsdial)\n\n### `POST /calls/dial`\n\n* Make the call to the number gathered by [`/calls/command`](#post-callscommand)\n* After the call end, route to [`/calls/dial/result`](#post-callsdialresult)\n\n### `POST /calls/dial/result`\n\n* Speak back the result of the call, and then hang up\n\n### `POST /calls/forward`\n\n* **Call Forward mode**\n* Forward the inbound call to desired receive phone number\n  * If the call is from the US number, forward to [`CALL_RECEIVE_US_PHONE_NUMBER`](#call_receive_us_phone_number).\n  * Otherwise, forward to [`CALL_RECEIVE_INTL_PHONE_NUMBER`](#call_receive_intl_phone_number).\n  * Send the carrier and/or Caller ID information to desired receive phone number.\n    * [`CALL_SHOW_CARRIER`](#call_show_carrier) controls the carrier lookup (0.005 USD per a call, billed by Twilio)\n    * [`CALL_SHOW_CALLER_ID`](#call_show_caller_id) controls the Caller ID lookup (0.01 USD per a call, billed by Twilio)\n  * Send the email when the call missed, to [`CALL_ALERT_TO_EMAIL_ADDRESS`](#call_alert_to_email_address)\n* After the call end, route to [`/calls/forward/result`](#post-callsforwardresult)\n\n### `POST /calls/forward/result`\n\n* Speak back the result of the call, and then hang up\n\n### `POST /texts`\n\n* Exchange the inbound text\n  * If the text is from one of [`TEXT_COMMAND_PHONE_NUMBER`](#text_command_phone_number), route to [`/texts/command`](#post-textscommand).\n  * Otherwise, route to [`/texts/forward`](#post-textsforward).\n\n### `POST /texts/command`\n\n* **Text Command mode**\n* Send the outbound text, when the inbound text is following format:\n\n  ```plain\n  TO_NUMBER:MESSAGE_BODY\n  ```\n\n  * `TO_NUMBER` must be [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164).\n\n### `POST /texts/forward`\n\n* **Text Forward mode**\n* Forward the inbound text to desired receive phone number\n  * If the text is from the US number, forward to [`TEXT_RECEIVE_US_PHONE_NUMBER`](#text_receive_us_phone_number).\n  * Otherwise, forward to [`TEXT_RECEIVE_INTL_PHONE_NUMBER`](#text_receive_intl_phone_number).\n* Forward the inbound text to [`TEXT_ALERT_TO_EMAIL_ADDRESS`](#text_alert_to_email_address)\n\n## Environmental variables\n\nEnvironmental variables could be stored in `.env` file in the root directory.\nThe example template is located at `.env.template`.\n\n### `TWILIO_PBX_URI_BASE`\n\n* Base URI to bind and run the Twilio PBX server\n* It must include the trailing `/`.\n* format: `string`\n* example:\n  * `/` if deployed on local\n  * `/pbx/` if deployed on Firebase Cloud Functions\n  * Again, do not forget the trailing `/`.\n\n### `TWILIO_PBX_PORT`\n\n* Port number to bind and run the Twilio PBX server\n* format: `int`\n* example: `3000`\n\n### `SENDGRID_API_KEY`\n\n* SendGrid API key\n* format: `string`\n\n### `SENDGRID_API_PATH`\n\n* SendGrid API endpoint\n* format: `uri`\n* default: `https://api.sendgrid.com/v3/mail/send`\n\n### `TWILIO_ACCOUNT_SID`\n\n* Twilio account SID\n* format: `string`\n\n### `TWILIO_AUTH_TOKEN`\n\n* Twilio auth token\n* format: `string`\n\n### `CALL_ALERT_FROM_EMAIL_ADDRESS`\n\n* Source email address to send the [Call Alert](#call-alert)\n* The address should be a Sender address in SendGrid\n* format: `string` - `domain` or `email`\n  * If the value is `domain`, [`CALL_ALERT_FROM_EMAIL_DOMAIN_ONLY`](#call_alert_from_email_domain_only) should be `1`.\n\n### `CALL_ALERT_FROM_EMAIL_DOMAIN_ONLY`\n\n* Flag if the value of [`CALL_ALERT_FROM_EMAIL_ADDRESS`](#call_alert_from_email_address) is domain only or not\n* format: `int` - `0` or `1`\n  * `1` if [`CALL_ALERT_FROM_EMAIL_ADDRESS`](#call_alert_from_email_address) is `domain`, otherwise `0`.\n* notes:\n  * If the value is `1`, Twilio PBX will generate the email sender as following format:\n    * `USERNAME` `@` [`CALL_ALERT_FROM_EMAIL_ADDRESS`](#call_alert_from_email_address)\n    * `USERNAME` will be [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164) phone number without `+` sign.\n    * All the possible addresses should be Sender addresses in SendGrid.\n\n### `CALL_ALERT_TO_EMAIL_ADDRESS`\n\n* Destination email address to receive the [Call Alert](#call-alert)\n* format: `string` - `email`\n\n### `CALL_COMMAND_PHONE_NUMBER`\n\n* Source phone number for the [Call Command mode](#call-command-mode)\n  * All the numbers here will be routed to the [Call Command mode](#call-command-mode).\n  * Others will be routed to the [Call Forwarding mode](#call-forwarding-mode).\n* format: `,` seperated `string` - [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164) phone number\n* example: `+12120007890,+821000337890`\n\n### `CALL_COMMAND_TIMEOUT`\n\n* Timeout for waiting the number press in the [Call Command mode](#call-command-mode)\n* format: `int` - positive integer, in seconds\n\n### `CALL_RECEIVE_US_PHONE_NUMBER`\n\n* Destination phone number for US Twilio number [Call Forwarding mode](#call-forwarding-mode)\n* format: `string` - [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164) phone number\n* example: `+12120007890`\n\n### `CALL_RECEIVE_INTL_PHONE_NUMBER`\n\n* Destination phone number for non-US Twilio number [Call Forwarding mode](#call-forwarding-mode)\n* format: `string` - [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164) phone number\n* example: `+821000337890`\n* notes:\n  * Twilio blocks the message outbound to US for non-US Twilio numbers.\n  * If you set the US number here for non-US Twilio number, you cannot receive the [Call Alert](#call-alert) message.\n\n### `CALL_RECEIVE_TIMEOUT`\n\n* Timeout for waiting the destination phone response in the [Call Forwarding mode](#call-forwarding-mode)\n* format: `int` - positive integer, in seconds\n\n### `CALL_SHOW_CARRIER`\n\n* Flag for include the carrier information in the [Call Alert](#call-alert)\n* format: `int` - `0` or `1`\n* notes:\n  * It uses Twilio Lookup API - Carrier\n  * It costs additional 0.005 USD per a call\n\n### `CALL_SHOW_CALLER_ID`\n\n* Flag for include the Caller ID in the [Call Alert](#call-alert)\n* format: `int` - `0` or `1`\n* notes:\n  * It uses Twilio Lookup API - Carrier\n  * It costs additional 0.01 USD per a call\n\n### `TEXT_ALERT_FROM_EMAIL_ADDRESS`\n\n* Source email address to send the [Text Alert](#text-alert)\n* The address should be a Sender address in SendGrid\n* format: `string` - `domain` or `email`\n  * If the value is `domain`, [`TEXT_ALERT_FROM_EMAIL_DOMAIN_ONLY`](#text_alert_from_email_domain_only) should be `1`.\n\n### `TEXT_ALERT_FROM_EMAIL_DOMAIN_ONLY`\n\n* Flag if the value of `TEXT_ALERT_FROM_EMAIL_ADDRESS` is domain only or not\n* format: `int` - `0` or `1`\n  * `1` if [`TEXT_ALERT_FROM_EMAIL_ADDRESS`](#text_alert_from_email_address) is `domain`, otherwise `0`.\n* notes:\n  * If the value is `1`, Twilio PBX will generate the email sender as following format:\n    * `USERNAME` `@` [`TEXT_ALERT_FROM_EMAIL_ADDRESS`](#text_alert_from_email_address)\n    * `USERNAME` will be [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164) phone number without `+` sign.\n    * All the possible addresses should be Sender addresses in SendGrid.\n\n### `TEXT_ALERT_TO_EMAIL_ADDRESS`\n\n* Destination email address to receive the [Text Alert](#text-alert)\n* format: `string` - `email`\n\n### `TEXT_COMMAND_PHONE_NUMBER`\n\n* Source phone number for the [Text Command mode](#text-command-mode)\n  * All the numbers here will be routed to the [Text Command mode](#text-command-mode).\n  * Others will be routed to the [Text Forwarding mode](#text-forwarding-mode).\n* format: `,` seperated `string` - [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164) phone number\n* example: `+12120007890,+821000337890`\n* notes:\n  * Twilio blocks the message outbound to US for non-US Twilio numbers.\n  * If you set the US number here for non-US Twilio number, you cannot receive the command response.\n  * If you send to the US number from non-US Twilio number, it will be undelivered silently.\n\n### `TEXT_RECEIVE_US_PHONE_NUMBER`\n\n* Destination phone number for US Twilio number [Text Forwarding mode](#text-forwarding-mode)\n* format: `string` - [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164) phone number\n* example: `+12120007890`\n\n### `TEXT_RECEIVE_INTL_PHONE_NUMBER`\n\n* Destination phone number for non-US Twilio number [Text Forwarding mode](#text-forwarding-mode)\n* format: `string` - [E.164 formatted](https://www.twilio.com/docs/glossary/what-e164) phone number\n* example: `+821000337890`\n* notes:\n  * Twilio blocks the message outbound to US for non-US Twilio numbers.\n  * If you set the US number here for non-US Twilio number, you cannot receive the [Text Alert](#text-alert) message.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmkim%2Ftwilio-pbx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmkim%2Ftwilio-pbx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmkim%2Ftwilio-pbx/lists"}