Running code samples in the Developer Guide
About RingCentral code samples and environment variables
To help developers make use of the many code samples found throughout this Developer Guide, each code sample is designed around the same usage pattern familiar to many developers. Commonly used variables, like your RingCentral application client ID, secret key, server URL and more, are collected together and placed in a config file, that is then loaded into your local environment upon script execution.
This is helpful as developers should know because it keeps your code separate from the preferences ands data that govern your code's behavior. This is how most modern CI/CD system are architected today, and makes it much easier for developers to containerize their code.
Creating a JWT credential
All code samples within the RingCentral Developer Guide utilize JWT authentication, which requires developers to first create a JWT credential. A JWT auth works similarly to username and password auth by following the same basic sequence of calls:
- Developer presents JWT credential to
/restapi/oath/token - RingCentral responds with an access token
- Developer presents access token in HTTP Authorization header to call the API
To execute code samples in the Developer Guide, please create a JWT credential now.
Your RingCentral .env file
Each code sample found within this Developer Guide is designed to use the variables found within a .env file to properly configure itself to run.
To begin, copy the contents of the file below and save it to your local development machine in a file named .env. Be sure to place that file within the same directory you will be running your test scripts from. Finally, edit the .env file to set the values of its variables accordingly.
# Create an app in the RingCentral Developer Console. Make sure the app has all permissions enabled.
# Enter in the credentials for this app into the fields below.
# Test on localhost when needed. Can be any open port
PORT = 3000
# Production
RC_SERVER_URL = 'https://platform.ringcentral.com'
RC_APP_CLIENT_ID = ''
RC_APP_CLIENT_SECRET = ''
# This credential is used for JWT-grant types
RC_USER_JWT = ''
# Used in messaging/quick-start.*
# For code testing purpose, we set the SMS recipient's phone number to this environment variable.
# You can set the phone number via this variable, or you can set it directly on your code.
SMS_RECIPIENT = ''
# Used in messaging/send-fax.*
# For code testing purpose, we set the Fax recipient's phone number to this environment variable.
# You can set the phone number via this variable, or you can set it directly on your code.
FAX_RECIPIENT = ''
# Used in voice/quick-start.*
# You can set the phone number via this variable, or you can set it directly on your code.
# For code testing purpose, we set the caller's phone number in this environment variable.
RINGOUT_CALLER = ''
# For code testing purpose, we set the callee's phone number in this environment variable.
RINGOUT_RECIPIENT = ''
# Used in voice/call-forwarding.*
# For code testing purpose, we set the forwarding phone number in this environment variable.
# You can set the phone number via this variable, or you can set it directly on your code.
FORWARDING_NUMBER = ''
# Used in code flow authentication Quick Start
# The following URL cannot be blank when running the code flow authentication Quick Start.
RC_REDIRECT_URL = 'http://localhost:5000/oauth2callback'
# Used throughout AI (Artificial Intelligence API)
CONTENT_URI=https://github.com/ringcentral/ringcentral-api-docs/raw/main/resources/sample-calls.mp3
NGROK_URL=''
# Used in the Team Messaging bot code samples
# The following URL is your bot webhook delivery address
RC_BOT_WEBHOOK_URL = ''
# Used in the WebHook notification code samples
# The following URL is your webhook delivery address
WEBHOOK_DELIVERY_ADDRESS = ''
Finally, run your code sample from the command line as you would normally. The script should read in the values from this file, and set all the local configuration properties accordingly.
.env file security
Your .env files contain sensitive information. Here are some tips to help keep them secure.
* Keep .env files out of source control. Don't check in .env files to source control. Consider using a vault instead, and add .env files to your .git-ignore (or equivalent) file.
* Don't make .env files web-accessible. Do not deploy your .env file to a directory that is accessible via http. Keep these files out of your web root folder.