Twilio Migration Guide

| cURL | Python | PHP | Node | Java | .NET | Ruby |


As of December 17th, Twilio will go forward with sunsetting support for their Programmable Fax offering. As such, we have outlined a step-by-step guide to make the transition to Telnyx's Programmable Fax system as painless as possible. This guide will inform and detail the process from start to finish to get you started using Fax with Telnyx!

Transitioning is quite simple, as the general configuration of the app mirrors Twilio's implimentation. In most cases, the only change you will have to make in the code itself is the authentication parameters and the send function.


cURL

Part 1: Account Configuration

To get started using Programmable Fax with Telnyx, you will be required to make an account and attain the following items. A guide on how to set this up can be found at our Quickstart

You will ultimately need the following configured:

Do note, to recieve updates and status of your faxes (both inbound and outbound), you will need to setup a Webhook in the Telnyx Fax Application. This is where we will be sending you all information regarding the fax. For more information on this, you can scroll down to "Part 3: Recieving Faxes" section.

After your account is configured, take note of the following items that you will need to send your specified faxes programmatically.

That's it from the portal perspective! With the 3 pieces of information from above we are ready to start sending and recieving faxes with Telnyx!

Part 2: Sending Faxes

Sending outbound faxes requires:

  • A To number (Destination)
  • A From number (Generally the number you have procured from above)
  • A public facing URL which points to the document you are intending to send, in PDF format.

The code to initiate a fax sendoff would be as follows:

Copy
Copied
curl -X POST https://api.telnyx.com/v2/faxes \
--data-urlencode "media_url=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" \
--data-urlencode "connection_id=YOUR_FAX_APP_ID" \
--data-urlencode "to=YOUR_DESTINATION_NUMBER" \
--data-urlencode "from=YOUR_FROM_NUMBER" \
--header "Authorization: Bearer API "YOUR_API_KEY"

Note: After pasting the above content, Kindly check and remove any new line added

A successful example JSON response to the request will look like:

Copy
Copied
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "direction": "outbound",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Part 3: Recieving Faxes

In order to recieve faxes, you will need to setup a webhook mentioned earlier.

In order for the webhooks in this tutorial to work, Telnyx must be able to send your web application an HTTP request over the Internet. That means your application needs to have a URL or IP address that Telnyx can reach. Telnyx sends webhooks to the URL or IP address to notify your application of incoming faxes.

For the purpose of this tutorial, we're using ngrok, a popular tunneling tool used to expose a locally running application to the internet. ngrok gives you a public URL for a local port on your development machine, which you can use to configure your Telnyx webhooks as described above.

Download and install ngrok, then use it at the command line to create a tunnel to whatever port your web application is running on. For example, this command will create a public URL for a web application listening on port 3000.

Copy
Copied
ngrok http 3000

Note: After pasting the above content, Kindly check and remove any new line added

After executing that command, you will see that ngrok has given your application a public URL that you can use in your webhook connection configuration in the Telnyx Mission Control Portal.

TwiML Twilio Telnyx Conference Flow

Grab your ngrok public URL and head back to the Programmable Fax Application you configured earlier. Now in the field under "Send a webhook to the URL" enter your new ngrok URL from either of the "Forwarding" URLs ngrok provided us with depending on if you want to use HTTP or HTTPS.

You're now all set up to receive webhooks for events related to inbound faxes. If you use the same Programmable Fax Application for sending faxes, you will receive events to the same ngrok URL you just created.

Example Webhooks

If you have set everything up correctly, any time an inbound fax is received you can expect to receive the following webhooks:

Webhook Name Description
fax.receiving.started The fax has begun transmitting to Telnyx successfully.
fax.media.processing.started Telnyx has received the fax and is generating the digital PDF file.
fax.received The PDF has been generated and the file is ready to be downloaded.
fax.failed Transmission of the fax failed. Check the <code>failure_reason</code> for more details.

Fax has begun transmitting to Telnyx

