How to use Fax for Asterisk - Part 2

How to use Fax for Asterisk - Part 2

We send and receive faxes via the dialplan function FAXOPT and SendFax/ReceiveFax asterisk applications.

 

*CLI> core show application sendfax

  -= Info about application 'SendFAX' =-

[Synopsis]

Sends a specified TIFF/F file as a FAX.

[Description]

SendFAX(filename[&filename[&filename]][,options]):

 The SendFAX() application sends the specified TIFF/F file(s) as a FAX.

 The application arguments are:

    'd' - enables FAX debugging

    'f' - allow audio fallback FAX transfer on T.38 capable channels

    'z' - initiate a T.38 reinvite on the channel if the remote end does not

    's' - send progress Manager events (overrides statusevents setting in res_fa                                              x.conf)

 Use the FAXOPT function to specify session arguments prior to calling SendFAX()

 and use FAXOPT after SendFAX completes to query result status for the session.

 The SendFAX() application is provided by res_fax, which is a FAX technology agn                                              ostic module

 that utilizes FAX technology resource modules to complete a FAX transmission.

[Syntax]

Not available

[Arguments]

Not available

[See Also]

Not available

The FAXOPT dialplan function is used to set options to be used by SendFax or ReceiveFax and obtain the fax results afterwards.

To faxout, we can use callfile to dial the destination fax number and call SendFax in dialplan.

Sample.call

Channel:SIP/t38gateway/12345678

Callerid:"Test"<1111>

Maxretries:0

Waittime:45

Context:fax_context

Extension:ffa_faxout

Priority:1

Set:TIFF_2_SEND=sample.tiff

Set:TAGLINE=header_sample

Set:RECEIVER=12345678

Extensions.conf

[fax_context]

exten => ffa_faxout,1,NoOp(**** SENDING FAX ****)

exten => ffa_faxout,n,Wait(6)

exten => ffa_faxout,n,Set(FAXFILE=${TIFF_2_SEND})

; Set FAXOPTs

exten => ffa_faxout,n,NoOp(**** SETTING FAXOPT ****)

exten => ffa_faxout,n,Set(FAXOPT(ecm)=yes)

exten => ffa_faxout,n,Set(FAXOPT(headerinfo)=${TAGLINE})

exten => ffa_faxout,n,Set(FAXOPT(maxrate)=14400)

exten => ffa_faxout,n,Set(FAXOPT(minrate)=2400)

; Send the fax

exten => ffa_faxout,n,NoOp(**** SENDING FAX : ${FAXFILE} ****)

exten => ffa_faxout,n,SendFAX(/tmp/${FAXFILE},dfzs)

; Hangup! Print FAXOPTs

exten => h,1,NoOp(FAXOPT(ecm) : ${FAXOPT(ecm)})

exten => h,n,NoOp(FAXOPT(filename) : ${FAXOPT(filename)})

exten => h,n,NoOp(FAXOPT(headerinfo) : ${FAXOPT(headerinfo)})

exten => h,n,NoOp(FAXOPT(localstationid) : ${FAXOPT(localstationid)})

exten => h,n,NoOp(FAXOPT(maxrate) : ${FAXOPT(maxrate)})

exten => h,n,NoOp(FAXOPT(minrate) : ${FAXOPT(minrate)})

exten => h,n,NoOp(FAXOPT(pages) : ${FAXOPT(pages)})

exten => h,n,NoOp(FAXOPT(rate) : ${FAXOPT(rate)})

exten => h,n,NoOp(FAXOPT(remotestationid) : ${FAXOPT(remotestationid)})

exten => h,n,NoOp(FAXOPT(resolution) : ${FAXOPT(resolution)})

exten => h,n,NoOp(FAXOPT(status) : ${FAXOPT(status)})

exten => h,n,NoOp(FAXOPT(statusstr) : ${FAXOPT(statusstr)})

exten => h,n,NoOp(FAXOPT(error) : ${FAXOPT(error)})

exten => h,n,NoOp(DNIS: ${RECEIVER})

exten => h,n,System(write_log.sh ${RECEIVER} ${FAXOPT(filename)} ${FAXOPT(status)} ${FAXOPT(statusstr)}  ${FAXOPT(error)})

Points to note.

l It is not recommended to edit the callfile in /var/spool/asterisk/outgoing as it might be processed by asterisk in the middle of creation.  A better approach is to create the callfile somewhere else and 'mv' to the outgoing directory.

l The resolution of tiff is important.  We can enforce the correct values by specifying them in the gs command.

n gs -q -dNOPAUSE -dBATCH -sDEVICE=tiffg4 -sPAPERSIZE=a4 -g1680x2285 -sOutputFile=sample.tiff sample.pdf

n We can verify our fax document using 'tiffinfo sample.tiff'

n If we receive 'res_fax_digium.c: FAX handle 0: failed to queue document', it is likely due to mis-formatted tiff.

l Utf8 tagline is currently not supported.

l We can pass certain variables from callfile to our dialplan, eg the destination number, for generating fax status reports.  The fax status is obtained from ${FAXOPT(status)}

l The write_log.sh is a simple shell script that merely logs whatever number we faxed with the fax status.  Alternatively, we could use AGI to insert the data to database for billing purpose.

l To enable t38 fax, we have to set 't38pt_udptl=yes' in sip.conf 

n If we receive error 'Audio FAX not allowed on channel', it is likely an issue with the t38_udptl value.

l To monitor fax progress, we can set debug on as below.

n *CLI> fax set debug on

To send faxes simultaneously (assuming that we purchased enough channels from Digium), we could put multiple callfiles in /var/spool/asterisk/outgoing and monitor this folder to add more callfiles when appropriate. 

 

In following parts, I would show how to control the maximum number of concurrent fax calls and automate fax retry.