When someone sends you a fax, it’s received by Telecoms Cloud and your application makes an HTTP request to the FAX resource to get data about, and download, your received faxes.
The first thing we’ll need is a Telecoms Cloud fax number, so if you’ve not done so already sign up using this link. Choose any number you like and then keep a note of it once you’ve bought it so we can use it in our script.
You’ll then need to generate yourself a set of Credentials to use with the API. In your Telecoms Cloud account just head over to your API Settings page to generate your Client ID and Client Secret.
Then, in your favourite text editor create a new script, and we’ll start by requiring the “request” and “fs” modules. The first thing we need to do is authenticate ourselves by creating a POST request to the /authorization resource and POSTing our API credentials as JSON data in the request. We’ll receive back an access token, which we can use to sign our requests to any of the API’s resources.
PAUSE: In the real world, you should save this access token either in a database or some local storage, and re-use it with each request until it expires.
We’ll start by constructing a GET request to the fax/inbound/info endpoint to retrieve information about new faxes received to any fax number within our Telecoms Cloud account. In the query string we’ll include the last_pointer, which tells the API the last fax we received and processed so that it can only give us information about new faxes. The very first time our script is run, we’ll pass a zero because we’ve not processed any faxes yet. We’ll also sign our request with that access token to authenticate.
That request will return a list of fax records as JSON data, which we can then loop through to extract information such as the sender’s number, date & time of receipt, etc. as well as a unique pointer for each fax.
You should save the pointer for the last fax you process, so you can pass it next time you request a list of any new received faxes.
Each fax record also has its own unique ID, which we can use in another request to GET a secure URL which we can use to download the fax document itself and save it to our local storage ready for whatever further processing your app needs to do.
So, let’s run our script and then watch the folder to see our downloaded fax documents appearing.
That’s all there is to it! You can download a copy of this example code, and don’t forget to add in things like proper error handling and any other processing required by your application.
Don’t forget to subscribe to Telecoms Cloud on YouTube and follow us on Twitter. If you’ve got any questions or comments please leave them below and take a look at our other videos to learn more about what you can do with Telecoms Cloud.