Copy
Copied
{
  "data": {
    "event_type": "fax.receiving.started",
    "id": "bc004786-f166-4dd3-8c5d-737990b501bc",
    "occurred_at": "2020-08-27T16:33:29.684247Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "9fbc3f0d-5495-42af-9a4e-c57a235d9182",
      "from": "+16132484872",
      "status": "receiving",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Fax transmission is complete and Telnyx is converting to PDF

Copy
Copied
{
  "data": {
    "event_type": "fax.media.processing.started",
    "id": "35e33b02-6365-47d0-93b7-3bfec97c467e",
    "occurred_at": "2020-08-27T16:33:33.175396Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "status": "media.processing",
      "page_count": 2,
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

PDF has been generated and is ready for download

The media_url field contains a signed AWS link to a PDF of the received fax. This URL is valid for 10 minutes before the file is no longer accessible so be sure to download the file if you wish to keep it!

Copy
Copied
{
  "data": {
    "event_type": "fax.received",
    "id": "4844b70c-3c6c-4c3a-ba2e-e4c785f02d24",
    "occurred_at": "2020-08-27T16:33:36.843054Z",
    "payload": {
      "call_duration_secs": 50,
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "media_url": "https://s3.amazonaws.com/faxes-prod/19a75cea-02c6-4b9a-84fa-c9bc8341feb8/f72eebbe-f9b6-4f0f-b652-03e742e110d5.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASDC5E2MJIX77C6J7%2F20200827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200827T163336Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=eef2716f51dcd13d3f8a070bbaf1f88dfed0d4fab901337a6316529dc9a3374a",
      "page_count": 2,
      "partial_content": false,
      "status": "received",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Uh oh, something has gone wrong and the fax failed

Inbound faxes can fail for a variety of reasons. Some of the most common reasons are that the sending party hung up before the fax was finished transmitting or didn't send anything at all.

Copy
Copied
{
  "data": {
    "event_type": "fax.failed",
    "id": "1a7405a6-696c-4369-a0b1-168e4bb7e22c",
    "occurred_at": "2020-08-27T16:17:51.844250Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "failure_reason": "sender_call_dropped",
      "fax_id": "181533f3-b0b8-4bcd-ab01-b33cd8698508",
      "from": "+16617480240",
      "status": "failed",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Python

Part 1: Account Configuration

To get started using Programmable Fax with Telnyx, you will be required to make an account and attain the following items. A guide on how to set this up can be found at our Quickstart

You will ultimately need the following configured:

Do note, to recieve updates and status of your faxes (both inbound and outbound), you will need to setup a Webhook in the Telnyx Fax Application. This is where we will be sending you all information regarding the fax. For more information on this, you can scroll down to "Part 3: Recieving Faxes" section.

After your account is configured, take note of the following items that you will need to send your specified faxes programmatically.

That's it from the portal perspective! With the 3 pieces of information from above we are ready to start sending and recieving faxes with Telnyx!

Part 2: Sending Faxes

Sending outbound faxes requires:

  • A To number (Destination)
  • A From number (Generally the number you have procured from above)
  • A public facing URL which points to the document you are intending to send, in PDF format.

The code to initiate a fax sendoff would be as follows:

Copy
Copied
import telnyx

telnyx.api_key = "YOUR_API_KEY"

fax_app_id = "YOUR_FAX_APP_ID"
your_telnyx_number = "YOUR_TELNYX_NUMBER"
desitnation_number = "YOUR_DESIRED_DESTINATION_NUMBER"

fax_send = telnyx.Fax.create(
            connection_id=TELNYX_FAX_CONNECTION_ID,
            to=to_phone_number,
            from_=from_phone_number,
            media_url=file_url
)

Note: After pasting the above content, Kindly check and remove any new line added

A successful example JSON response to the request will look like:

Copy
Copied
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "direction": "outbound",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Part 3: Recieving Faxes

In order to recieve faxes, you will need to setup a webhook mentioned earlier.

In order for the webhooks in this tutorial to work, Telnyx must be able to send your web application an HTTP request over the Internet. That means your application needs to have a URL or IP address that Telnyx can reach. Telnyx sends webhooks to the URL or IP address to notify your application of incoming faxes.

For the purpose of this tutorial, we're using ngrok, a popular tunneling tool used to expose a locally running application to the internet. ngrok gives you a public URL for a local port on your development machine, which you can use to configure your Telnyx webhooks as described above.

Download and install ngrok, then use it at the command line to create a tunnel to whatever port your web application is running on. For example, this command will create a public URL for a web application listening on port 3000.

Copy
Copied
ngrok http 3000

Note: After pasting the above content, Kindly check and remove any new line added

After executing that command, you will see that ngrok has given your application a public URL that you can use in your webhook connection configuration in the Telnyx Mission Control Portal.

TwiML Twilio Telnyx Conference Flow

Grab your ngrok public URL and head back to the Programmable Fax Application you configured earlier. Now in the field under "Send a webhook to the URL" enter your new ngrok URL from either of the "Forwarding" URLs ngrok provided us with depending on if you want to use HTTP or HTTPS.

You're now all set up to receive webhooks for events related to inbound faxes. If you use the same Programmable Fax Application for sending faxes, you will receive events to the same ngrok URL you just created.

Example Webhooks

If you have set everything up correctly, any time an inbound fax is received you can expect to receive the following webhooks:

Webhook Name Description
fax.receiving.started The fax has begun transmitting to Telnyx successfully.
fax.media.processing.started Telnyx has received the fax and is generating the digital PDF file.
fax.received The PDF has been generated and the file is ready to be downloaded.
fax.failed Transmission of the fax failed. Check the <code>failure_reason</code> for more details.

Fax has begun transmitting to Telnyx

Copy
Copied
{
  "data": {
    "event_type": "fax.receiving.started",
    "id": "bc004786-f166-4dd3-8c5d-737990b501bc",
    "occurred_at": "2020-08-27T16:33:29.684247Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "9fbc3f0d-5495-42af-9a4e-c57a235d9182",
      "from": "+16132484872",
      "status": "receiving",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Fax transmission is complete and Telnyx is converting to PDF

Copy
Copied
{
  "data": {
    "event_type": "fax.media.processing.started",
    "id": "35e33b02-6365-47d0-93b7-3bfec97c467e",
    "occurred_at": "2020-08-27T16:33:33.175396Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "status": "media.processing",
      "page_count": 2,
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

PDF has been generated and is ready for download

The media_url field contains a signed AWS link to a PDF of the received fax. This URL is valid for 10 minutes before the file is no longer accessible so be sure to download the file if you wish to keep it!

Copy
Copied
{
  "data": {
    "event_type": "fax.received",
    "id": "4844b70c-3c6c-4c3a-ba2e-e4c785f02d24",
    "occurred_at": "2020-08-27T16:33:36.843054Z",
    "payload": {
      "call_duration_secs": 50,
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "media_url": "https://s3.amazonaws.com/faxes-prod/19a75cea-02c6-4b9a-84fa-c9bc8341feb8/f72eebbe-f9b6-4f0f-b652-03e742e110d5.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASDC5E2MJIX77C6J7%2F20200827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200827T163336Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=eef2716f51dcd13d3f8a070bbaf1f88dfed0d4fab901337a6316529dc9a3374a",
      "page_count": 2,
      "partial_content": false,
      "status": "received",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Uh oh, something has gone wrong and the fax failed

Inbound faxes can fail for a variety of reasons. Some of the most common reasons are that the sending party hung up before the fax was finished transmitting or didn't send anything at all.

Copy
Copied
{
  "data": {
    "event_type": "fax.failed",
    "id": "1a7405a6-696c-4369-a0b1-168e4bb7e22c",
    "occurred_at": "2020-08-27T16:17:51.844250Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "failure_reason": "sender_call_dropped",
      "fax_id": "181533f3-b0b8-4bcd-ab01-b33cd8698508",
      "from": "+16617480240",
      "status": "failed",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

PHP

Part 1: Account Configuration

To get started using Programmable Fax with Telnyx, you will be required to make an account and attain the following items. A guide on how to set this up can be found at our Quickstart

You will ultimately need the following configured:

Do note, to recieve updates and status of your faxes (both inbound and outbound), you will need to setup a Webhook in the Telnyx Fax Application. This is where we will be sending you all information regarding the fax. For more information on this, you can scroll down to "Part 3: Recieving Faxes" section.

After your account is configured, take note of the following items that you will need to send your specified faxes programmatically.

That's it from the portal perspective! With the 3 pieces of information from above we are ready to start sending and recieving faxes with Telnyx!

Part 2: Sending Faxes

Sending outbound faxes requires:

  • A To number (Destination)
  • A From number (Generally the number you have procured from above)
  • A public facing URL which points to the document you are intending to send, in PDF format.

The code to initiate a fax sendoff would be as follows:

Copy
Copied
<?php
require_once __DIR__.'/vendor/autoload.php';

\Telnyx\Telnyx::setApiKey('YOUR_API_KEY');

$your_telnyx_number = 'YOUR_FROM_NUMBER';
$destination_number = 'YOUR_DESTINATION_NUMBER';
$connection_id = 'YOUR_CONNECTIONID';
$media_url = 'YOUR_MEDIA_URL';

$new_fax = \Telnyx\Message::Create(['from' => $your_telnyx_number, 'to' => $destination_number, 'connection_id' => $connection_id, 'media_url' => $media_url]);

Note: After pasting the above content, Kindly check and remove any new line added

A successful example JSON response to the request will look like:

Copy
Copied
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "direction": "outbound",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Part 3: Recieving Faxes

In order to recieve faxes, you will need to setup a webhook mentioned earlier.

In order for the webhooks in this tutorial to work, Telnyx must be able to send your web application an HTTP request over the Internet. That means your application needs to have a URL or IP address that Telnyx can reach. Telnyx sends webhooks to the URL or IP address to notify your application of incoming faxes.

For the purpose of this tutorial, we're using ngrok, a popular tunneling tool used to expose a locally running application to the internet. ngrok gives you a public URL for a local port on your development machine, which you can use to configure your Telnyx webhooks as described above.

Download and install ngrok, then use it at the command line to create a tunnel to whatever port your web application is running on. For example, this command will create a public URL for a web application listening on port 3000.

Copy
Copied
ngrok http 3000

Note: After pasting the above content, Kindly check and remove any new line added

After executing that command, you will see that ngrok has given your application a public URL that you can use in your webhook connection configuration in the Telnyx Mission Control Portal.

TwiML Twilio Telnyx Conference Flow

Grab your ngrok public URL and head back to the Programmable Fax Application you configured earlier. Now in the field under "Send a webhook to the URL" enter your new ngrok URL from either of the "Forwarding" URLs ngrok provided us with depending on if you want to use HTTP or HTTPS.

You're now all set up to receive webhooks for events related to inbound faxes. If you use the same Programmable Fax Application for sending faxes, you will receive events to the same ngrok URL you just created.

Example Webhooks

If you have set everything up correctly, any time an inbound fax is received you can expect to receive the following webhooks:

Webhook Name Description
fax.receiving.started The fax has begun transmitting to Telnyx successfully.
fax.media.processing.started Telnyx has received the fax and is generating the digital PDF file.
fax.received The PDF has been generated and the file is ready to be downloaded.
fax.failed Transmission of the fax failed. Check the <code>failure_reason</code> for more details.

Fax has begun transmitting to Telnyx

Copy
Copied
{
  "data": {
    "event_type": "fax.receiving.started",
    "id": "bc004786-f166-4dd3-8c5d-737990b501bc",
    "occurred_at": "2020-08-27T16:33:29.684247Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "9fbc3f0d-5495-42af-9a4e-c57a235d9182",
      "from": "+16132484872",
      "status": "receiving",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Fax transmission is complete and Telnyx is converting to PDF

Copy
Copied
{
  "data": {
    "event_type": "fax.media.processing.started",
    "id": "35e33b02-6365-47d0-93b7-3bfec97c467e",
    "occurred_at": "2020-08-27T16:33:33.175396Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "status": "media.processing",
      "page_count": 2,
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

PDF has been generated and is ready for download

The media_url field contains a signed AWS link to a PDF of the received fax. This URL is valid for 10 minutes before the file is no longer accessible so be sure to download the file if you wish to keep it!

Copy
Copied
{
  "data": {
    "event_type": "fax.received",
    "id": "4844b70c-3c6c-4c3a-ba2e-e4c785f02d24",
    "occurred_at": "2020-08-27T16:33:36.843054Z",
    "payload": {
      "call_duration_secs": 50,
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "media_url": "https://s3.amazonaws.com/faxes-prod/19a75cea-02c6-4b9a-84fa-c9bc8341feb8/f72eebbe-f9b6-4f0f-b652-03e742e110d5.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASDC5E2MJIX77C6J7%2F20200827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200827T163336Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=eef2716f51dcd13d3f8a070bbaf1f88dfed0d4fab901337a6316529dc9a3374a",
      "page_count": 2,
      "partial_content": false,
      "status": "received",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Uh oh, something has gone wrong and the fax failed

Inbound faxes can fail for a variety of reasons. Some of the most common reasons are that the sending party hung up before the fax was finished transmitting or didn't send anything at all.

Copy
Copied
{
  "data": {
    "event_type": "fax.failed",
    "id": "1a7405a6-696c-4369-a0b1-168e4bb7e22c",
    "occurred_at": "2020-08-27T16:17:51.844250Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "failure_reason": "sender_call_dropped",
      "fax_id": "181533f3-b0b8-4bcd-ab01-b33cd8698508",
      "from": "+16617480240",
      "status": "failed",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Node

Part 1: Account Configuration

To get started using Programmable Fax with Telnyx, you will be required to make an account and attain the following items. A guide on how to set this up can be found at our Quickstart

You will ultimately need the following configured:

Do note, to recieve updates and status of your faxes (both inbound and outbound), you will need to setup a Webhook in the Telnyx Fax Application. This is where we will be sending you all information regarding the fax. For more information on this, you can scroll down to "Part 3: Recieving Faxes" section.

After your account is configured, take note of the following items that you will need to send your specified faxes programmatically.

That's it from the portal perspective! With the 3 pieces of information from above we are ready to start sending and recieving faxes with Telnyx!

Part 2: Sending Faxes

Sending outbound faxes requires:

  • A To number (Destination)
  • A From number (Generally the number you have procured from above)
  • A public facing URL which points to the document you are intending to send, in PDF format.

The code to initiate a fax sendoff would be as follows:

Copy
Copied
var telnyx = require('telnyx')('YOUR_API_KEY');

telnyx.faxes.create(
 {
   'from': 'YOUR_FROM_NUMBER',
   'to': 'YOUR_DESTINATION_NUMBER',
   'connection_id': 'YOUR_FAX_APP_ID'
   'media_url': 'YOUR_MEDIA_URL'
 },
 function(err, response) {
   // asynchronously called
   console.log(response);
 }
);

Note: After pasting the above content, Kindly check and remove any new line added

A successful example JSON response to the request will look like:

Copy
Copied
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "direction": "outbound",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Part 3: Recieving Faxes

In order to recieve faxes, you will need to setup a webhook mentioned earlier.

In order for the webhooks in this tutorial to work, Telnyx must be able to send your web application an HTTP request over the Internet. That means your application needs to have a URL or IP address that Telnyx can reach. Telnyx sends webhooks to the URL or IP address to notify your application of incoming faxes.

For the purpose of this tutorial, we're using ngrok, a popular tunneling tool used to expose a locally running application to the internet. ngrok gives you a public URL for a local port on your development machine, which you can use to configure your Telnyx webhooks as described above.

Download and install ngrok, then use it at the command line to create a tunnel to whatever port your web application is running on. For example, this command will create a public URL for a web application listening on port 3000.

Copy
Copied
ngrok http 3000

Note: After pasting the above content, Kindly check and remove any new line added

After executing that command, you will see that ngrok has given your application a public URL that you can use in your webhook connection configuration in the Telnyx Mission Control Portal.

TwiML Twilio Telnyx Conference Flow

Grab your ngrok public URL and head back to the Programmable Fax Application you configured earlier. Now in the field under "Send a webhook to the URL" enter your new ngrok URL from either of the "Forwarding" URLs ngrok provided us with depending on if you want to use HTTP or HTTPS.

You're now all set up to receive webhooks for events related to inbound faxes. If you use the same Programmable Fax Application for sending faxes, you will receive events to the same ngrok URL you just created.

Example Webhooks

If you have set everything up correctly, any time an inbound fax is received you can expect to receive the following webhooks:

Webhook Name Description
fax.receiving.started The fax has begun transmitting to Telnyx successfully.
fax.media.processing.started Telnyx has received the fax and is generating the digital PDF file.
fax.received The PDF has been generated and the file is ready to be downloaded.
fax.failed Transmission of the fax failed. Check the <code>failure_reason</code> for more details.

Fax has begun transmitting to Telnyx

Copy
Copied
{
  "data": {
    "event_type": "fax.receiving.started",
    "id": "bc004786-f166-4dd3-8c5d-737990b501bc",
    "occurred_at": "2020-08-27T16:33:29.684247Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "9fbc3f0d-5495-42af-9a4e-c57a235d9182",
      "from": "+16132484872",
      "status": "receiving",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Fax transmission is complete and Telnyx is converting to PDF

Copy
Copied
{
  "data": {
    "event_type": "fax.media.processing.started",
    "id": "35e33b02-6365-47d0-93b7-3bfec97c467e",
    "occurred_at": "2020-08-27T16:33:33.175396Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "status": "media.processing",
      "page_count": 2,
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

PDF has been generated and is ready for download

The media_url field contains a signed AWS link to a PDF of the received fax. This URL is valid for 10 minutes before the file is no longer accessible so be sure to download the file if you wish to keep it!

Copy
Copied
{
  "data": {
    "event_type": "fax.received",
    "id": "4844b70c-3c6c-4c3a-ba2e-e4c785f02d24",
    "occurred_at": "2020-08-27T16:33:36.843054Z",
    "payload": {
      "call_duration_secs": 50,
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "media_url": "https://s3.amazonaws.com/faxes-prod/19a75cea-02c6-4b9a-84fa-c9bc8341feb8/f72eebbe-f9b6-4f0f-b652-03e742e110d5.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASDC5E2MJIX77C6J7%2F20200827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200827T163336Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=eef2716f51dcd13d3f8a070bbaf1f88dfed0d4fab901337a6316529dc9a3374a",
      "page_count": 2,
      "partial_content": false,
      "status": "received",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Uh oh, something has gone wrong and the fax failed

Inbound faxes can fail for a variety of reasons. Some of the most common reasons are that the sending party hung up before the fax was finished transmitting or didn't send anything at all.

Copy
Copied
{
  "data": {
    "event_type": "fax.failed",
    "id": "1a7405a6-696c-4369-a0b1-168e4bb7e22c",
    "occurred_at": "2020-08-27T16:17:51.844250Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "failure_reason": "sender_call_dropped",
      "fax_id": "181533f3-b0b8-4bcd-ab01-b33cd8698508",
      "from": "+16617480240",
      "status": "failed",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Java

Part 1: Account Configuration

To get started using Programmable Fax with Telnyx, you will be required to make an account and attain the following items. A guide on how to set this up can be found at our Quickstart

You will ultimately need the following configured:

Do note, to recieve updates and status of your faxes (both inbound and outbound), you will need to setup a Webhook in the Telnyx Fax Application. This is where we will be sending you all information regarding the fax. For more information on this, you can scroll down to "Part 3: Recieving Faxes" section.

After your account is configured, take note of the following items that you will need to send your specified faxes programmatically.

That's it from the portal perspective! With the 3 pieces of information from above we are ready to start sending and recieving faxes with Telnyx!

Part 2: Sending Faxes

Sending outbound faxes requires:

  • A To number (Destination)
  • A From number (Generally the number you have procured from above)
  • A public facing URL which points to the document you are intending to send, in PDF format.

The code to initiate a fax sendoff would be as follows:

Copy
Copied
curl -X POST https://api.telnyx.com/v2/faxes \
--data-urlencode "media_url=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" \
--data-urlencode "connection_id=YOUR_FAX_APP_ID" \
--data-urlencode "to=YOUR_DESTINATION_NUMBER" \
--data-urlencode "from=YOUR_FROM_NUMBER" \
--header "Authorization: Bearer API "YOUR_API_KEY"

Note: After pasting the above content, Kindly check and remove any new line added

A successful example JSON response to the request will look like:

Copy
Copied
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "direction": "outbound",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Part 3: Recieving Faxes

In order to recieve faxes, you will need to setup a webhook mentioned earlier.

In order for the webhooks in this tutorial to work, Telnyx must be able to send your web application an HTTP request over the Internet. That means your application needs to have a URL or IP address that Telnyx can reach. Telnyx sends webhooks to the URL or IP address to notify your application of incoming faxes.

For the purpose of this tutorial, we're using ngrok, a popular tunneling tool used to expose a locally running application to the internet. ngrok gives you a public URL for a local port on your development machine, which you can use to configure your Telnyx webhooks as described above.

Download and install ngrok, then use it at the command line to create a tunnel to whatever port your web application is running on. For example, this command will create a public URL for a web application listening on port 3000.

Copy
Copied
ngrok http 3000

Note: After pasting the above content, Kindly check and remove any new line added

After executing that command, you will see that ngrok has given your application a public URL that you can use in your webhook connection configuration in the Telnyx Mission Control Portal.

TwiML Twilio Telnyx Conference Flow

Grab your ngrok public URL and head back to the Programmable Fax Application you configured earlier. Now in the field under "Send a webhook to the URL" enter your new ngrok URL from either of the "Forwarding" URLs ngrok provided us with depending on if you want to use HTTP or HTTPS.

You're now all set up to receive webhooks for events related to inbound faxes. If you use the same Programmable Fax Application for sending faxes, you will receive events to the same ngrok URL you just created.

Example Webhooks

If you have set everything up correctly, any time an inbound fax is received you can expect to receive the following webhooks:

Webhook Name Description
fax.receiving.started The fax has begun transmitting to Telnyx successfully.
fax.media.processing.started Telnyx has received the fax and is generating the digital PDF file.
fax.received The PDF has been generated and the file is ready to be downloaded.
fax.failed Transmission of the fax failed. Check the <code>failure_reason</code> for more details.

Fax has begun transmitting to Telnyx

Copy
Copied
{
  "data": {
    "event_type": "fax.receiving.started",
    "id": "bc004786-f166-4dd3-8c5d-737990b501bc",
    "occurred_at": "2020-08-27T16:33:29.684247Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "9fbc3f0d-5495-42af-9a4e-c57a235d9182",
      "from": "+16132484872",
      "status": "receiving",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Fax transmission is complete and Telnyx is converting to PDF

Copy
Copied
{
  "data": {
    "event_type": "fax.media.processing.started",
    "id": "35e33b02-6365-47d0-93b7-3bfec97c467e",
    "occurred_at": "2020-08-27T16:33:33.175396Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "status": "media.processing",
      "page_count": 2,
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

PDF has been generated and is ready for download

The media_url field contains a signed AWS link to a PDF of the received fax. This URL is valid for 10 minutes before the file is no longer accessible so be sure to download the file if you wish to keep it!

Copy
Copied
{
  "data": {
    "event_type": "fax.received",
    "id": "4844b70c-3c6c-4c3a-ba2e-e4c785f02d24",
    "occurred_at": "2020-08-27T16:33:36.843054Z",
    "payload": {
      "call_duration_secs": 50,
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "media_url": "https://s3.amazonaws.com/faxes-prod/19a75cea-02c6-4b9a-84fa-c9bc8341feb8/f72eebbe-f9b6-4f0f-b652-03e742e110d5.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASDC5E2MJIX77C6J7%2F20200827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200827T163336Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=eef2716f51dcd13d3f8a070bbaf1f88dfed0d4fab901337a6316529dc9a3374a",
      "page_count": 2,
      "partial_content": false,
      "status": "received",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Uh oh, something has gone wrong and the fax failed

Inbound faxes can fail for a variety of reasons. Some of the most common reasons are that the sending party hung up before the fax was finished transmitting or didn't send anything at all.

Copy
Copied
{
  "data": {
    "event_type": "fax.failed",
    "id": "1a7405a6-696c-4369-a0b1-168e4bb7e22c",
    "occurred_at": "2020-08-27T16:17:51.844250Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "failure_reason": "sender_call_dropped",
      "fax_id": "181533f3-b0b8-4bcd-ab01-b33cd8698508",
      "from": "+16617480240",
      "status": "failed",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

.NET

Part 1: Account Configuration

To get started using Programmable Fax with Telnyx, you will be required to make an account and attain the following items. A guide on how to set this up can be found at our Quickstart

You will ultimately need the following configured:

Do note, to recieve updates and status of your faxes (both inbound and outbound), you will need to setup a Webhook in the Telnyx Fax Application. This is where we will be sending you all information regarding the fax. For more information on this, you can scroll down to "Part 3: Recieving Faxes" section.

After your account is configured, take note of the following items that you will need to send your specified faxes programmatically.

That's it from the portal perspective! With the 3 pieces of information from above we are ready to start sending and recieving faxes with Telnyx!

Part 2: Sending Faxes

Sending outbound faxes requires:

  • A To number (Destination)
  • A From number (Generally the number you have procured from above)
  • A public facing URL which points to the document you are intending to send, in PDF format.

Follow the steps below to send Fax messages with dotnet core v3.1+

  1. Using the dotnet CLI create a new console application and change directories to the newly created folder. Then add the Telnyx.net package.
Copy
Copied
$ dotnet new console --output send-fax
$ cd send-fax
$ dotnet add package Telnyx.net

Note: After pasting the above content, Kindly check and remove any new line added

  1. Open the 'Program.cs' file created for you in the directory. It should look something like the code below:
Copy
Copied
using System;

namespace send_sms
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

  1. Tell the application to use Telnyx.net by adding: using Telnyx; before the namespace
  2. In order to use the Asynchronous methods, we need to modify our Main method to return a Task and make it async. 4.1 static void Main(string[] args) should be static async Task Main(string[] args) 4.2 Add using System.Threading.Tasks; before the namespace`

A successful example JSON response to the request will look like:

Copy
Copied
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "direction": "outbound",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Part 3: Recieving Faxes

In order to recieve faxes, you will need to setup a webhook mentioned earlier.

In order for the webhooks in this tutorial to work, Telnyx must be able to send your web application an HTTP request over the Internet. That means your application needs to have a URL or IP address that Telnyx can reach. Telnyx sends webhooks to the URL or IP address to notify your application of incoming faxes.

For the purpose of this tutorial, we're using ngrok, a popular tunneling tool used to expose a locally running application to the internet. ngrok gives you a public URL for a local port on your development machine, which you can use to configure your Telnyx webhooks as described above.

Download and install ngrok, then use it at the command line to create a tunnel to whatever port your web application is running on. For example, this command will create a public URL for a web application listening on port 3000.

Copy
Copied
ngrok http 3000

Note: After pasting the above content, Kindly check and remove any new line added

After executing that command, you will see that ngrok has given your application a public URL that you can use in your webhook connection configuration in the Telnyx Mission Control Portal.

TwiML Twilio Telnyx Conference Flow

Grab your ngrok public URL and head back to the Programmable Fax Application you configured earlier. Now in the field under "Send a webhook to the URL" enter your new ngrok URL from either of the "Forwarding" URLs ngrok provided us with depending on if you want to use HTTP or HTTPS.

You're now all set up to receive webhooks for events related to inbound faxes. If you use the same Programmable Fax Application for sending faxes, you will receive events to the same ngrok URL you just created.

Example Webhooks

If you have set everything up correctly, any time an inbound fax is received you can expect to receive the following webhooks:

Webhook Name Description
fax.receiving.started The fax has begun transmitting to Telnyx successfully.
fax.media.processing.started Telnyx has received the fax and is generating the digital PDF file.
fax.received The PDF has been generated and the file is ready to be downloaded.
fax.failed Transmission of the fax failed. Check the <code>failure_reason</code> for more details.

Fax has begun transmitting to Telnyx

Copy
Copied
{
  "data": {
    "event_type": "fax.receiving.started",
    "id": "bc004786-f166-4dd3-8c5d-737990b501bc",
    "occurred_at": "2020-08-27T16:33:29.684247Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "9fbc3f0d-5495-42af-9a4e-c57a235d9182",
      "from": "+16132484872",
      "status": "receiving",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Fax transmission is complete and Telnyx is converting to PDF

Copy
Copied
{
  "data": {
    "event_type": "fax.media.processing.started",
    "id": "35e33b02-6365-47d0-93b7-3bfec97c467e",
    "occurred_at": "2020-08-27T16:33:33.175396Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "status": "media.processing",
      "page_count": 2,
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

PDF has been generated and is ready for download

The media_url field contains a signed AWS link to a PDF of the received fax. This URL is valid for 10 minutes before the file is no longer accessible so be sure to download the file if you wish to keep it!

Copy
Copied
{
  "data": {
    "event_type": "fax.received",
    "id": "4844b70c-3c6c-4c3a-ba2e-e4c785f02d24",
    "occurred_at": "2020-08-27T16:33:36.843054Z",
    "payload": {
      "call_duration_secs": 50,
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "media_url": "https://s3.amazonaws.com/faxes-prod/19a75cea-02c6-4b9a-84fa-c9bc8341feb8/f72eebbe-f9b6-4f0f-b652-03e742e110d5.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASDC5E2MJIX77C6J7%2F20200827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200827T163336Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=eef2716f51dcd13d3f8a070bbaf1f88dfed0d4fab901337a6316529dc9a3374a",
      "page_count": 2,
      "partial_content": false,
      "status": "received",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Uh oh, something has gone wrong and the fax failed

Inbound faxes can fail for a variety of reasons. Some of the most common reasons are that the sending party hung up before the fax was finished transmitting or didn't send anything at all.

Copy
Copied
{
  "data": {
    "event_type": "fax.failed",
    "id": "1a7405a6-696c-4369-a0b1-168e4bb7e22c",
    "occurred_at": "2020-08-27T16:17:51.844250Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "failure_reason": "sender_call_dropped",
      "fax_id": "181533f3-b0b8-4bcd-ab01-b33cd8698508",
      "from": "+16617480240",
      "status": "failed",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Ruby

Part 1: Account Configuration

To get started using Programmable Fax with Telnyx, you will be required to make an account and attain the following items. A guide on how to set this up can be found at our Quickstart

You will ultimately need the following configured:

Do note, to recieve updates and status of your faxes (both inbound and outbound), you will need to setup a Webhook in the Telnyx Fax Application. This is where we will be sending you all information regarding the fax. For more information on this, you can scroll down to "Part 3: Recieving Faxes" section.

After your account is configured, take note of the following items that you will need to send your specified faxes programmatically.

That's it from the portal perspective! With the 3 pieces of information from above we are ready to start sending and recieving faxes with Telnyx!

Part 2: Sending Faxes

Sending outbound faxes requires:

  • A To number (Destination)
  • A From number (Generally the number you have procured from above)
  • A public facing URL which points to the document you are intending to send, in PDF format.

The code to initiate a fax sendoff would be as follows:

Copy
Copied
curl -X POST https://api.telnyx.com/v2/faxes \
--data-urlencode "media_url=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" \
--data-urlencode "connection_id=YOUR_FAX_APP_ID" \
--data-urlencode "to=YOUR_DESTINATION_NUMBER" \
--data-urlencode "from=YOUR_FROM_NUMBER" \
--header "Authorization: Bearer API "YOUR_API_KEY"

Note: After pasting the above content, Kindly check and remove any new line added

A successful example JSON response to the request will look like:

Copy
Copied
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "direction": "outbound",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Part 3: Recieving Faxes

In order to recieve faxes, you will need to setup a webhook mentioned earlier.

In order for the webhooks in this tutorial to work, Telnyx must be able to send your web application an HTTP request over the Internet. That means your application needs to have a URL or IP address that Telnyx can reach. Telnyx sends webhooks to the URL or IP address to notify your application of incoming faxes.

For the purpose of this tutorial, we're using ngrok, a popular tunneling tool used to expose a locally running application to the internet. ngrok gives you a public URL for a local port on your development machine, which you can use to configure your Telnyx webhooks as described above.

Download and install ngrok, then use it at the command line to create a tunnel to whatever port your web application is running on. For example, this command will create a public URL for a web application listening on port 3000.

Copy
Copied
ngrok http 3000

Note: After pasting the above content, Kindly check and remove any new line added

After executing that command, you will see that ngrok has given your application a public URL that you can use in your webhook connection configuration in the Telnyx Mission Control Portal.

TwiML Twilio Telnyx Conference Flow

Grab your ngrok public URL and head back to the Programmable Fax Application you configured earlier. Now in the field under "Send a webhook to the URL" enter your new ngrok URL from either of the "Forwarding" URLs ngrok provided us with depending on if you want to use HTTP or HTTPS.

You're now all set up to receive webhooks for events related to inbound faxes. If you use the same Programmable Fax Application for sending faxes, you will receive events to the same ngrok URL you just created.

Example Webhooks

If you have set everything up correctly, any time an inbound fax is received you can expect to receive the following webhooks:

Webhook Name Description
fax.receiving.started The fax has begun transmitting to Telnyx successfully.
fax.media.processing.started Telnyx has received the fax and is generating the digital PDF file.
fax.received The PDF has been generated and the file is ready to be downloaded.
fax.failed Transmission of the fax failed. Check the <code>failure_reason</code> for more details.

Fax has begun transmitting to Telnyx

Copy
Copied
{
  "data": {
    "event_type": "fax.receiving.started",
    "id": "bc004786-f166-4dd3-8c5d-737990b501bc",
    "occurred_at": "2020-08-27T16:33:29.684247Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "9fbc3f0d-5495-42af-9a4e-c57a235d9182",
      "from": "+16132484872",
      "status": "receiving",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Fax transmission is complete and Telnyx is converting to PDF

Copy
Copied
{
  "data": {
    "event_type": "fax.media.processing.started",
    "id": "35e33b02-6365-47d0-93b7-3bfec97c467e",
    "occurred_at": "2020-08-27T16:33:33.175396Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "status": "media.processing",
      "page_count": 2,
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

PDF has been generated and is ready for download

The media_url field contains a signed AWS link to a PDF of the received fax. This URL is valid for 10 minutes before the file is no longer accessible so be sure to download the file if you wish to keep it!

Copy
Copied
{
  "data": {
    "event_type": "fax.received",
    "id": "4844b70c-3c6c-4c3a-ba2e-e4c785f02d24",
    "occurred_at": "2020-08-27T16:33:36.843054Z",
    "payload": {
      "call_duration_secs": 50,
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "fax_id": "f72eebbe-f9b6-4f0f-b652-03e742e110d5",
      "from": "+16132484850",
      "media_url": "https://s3.amazonaws.com/faxes-prod/19a75cea-02c6-4b9a-84fa-c9bc8341feb8/f72eebbe-f9b6-4f0f-b652-03e742e110d5.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASDC5E2MJIX77C6J7%2F20200827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200827T163336Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=eef2716f51dcd13d3f8a070bbaf1f88dfed0d4fab901337a6316529dc9a3374a",
      "page_count": 2,
      "partial_content": false,
      "status": "received",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Uh oh, something has gone wrong and the fax failed

Inbound faxes can fail for a variety of reasons. Some of the most common reasons are that the sending party hung up before the fax was finished transmitting or didn't send anything at all.

Copy
Copied
{
  "data": {
    "event_type": "fax.failed",
    "id": "1a7405a6-696c-4369-a0b1-168e4bb7e22c",
    "occurred_at": "2020-08-27T16:17:51.844250Z",
    "payload": {
      "connection_id": "1447842681660114324",
      "direction": "inbound",
      "failure_reason": "sender_call_dropped",
      "fax_id": "181533f3-b0b8-4bcd-ab01-b33cd8698508",
      "from": "+16617480240",
      "status": "failed",
      "to": "+17733372863",
      "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://1a3097.ngrok.io/"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added