A Virtual PBX Server for Twilio. Supports standalone Node.js server and Firebase Cloud Functions.
(Make a call)
- To make a call:
- Call to your Twilio number, from one of
CALL_COMMAND_PHONE_NUMBER. - In the call, you can dial the number.
- In the call, a new call will be made with your Twilio number, to the dialed number.
- Call to your Twilio number, from one of
(Receive a call)
- Calls to your Twilio number will be forwarded to the desired number:
- If the call is from the US number, it will be forwarded to
CALL_RECEIVE_US_PHONE_NUMBER. - Otherwise, it will be forwarded to
CALL_RECEIVE_INTL_PHONE_NUMBER. - Exceptions: the calls from the numbers in
CALL_COMMAND_PHONE_NUMBERwill be routed to the Call Command mode.
- If the call is from the US number, it will be forwarded to
- Call Alert will be sent to your Twilio number, simultaneously.
(Alert the call: incoming call and missed call)
-
With the call forwarding, Call Alert will be sent to your Twilio number.
-
If you have multiple Twilio numbers, this will help you identify the number which has the call.
-
The message for incoming call looks like below:
Incoming call: +12120007890 (US) Name: KIM,JONGMIN Carrier: T-Mobile USA, Inc. (mobile)- You can control the information included in the message:
-
CALL_SHOW_CARRIERcontrols the carrier lookup (0.005 USD per a call, billed by Twilio)Incoming call: +12120007890 (US) Carrier: T-Mobile USA, Inc. (mobile) -
CALL_SHOW_CALLER_IDcontrols the Caller ID lookup (0.01 USD per a call, billed by Twilio)Incoming call: +12120007890 (US) Name: KIM,JONGMIN -
If both flags disabled, the message would be like below:
Incoming call: +12120007890 (US)
-
- You can control the information included in the message:
-
-
When you missed the call, Call Alert will be sent to your email
CALL_ALERT_TO_EMAIL_ADDRESS.-
The email for missed call looks like below:
Subject: Missed call: +12120007890 From: 12120007890@example.com To: jmkim@jongmin.dev Missed call: +12120007890
-
(Send a message)
-
Text to your Twilio number, from one of
TEXT_COMMAND_PHONE_NUMBER. -
The message format should follow below:
TO_NUMBER:MESSAGE_BODYTO_NUMBERmust be E.164 formatted.
-
Examples:
-
Single-line text example:
+12120007890:Hi-
will send below message to
+1 (212) 000-7890:Hi
-
-
Multi-line text example:
+821000337890:Hey, this is Jongmin. Happy holiday o/-
will send below message to
+82 10-0033-7890:Hey, this is Jongmin. Happy holiday o/
-
-
(Receive a message)
- Texts to your Twilio number will be forwarded to the desired number:
- If the text is from the US number, it will be forwarded to
TEXT_RECEIVE_US_PHONE_NUMBER. - Otherwise, it will be forwarded to
TEXT_RECEIVE_INTL_PHONE_NUMBER. - Exceptions: the calls from the numbers in
TEXT_COMMAND_PHONE_NUMBERwill be routed to the Text Command mode.
- If the text is from the US number, it will be forwarded to
- Text Alert will be sent to the email, simultaneously.
(Alert the text: incoming text)
- With the text forwarding, Text Alert email will be sent to
TEXT_ALERT_TO_EMAIL_ADDRESS.-
The email for incoming text looks like below:
Subject: New message: +12120007890 From: 12120007890@example.com To: jmkim@jongmin.dev Hey, this is Jongmin. Happy holiday o/
-
twilio-pbx supports two ways for deployment: one is Node.js Standalone server and another is Firebase Cloud Functions.
-
Install npm dependencies
npm install
-
Copy the
.envfile from.env.templatecp .env.template .env
-
Edit the
.envfile -
Run the server
npm run start
-
Make ready the Firebase Cloud Functions
-
Create the project at firebase.google.com.
-
Make sure the billing is activated, which is required by the Firebase Cloud Functions.
- Note: Firebase Cloud Functions is only available with paid account. It does not offer the free trial.
-
Install and login to Firebase
npm install -g firebase-tools # Globally install the Firebase CLI Tools firebase login # Login
-
-
Copy the
.firebasercfile from.firebaserc.templatecp .firebaserc.template .firebaserc
-
Set the actual project name in
.firebaserc- Replace
FIREBASE_PROJECT_NAME_HEREwith the actual project name
- Replace
-
Copy the
.envfile from.env.templatecp .env.template .env
-
Edit the
.envfile -
Emulate the server in local machine
npm run serve
-
Deploy the server to the Firebase Cloud Functions
npm run deploy
- Exchange the inbound call
- If the call is from one of
CALL_COMMAND_PHONE_NUMBER, route to/calls/command. - Otherwise, route to
/calls/forward.
- If the call is from one of
- Call Command mode
- Let the user press the dial, to make the outbound call
- Uses DTMF (tone dialing).
- Dialing finishes on
#key, or after the timeout withCALL_COMMAND_TIMEOUT.
- After the dialing, route to
/calls/dial
- Make the call to the number gathered by
/calls/command - After the call end, route to
/calls/dial/result
- Speak back the result of the call, and then hang up
- Call Forward mode
- Forward the inbound call to desired receive phone number
- If the call is from the US number, forward to
CALL_RECEIVE_US_PHONE_NUMBER. - Otherwise, forward to
CALL_RECEIVE_INTL_PHONE_NUMBER. - Send the carrier and/or Caller ID information to desired receive phone number.
CALL_SHOW_CARRIERcontrols the carrier lookup (0.005 USD per a call, billed by Twilio)CALL_SHOW_CALLER_IDcontrols the Caller ID lookup (0.01 USD per a call, billed by Twilio)
- Send the email when the call missed, to
CALL_ALERT_TO_EMAIL_ADDRESS
- If the call is from the US number, forward to
- After the call end, route to
/calls/forward/result
- Speak back the result of the call, and then hang up
- Exchange the inbound text
- If the text is from one of
TEXT_COMMAND_PHONE_NUMBER, route to/texts/command. - Otherwise, route to
/texts/forward.
- If the text is from one of
-
Text Command mode
-
Send the outbound text, when the inbound text is following format:
TO_NUMBER:MESSAGE_BODYTO_NUMBERmust be E.164 formatted.
- Text Forward mode
- Forward the inbound text to desired receive phone number
- If the text is from the US number, forward to
TEXT_RECEIVE_US_PHONE_NUMBER. - Otherwise, forward to
TEXT_RECEIVE_INTL_PHONE_NUMBER.
- If the text is from the US number, forward to
- Forward the inbound text to
TEXT_ALERT_TO_EMAIL_ADDRESS
Environmental variables could be stored in .env file in the roo
8000
t directory.
The example template is located at .env.template.
- Base URI to bind and run the Twilio PBX server
- It must include the trailing
/. - format:
string - example:
/if deployed on local/pbx/if deployed on Firebase Cloud Functions- Again, do not forget the trailing
/.
- Port number to bind and run the Twilio PBX server
- format:
int - example:
3000
- SendGrid API key
- format:
string
- SendGrid API endpoint
- format:
uri - default:
https://api.sendgrid.com/v3/mail/send
- Twilio account SID
- format:
string
- Twilio auth token
- format:
string
- Source email address to send the Call Alert
- The address should be a Sender address in SendGrid
- format:
string-domainoremail- If the value is
domain,CALL_ALERT_FROM_EMAIL_DOMAIN_ONLYshould be1.
- If the value is
- Flag if the value of
CALL_ALERT_FROM_EMAIL_ADDRESSis domain only or not - format:
int-0or11ifCALL_ALERT_FROM_EMAIL_ADDRESSisdomain, otherwise0.
- notes:
- If the value is
1, Twilio PBX will generate the email sender as following format:USERNAME@CALL_ALERT_FROM_EMAIL_ADDRESSUSERNAMEwill be E.164 formatted phone number without+sign.- All the possible addresses should be Sender addresses in SendGrid.
- If the value is
- Destination email address to receive the Call Alert
- format:
string-email
- Source phone number for the Call Command mode
- All the numbers here will be routed to the Call Command mode.
- Others will be routed to the Call Forwarding mode.
- format:
,seperatedstring- E.164 formatted phone number - example:
+12120007890,+821000337890
- Timeout for waiting the number press in the Call Command mode
- format:
int- positive integer, in seconds
- Destination phone number for US Twilio number Call Forwarding mode
- format:
string- E.164 formatted phone number - example:
+12120007890
- Destination phone number for non-US Twilio number Call Forwarding mode
- format:
string- E.164 formatted phone number - example:
+821000337890 - notes:
- Twilio blocks the message outbound to US for non-US Twilio numbers.
- If you set the US number here for non-US Twilio number, you cannot receive the Call Alert message.
- Timeout for waiting the destination phone response in the Call Forwarding mode
- format:
int- positive integer, in seconds
- Flag for include the carrier information in the Call Alert
- format:
int-0or1 - notes:
- It uses Twilio Lookup API - Carrier
- It costs additional 0.005 USD per a call
- Flag for include the Caller ID in the Call Alert
- format:
int-0or1 - notes:
- It uses Twilio Lookup API - Carrier
- It costs additional 0.01 USD per a call
- Source email address to send the Text Alert
- The address should be a Sender address in SendGrid
- format:
string-domainoremail- If the value is
domain,TEXT_ALERT_FROM_EMAIL_DOMAIN_ONLYshould be1.
- If the value is
- Flag if the value of
TEXT_ALERT_FROM_EMAIL_ADDRESSis domain only or not - format:
int-0or11ifTEXT_ALERT_FROM_EMAIL_ADDRESSisdomain, otherwise0.
- notes:
- If the value is
1, Twilio PBX will generate the email sender as following format:USERNAME@TEXT_ALERT_FROM_EMAIL_ADDRESSUSERNAMEwill be E.164 formatted phone number without+sign.- All the possible addresses should be Sender addresses in SendGrid.
- If the value is
- Destination email address to receive the Text Alert
- format:
string-email
- Source phone number for the Text Command mode
- All the numbers here will be routed to the Text Command mode.
- Others will be routed to the Text Forwarding mode.
- format:
,seperatedstring- E.164 formatted phone number - example:
+12120007890,+821000337890 - notes:
- Twilio blocks the message outbound to US for non-US Twilio numbers.
- If you set the US number here for non-US Twilio number, you cannot receive the command response.
- If you send to the US number from non-US Twilio number, it will be undelivered silently.
- Destination phone number for US Twilio number Text Forwarding mode
- format:
string- E.164 formatted phone number - example:
+12120007890
- Destination phone number for non-US Twilio number Text Forwarding mode
- format:
string- E.164 formatted phone number - example:
+821000337890 - notes:
- Twilio blocks the message outbound to US for non-US Twilio numbers.
- If you set the US number here for non-US Twilio number, you cannot receive the Text Alert message.