phaxio-official

It is suggested that you ONLY use this library with Node.js 8 or higher.

Installation

# Stable Version:
npm install --save phaxio-official
# Development Version:
npm install --save https://github.com/phaxio/phaxio-node

Example Usage

Every method in phaxio returns a Promise. You should also be able to use async/await syntax with these methods.

See the test directory for more examples.

// Assuming you have a .env file in your project that contains your// API credentials and you have installed the `dotenv` package from// NPM so that you can attach those variables to the Node environment.const{ config }=require('dotenv');config();if(process.env.PHAXIOKEY===undefined||process.env.PHAXIOSECRET===undefined){console.log('No `PHAXIOKEY` or `PHAXIOSECRET` found in file `.env`. Exiting.');process.exit();}constPhaxio=require('phaxio-official');constphaxio=newPhaxio(process.env.PHAXIOKEY,process.env.PHAXIOSECRET);// Send a single fax containing two documents: one a URL, one from the filesystem.phaxio.faxes.create({to: '+1234567890',// Replace this with a number that can receive faxes.content_url: 'https://google.com',file: `${__dirname}/sample1.pdf`,}).then((fax)=>{// The `create` method returns a fax object with methods attached to it for doing things// like cancelling, resending, getting info, etc.// Wait 5 seconds to let the fax send, then get the status of the fax by getting its info from the API.returnsetTimeout(()=>{fax.getInfo()},5000)}).then(status=>console.log('Fax status response:\n',JSON.stringify(status,null,2))).catch((err)=>{throwerr;});// Get a list of all the faxes you have sent in the past and re-send the most recent one.phaxio.faxes.listFaxes({direction: 'sent'}).then((faxes)=>{constmostRecent=faxes.data.reduce((acc,cv)=>{constaccCreated=newDate(acc.created_at);constcvCreated=newDate(cv.created_at);constoutput=accCreated>cvCreated ? acc : cv;returnoutput;},{created_at: '1970-01-01T00:00:00.000Z'});returnphaxio.faxes.resend({id: mostRecent.id});}).then(response=>console.log('Response from resending most recent fax:\n',JSON.stringify(response,null,2));.catch((err)=>{throwerr;});

Documentation

Phaxio methods are categorized according to the Phaxio API route that they target. See the Phaxio Docs for more information about the raw API.

Initialization

Initializing the Phaxio class takes two required arguments, the Key and Secret you retreived from Phaxio, and allows for one optional argument, the minimum TLS version to use. By default, the minimum TLS version is set to TLSv1.2. See the TLS documentation for other possible options to minVersion if you require something other than TLSv1.2. Modifying the minimum TLS version is not recommended.

Arguments:

Key	Value Type	Required?	Description
`phaxio api key`	String	True	Your Phaxio API Key
`phaxio api secret`	String	True	Your Phaxio API Secret
`minimum TLS Version`	String	False	Default: `TLSv1.2`, other possible options are the same as `minVersion` in the TLS documentation.

constPhaxio=require('phaxio-official');constphaxio=newPhaxio(<phaxioapikey>, <phaxioapisecret>, [optional: <minimumTLSversion>]);

All Phaxio methods take one argument: either a single argument such as an ID, or an Object containing key: value parameters. See the documentation below for specifics.

Public

`phaxio.public.getAreaCodes()`

Displays a list of area codes available for purchasing Phaxio numbers. This operation requires no authentication and can be used without passing an API key.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`toll_free`	Boolean	False	If set to `true`, only toll free area codes will be returned. If specified and set to `false`, only non-toll free area codes will be returned.
`country_code`	Integer	False	A country code (E.164) you'd like to filter by.
`country`	String	False	A two character country abbreviation (ISO 3166; e.g. `US` or `CA`) you'd like to filter by.
`state`	String	False	A two character state or province abbreviation (ISO 3166; e.g. `IL` or `YT`) you'd like to filter by. When using this parameter, `country_code` or `country` must also be provided.
`per_page`	Integer	False	Maximum number of results returned per call or "page".
`page`	Integer	False	The current page number. 1-based.

