RingCentral’s Fax API and PHP

Faxes, yes faxes are still a thing! I was just at my local pharmacy and they said they could fax my doctor with some questions I had about my medications, and even get a refill prescription from him if needed. This got me thinking and reading about how much fax technology is still being used in this “modern age”. Banks, high finance, law offices, government agencies, law courts, and real estate are all still using fax technology in addition to the above-mentioned health care. The main reasons faxes are still in use are:

• Inertia: Some industries are just used to it,
• Perceived security: there is a sense of security inherent in it, and
• Faxes are “paper-based”

The third point is kind of ironic, because with the move to cloud-based fax services, the physical paper aspect of the transmission has been largely removed. Only a few people are still standing by a FAX machine feeding it paper. The essence of being “paper-based” remains, though, in that it is still a non-editable document that gets transmitted. In addition, from a security perspective, the transmission is fully encrypted; at least it should be. So be sure to check your provider if you are not sure on this point. RingCentral’s Fax API and supporting features have all of the above-mentioned attributes and requirements so you can be confident in using it.

I wanted to play with RingCentral’s Fax API in my favorite web development language of PHP. I built a small app that accepts a receiving fax phone number, a fax cover note, and the ability to attach a document to the fax payload. The Fax API does need an authorized app created on the RingCentral Developer platform.

Follow these steps to create an app and get the credentials to the API.

1. Login or create an account if you have not done so already.
2. Go to Console/Apps and click the ‘Create App’ button.
3. Select “REST API App” under “What type of app are you creating?” Click “Next.”
4. Under “Auth” select “JWT auth flow”
5. Under “Security” add the following permissions: Faxes
6. Under “Security” select “This app is private and will only be callable using credentials from the same RingCentral account.”

Be sure that your app has “Faxes” selected in the application scope section of Security. See Figure 1.

Figure 1 — RingCentral Developers app scope selection

When you are done, you will be taken to the app’s dashboard. Make note of the Client ID and Client Secret keys.

Next, you will need a JWT key. Go here to see how to get a JWT key code for use. For simplicity, I hardcoded these values in my app, but you can either ask for them on the fax form page or store them in a database. My PHP application screen looks like the following.

Figure 2 — PHP Fax preparation form

After the form is submitted (remember you have to add “enctype=’multipart/form-data’ ” to the <form > tag when uploading files) some data integrity checks are executed. Then I upload the file that will be attached to the fax to my server with the upload_file() function [1]. See Figure 3 for this code segment. You can see the details of the upload_file() function if you connect to my code on GitHub — the link is at the end of this article.

Figure 3 — PHP Form submission processing code

The upload_file() function tests for the allowed file types (images and PDFs) and the maximum file size. Then if all is good it puts the file in my “uploads/” folder on the server. I then [2] call my send_fax() function to send out the fax with the information collected from the form. When the send completes, I create a “success” message [3] and remove the file from my server so that the file count doesn’t grow there. Then I simply re-display my form with the sent fax identifier for reference. The form can then be re-used to send out another fax if desired.

Most of the API heavy lifting is done inside the send_fax() function. See Figure 4.

Figure 4 — Fax sending function

Here I call my SDK connection function, set my fax body parameters based on the collected form data, add the file attachment with the “add(fopen() )” call, point the SDK at the fax API endpoint with the “request” directive, and then call the sendRequest method passing the parameters to it. Since this is all in a try/catch structure we can manage any errors that may be returned if we encounter something incorrect or untoward. If all goes as planned, we can pick up the sent fax reference identifier with JSON ()->id and send it back to the PHP form for future use if needed.

My SDK code follows but you would have to provide your own credentials.

Figure 5 — SDK Connecting function

Figure 6 shows a successfully sent fax with a cover page, my custom cover note, and the attached PDF of a US Government W-7 form.

Figure 6 — Sent Fax content

There are a lot of balances and controls that you can add here. For example:

1. Create your own custom cover page.
2. Check on the status of the outgoing fax, if the receiving phone line was busy, for example.
3. Send one fax package to multiple recipients.
4. Upload/attach multiple documents to a single fax transmission.

For further reading go to the RingCentral Developers site and check out the Fax API reference. My code is here in GitHub if you want to use it as a starting point for your own projects.