article

Introduction

A Go program to send fax from Telnyx phone number using Programmable Fax API.

Prerequisite

• Telnyx Account

• Telnyx Phone Number

• Code IDE or text Editor

• Go installed on your machine

Steps

Step 1: Telnyx Setup

You need to signup and acquire Telnyx Phone number, API key and Fax application ID for sending a fax.

• Sign up for Telnyx account and acquire phone number

  • Set up a developer account with Telnyx from https://telnyx.com/sign-up

    • After creating an account and signing in, you need to acquire a number for the application. Search for a number by selecting your preferred 'Region' or 'Area Code'.

    • Make sure that the number supports Fax feature(Very Important!) as it will be used by our application.

    • Keep the acquired phone number

• Acquire Telnyx API key

  • Go to the API Keys page and copy the API Key for the future steps. Incase there is no API Key, then create one.

You now should have Telnyx Phone number and API key

• Create Fax Application

  • Click Programmable Fax from the left vertical menu. It will open a section where you can create a Fax application

    

    • Click Add new App in the "Configure Your Fax Applications" section to create a new application.

    

    • Provide a contextual name to your application

    

    • For the webhook URL, go to webhook.site and copy the URL as shown below (do not copy from the address bar of browser)

    

    • Paste the copied URL in Telnyx portal

    

    • Click on save to finish the fax application creation.

    

• Acquire Fax Application ID

  • In the "Programmable Fax" window, look for your newly created application and edit it.

    

    • Copy the Fax Application ID and keep it for future use

    

You now should have Telnyx Phone number, API key and fax application id

• Assign outbound voice profile to your Fax application

  • To assign your phone number to your Fax application, go to your number and click on routing

    

    • In the opened popup, look for your fax application and select it.

    

    • Click Outbound Voice Profiles on the left vertical menu and click on "Add New Profile" button to create an outbound voice profile

    

    • Provide a contextual name and click "Create"

    

    • Clicking on "Create" button will open a new page where you need to add your fax application to the created outbound profile

    

    • Select your fax application and click on "Add Connection/Apps to profile" button

    

    

    • Your application is added to the outbound profile.

    

Step 2: Go code to send fax

To send a fax, you need to Telnyx phone number, API key and fax application id to your Go code

• Copy and paste the code in a file - Create a new file with extension .go and paste the below provided code

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
    "strings"
)

func main() {

    endpoint := "https://api.telnyx.com/v2/faxes"
    method := "POST"

    data := url.Values{}
    data.Set("media_url", "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf") //The URL of the PDF used for the fax's media
    data.Set("connection_id", "FAX_APP_ID") //Acquire from Fax app
    data.Set("to", "RECIPIENT_PHONE_NUMBER")
    data.Set("from", "YOUR_TELNYX_NUMBER")

    client := &http.Client{}

    req, err := http.NewRequest(method, endpoint, strings.NewReader(data.Encode()))

    if err != nil {
        fmt.Println(err)
        return
    }

    req.Header = http.Header{
        "Authorization": []string{"Bearer TELNYX_API_KEY"},
        "Content-Type":  []string{"application/x-www-form-urlencoded"},
    }

    res, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }

    body, err := ioutil.ReadAll(res.Body)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(string(body))
}

• Replace values - Replace following values in your code:

  • YOUR_TELNYX_NUMBER with acquired Telnyx phone number

  • TELNYX_API_KEY with acquired API key

  • RECIPIENT_PHONE_NUMBER with the number you want to send message to

  • FAX_APP_ID with acquired fax application id

• Run the code - To run the code, open terminal or command prompt and provide following command

go run file_name.go

On successfully sending the fax, the Programmable Fax API will respond with HTTP 202.

• Webhook responses

  • Once the request to send the fax has been successfullly received by Telnyx, you should begin receiving a series of webhooks to the URL that you specified in your Fax Application.
    The webhooks you should receive are:

• fax.queued

• fax.media.processed

• fax.sending.started

• fax.delivered

• fax.failed

Once you've received a fax.delivered webhook, your fax has been delivered to its destinaion!