phaxio.public.getAreaCodes().then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.public.getCountries()`

Returns a list of supported countries for sending and receiving faxes on Phaxio. This operation requires no authentication and can be used without passing an API key.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`per_page`	Integer	False	Maximum number of results returned per call or "page".
`page`	Integer	False	The current page number. 1-based.

phaxio.public.getCountries().then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

Faxes

`phaxio.faxes.create()`

Create and send a fax.

Returns a Fax Object with methods attached. More detail on Fax Objects after the example.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`to`	String or Array	True	A phone number in E.164 format (+[country code][number]). Pass an `Array` to send to multiple numbers.
`file`	String or Array	Only when sending files from filesystem	The file you wish to fax. A least one file or content_url parameter is required. Pass an `Array` to send to multiple files.
`content_url`	String or Array	Only when sending public URL's	URL to be rendered and sent as the fax content. At least one file or content_url parameter is required. Pass an `Array` to send to multiple URL's.
`header_text`	String	False	Text that will be displayed at the top of each page of the fax. 50 characters maximum. Default header text is "-". Note that the header is not applied until the fax is transmitted, so it will not appear on fax PDFs or thumbnails.
`batch_delay`	Integer	False	Specifies the amount of time in seconds before the batch is fired. Maximum is 3600 (1 hour).
`batch_collision_avoidance`	Boolean	False	When batch_delay is set to 'true', fax will be blocked until the receiving machine is no longer busy. See docs for more info. Default is 'false'.
`callback_url`	String	False	You can specify a callback url that will override the one you have defined globally for your account.
`cancel_timeout`	Integer	False	A number of minutes after which the fax will be canceled if it hasn't yet completed. Must be between 3 and 60. Additionally, for faxes with a `batch_delay`, the `cancel_timeout` must be at least 3 minutes after the `batch_delay`. If it is not, it will automatically be extended when batching.
`tags`	Object	False	An object containing `key: value` metadata tags relevant to your application. You may specify up to 10 tags. `{ my_tag1: tag_val1, my_tag2: tag_val2, ..., my_tag10: tag_val10 }`
`caller_id`	String	False	A Phaxio phone number you would like to use for the caller id.
`test_fail`	String	False	When using a test API key, this will simulate a sending failure at Phaxio. The contents of this parameter should be one of the Phaxio error types which will dictate how the fax will "fail".

phaxio.faxes.create({to: '+1234567890',content_url: 'https://google.com',file: 'sample.pdf'}).then(faxObject=>console.log(JSON.stringify(faxObject,null,2))).catch((err)=>{throwerr;});

Fax Objects

Fax Objects are returned by phaxio.faxes.create(). They contain some metadata attributes as well as methods for doing extra things with a particular fax. The methods attached to a Fax Object take one or no arguments as they already have the required metadata to fire off against the raw API.

Method	Arguments	Description
`faxObject.cancel()`	None	Cancels the fax.
`faxObject.resend()`	`callback_url` (optional)	Resends the fax. Default `callback_url` uses the fax's original `callback_url`. Passing a URL string will set the `callback_url` to the new value.
`faxObject.getInfo()`	None	Gets the fax's metadata information.
`faxObject.getFile()`	`thumbnail` (optional)	Gets the fax's document. The default `thumbnail` is `null`, which gets the full PDF file. Specify a string, `'s'` or `'l'`, to get a small or large JPG thumbnail (respectively) of the first page of the document.
`faxObject.deleteFile()`	None	Deletes a document associated with a fax.
`faxObject.testDelete()`	None	Deletes a fax created using Test API Credentials.

// Cancelling a fax you just sent.phaxio.faxes.create({to: '+1234567890',content_url: 'https://google.com'}).then((faxObject)=>{returnfaxObject.cancel();}).then(response=>console.log('Fax cancelled:\n',JSON.stringify(response,null,2))).catch((err)=>{throwerr;});// Suppose that earlier you created a `FaxDB` sequelize model you want to store Fax data into.phaxio.faxes.create({to: '+1234567890',content_url: 'https://google.com'}).then((faxObject)=>{returnfaxObject.getInfo();}).then((faxInfo)=>{constfi=FaxDB.build(faxInfo);returnfi.save();}).then(()=>console.log('Insert successful.')).catch((err)=>{throwerr;});// Write out the thumbnail of a created fax to a file.phaxio.faxes.create({to: '+1234567890',content_url: 'https://google.com'}).then((faxObject)=>{returnfaxObject.getFile('s')}).then(fileString=>fs.writeFileSync(`${__dirname}/thumbnail.jpg`,fileString)).catch((err)=>{throwerr;});

`phaxio.faxes.cancel()`

Cancel a fax.

See docs for more information.

Argument (Value):

Key	Value Type	Required?	Description
`id`	Integer	True	A Fax Identifier

phaxio.faxes.cancel(987).then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.faxes.resend()`

Resend a fax.

See docs for more information.

Argument (Value):

Key	Value Type	Required?	Description
`id`	Integer	True	A Fax Identifier

phaxio.faxes.resend(987).then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.faxes.getInfo()`

Get fax info.

See docs for more information.

Argument (Value):

Key	Value Type	Required?	Description
`id`	Integer	True	A Fax Identifier

phaxio.faxes.getInfo(987).then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.faxes.getFile()`

Get fax content file or thumbnail.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`id`	Integer	True	A Fax Identifier
`thumbnail`	String	False	The default `thumbnail` is `null`, which gets the full file. Specify a string, `'s'` or `'l'`, to get a small or large thumbnail (respectively) of the first page of the document.

phaxio.faxes.getFile({id: 987}).then(fileString=>fs.writeFileSync(`${__dirname}/full_file.pdf`,fileString)).catch((err)=>{throwerr;});

`phaxio.faxes.listFaxes()`

List sent faxes.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`created_before`	String	False	The end of the range. Must be in RFC 3339 format, except that the timezone may be omitted (e.g. `'2016-05-31T23:59:59'`). Defaults to now.
`created_after`	String	False	The beginning of the range. Must be in RFC 3339 format, except that the timezone may be omitted (e.g. `'2016-05-01T00:00:00'`). Defaults to one week ago.
`direction`	String	False	Either `'sent'` or `'received'`. Limits results to faxes with the specified direction.
`status`	String	False	Limits results to faxes with the specified status.
`phone_number`	String	False	A phone number in E.164 format that you want to use to filter results. The phone number must be an exact match, not a number fragment.
`tags`	Object	False	An object containing `key: value` metadata tags relevant to your application. You may specify up to 10 tags. `{ my_tag1: tag_val1, my_tag2: tag_val2, ..., my_tag10: tag_val10 }`
`per_page`	Integer	False	Maximum number of results returned per call or "page".
`page`	Integer	False	The current page number. 1-based.

phaxio.faxes.listFaxes().then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.faxes.deleteFile()`

Delete fax document files.

See docs for more information.

Argument (Value):

Key	Value Type	Required?	Description
`id`	Integer	True	A Fax Identifier

phaxio.faxes.deleteFile(987).then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.faxes.testDelete()`

Delete a sent fax. May only be used with test credentials.

See docs for more information.

Argument (Value):

Key	Value Type	Required?	Description
`id`	Integer	True	A Fax Identifier

phaxio.faxes.testDelete(987).then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.faxes.testReceive()`

Test receiving a fax.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`file`	String	True	A PDF file to simulate receiving.
`from_number`	String	False	The phone number of the simulated sender in E.164 format. Default is the public Phaxio fax number.
`to_number`	String	False	The phone number, in E.164 format, that is receiving the fax. Specifically, a Phaxio phone number you have purchased in your account that is "receiving" the fax, or the public Phaxio fax number. Default is the public Phaxio fax number.

phaxio.faxes.testReceive({file: 'sample.pdf'}).then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

Account

`phaxio.account.status()`

Information about the Phaxio account for the configured API key and secret.

See docs for more information.

Does not take arguments.

phaxio.account.status().then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

PhaxCode

`phaxio.phaxCode.create()`

Create a custom PhaxCode.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`metadata`	String	True	Custom metadata to be associated with this barcode.
`type`	String	False	Defaults to `.json`. Other option is `.png`

phaxio.phaxCode.create({metadata: 'This is my metadata.'}).then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.phaxCode.get()`

Retreive a PhaxCode.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`id`	String	False	PhaxCode Identifier to retrieve. If not specified, provides default PhaxCode for your account.
`type`	String	False	Defaults to `.json`. Other option is `.png`

phaxio.phaxCode.get().then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

Phone Number

`phaxio.phoneNumber.provisionNumber()`

Provision a phone number that you can use to receive faxes in your Phaxio account.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`country_code`	Integer	True	The country code (E.164) of the number you'd like to provision.
`area_code`	Integer	True	The area code of the number you'd like to provision.
`callback_url`	String	False	A callback URL that we'll post to when a fax is received by this number. This will override the global receive callback URL, if you have one specified.

phaxio.phoneNumbers.provisionNumber({country_code: 1,area_code: 847,}).then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.phoneNumber.releaseNumber()`

Release a phone number that you no longer need. Once a phone number is released you will no longer be charged for it.

See docs for more information.

Arguments (Value):

Key	Value Type	Required?	Description
`number`	String	True	The phone number to be released in E.164 format.

phaxio.phoneNumbers.releaseNumber('+1234567890').then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.phoneNumber.getNumberInfo()`

Get information about a phone number you own.

See docs for more information.

Arguments (Value):

Key	Value Type	Required?	Description
`number`	String	True	The phone number to be released in E.164 format.

phaxio.phoneNumber.getNumberInfo().then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

`phaxio.phoneNumber.listNumbers()`

Get a detailed list of the phone numbers that you currently own on Phaxio.

See docs for more information.

Arguments (Object):

Key	Value Type	Required?	Description
`country_code`	Integer	False	The country code (E.164) of the numbers you'd like to list.
`area_code`	Integer	False	The area code of the numbers you'd like to list.

phaxio.phoneNumber.listNumbers().then(response=>console.log(JSON.stringify(response,null,2))).catch((err)=>{throwerr;});

Testing This Package

This package tests against the Phaxio API.

YOU ARE RESPONSIBLE FOR ANY CHARGES ACCRUED WHEN RUNNING THE TEST SUITE.

WARNING Running many of these tests will cause your Phaxio account to be billed, unless you use Test API credentials.

DOUBLE WARNING Running tests for provisioning Phone Numbers WILL ALWAYS bill your account, even if you use Test API credentials. These tests are not run by default. See test/phonenumber/index.test.js for comments on how to enable these tests.

You should create a .env file in the root of this directory containing three pieces of information:

TEST_APIKEY # Your Phaxio Test API Key.
TEST_APISECRET # Your Phaxio Test API Secret.
PHONE_NUMBER # Your Phone Number purchased from Phaxio.

To run the test suite:

npm run test

Note: this test suite uses setTimeout() to reduce the likelihood of receiving rate limiting errors.

LICENSE

See LICENSE file for full detail.

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
src		src
test		test
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Uh oh!

Repository files navigation

phaxio-official

Installation

Example Usage

Documentation

Initialization

Public

`phaxio.public.getAreaCodes()`

`phaxio.public.getCountries()`

Faxes

`phaxio.faxes.create()`

Fax Objects

`phaxio.faxes.cancel()`

`phaxio.faxes.resend()`

`phaxio.faxes.getInfo()`

`phaxio.faxes.getFile()`

`phaxio.faxes.listFaxes()`

`phaxio.faxes.deleteFile()`

`phaxio.faxes.testDelete()`

`phaxio.faxes.testReceive()`

Account

`phaxio.account.status()`

PhaxCode

`phaxio.phaxCode.create()`

`phaxio.phaxCode.get()`

Phone Number

`phaxio.phoneNumber.provisionNumber()`

`phaxio.phoneNumber.releaseNumber()`

`phaxio.phoneNumber.getNumberInfo()`

`phaxio.phoneNumber.listNumbers()`

Testing This Package

LICENSE

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

phaxio-official

Installation

Example Usage

Documentation

Initialization

Public

phaxio.public.getAreaCodes()

phaxio.public.getCountries()

Faxes

phaxio.faxes.create()

Fax Objects

phaxio.faxes.cancel()

phaxio.faxes.resend()

phaxio.faxes.getInfo()

phaxio.faxes.getFile()

phaxio.faxes.listFaxes()

phaxio.faxes.deleteFile()

phaxio.faxes.testDelete()

phaxio.faxes.testReceive()

Account

phaxio.account.status()

PhaxCode

phaxio.phaxCode.create()

phaxio.phaxCode.get()

Phone Number

phaxio.phoneNumber.provisionNumber()

phaxio.phoneNumber.releaseNumber()

phaxio.phoneNumber.getNumberInfo()

phaxio.phoneNumber.listNumbers()

Testing This Package

LICENSE

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`phaxio.public.getAreaCodes()`

`phaxio.public.getCountries()`

`phaxio.faxes.create()`

`phaxio.faxes.cancel()`

`phaxio.faxes.resend()`

`phaxio.faxes.getInfo()`

`phaxio.faxes.getFile()`

`phaxio.faxes.listFaxes()`

`phaxio.faxes.deleteFile()`

`phaxio.faxes.testDelete()`

`phaxio.faxes.testReceive()`

`phaxio.account.status()`

`phaxio.phaxCode.create()`

`phaxio.phaxCode.get()`

`phaxio.phoneNumber.provisionNumber()`

`phaxio.phoneNumber.releaseNumber()`

`phaxio.phoneNumber.getNumberInfo()`

`phaxio.phoneNumber.listNumbers()`