asterisk/doc/advice_of_charge.txt

================
Advice of Charge
================

Written by: David Vossel
Initial version: 04-19-2010
Email: dvossel@digium.com

This document is designed to give an overview of how to configure and
generate Advice of Charge along with a detailed explanation of how each
option works.

--------------------------------------
|          READ THIS FIRST           |
--------------------------------------
PLEASE REPORT ANY ISSUES ENCOUNTERED WHILE USING AOC.  This feature
has had very little community feedback so far.  If you are using this
feature please share with us any problems you are having and any
improvements that could make this feature more useful.  Thank you!

--------------------------------------
|           Terminology              |
--------------------------------------
AOC: Advice of Charge

AOC-S: Advice of Charge message sent at the beginning of a call during
call setup.  This message contains a list of rates associated with the
call.

AOC-D: Advice of Charge message sent during the call.  This message
is typically used to update the endpoint with the current call charge.

AOC-E: Advice of Charge message sent at the end of a call.  This
message is used to indicate to the endpoint the final call charge.

AMI: Asterisk Manager Interface.  This interface is used to generate
AOC messages and listen for AOC events.

--------------------------------------
|           AOC in chan_dahdi        |
--------------------------------------
----- LibPRI Support:
ETSI, or euroisdn, is the only switchtype that LibPRI currently supports
for AOC.

----- Enable AOC Pass-through in chan_dahdi
To enable AOC pass-through between the ISDN and Asterisk use the
'aoc_enable' config option.  This option allows for any combination
of AOC-S, AOC-D, and AOC-E to be enabled or disabled.

For example:
aoc_enable=s,d,e ; enables pass-through of AOC-S, AOC-D, and AOC-E

aoc_enable=s,d   ; enables pass-through of AOC-S and AOC-D. Rejects
                 ; AOC-E and AOC-E request messages

Since AOC messages are often transported on facility messages, the
'facilityenable' option must be enabled as well to fully support AOC
pass-through.

----- Handling AOC-E in chan_dahdi
Whenever a dahdi channel receives an AOC-E message from Asterisk, it
stores that message to deliver it at the appropriate time during call
termination. This means that if two AOC-E messages are received on the
same call, the last one will override the first one and only one AOC-E
message will be sent during call termination.

There are some tricky situations involving the final AOC-E message. During
a bridged call, if the endpoint receiving the AOC messages terminates
the call before the endpoint delivering the AOC does, the final AOC-E
message sent by the sending side during termination will never make it to
the receiving end because Asterisk will have already torn down that channel.
This is where the chan_dahdi.conf 'aoce_delayhangup' option comes into play.

By enabling 'aoce_delayhangup', anytime a hangup is initiated by the
ISDN side of an Asterisk channel, instead of hanging up the channel,
the channel sends a unique internal AOC-E termination request to its bridge
channel. This indicates it is about to hangup and wishes to receive the
final AOC-E message from the bridged channel before completely tearing
down.  If the bridged channel knows what to do with this AOC-E termination
request, it will do whatever is necessary to indicate to its endpoint that
the call is being terminated without actually hanging up the Asterisk channel.
This allows the final AOC-E message to come in and be sent across the bridge
while both channels are still up.  If the channel delaying its hangup for
the final AOC-E message times out, the call will be torn down just as it
normally would.  In chan_dahdi the timeout period is 1/2 the T305 timer
which by default is 15 seconds.

'aoce_delayhangup' currently only works when both bridged channels are
dahdi_channels. If a SIP channel receives an AOC-E termination request, it
just responds by immediately hanging up the channel.  Using this option when
bridged to any channel technology besides SIP or DAHDI will result in the
15 second timeout period before tearing down the call completely.

----- Requesting AOC services
AOC can be requested on a call by call basis using the DAHDI dialstring
option, A(). The A() option takes in 's', 'd', and 'e' parameters which
represent the three types of AOC messages, AOC-S, AOC-D, and AOC-E.  By using
this option Asterisk will indicate to the endpoint during call setup that it
wishes to receive the specified forms of AOC during the call.

Example Usage in extensions.conf
exten => 1111,1,Dial(DAHDI/g1/1112/A(s,d,e) ; requests AOC-S, AOC-D, and AOC-E on
                                          ; call setup
exten => 1111,1,Dial(DAHDI/g1/1112/A(d,e)  ; requests only AOC-D, and AOC-E on
                                          ; call setup

--------------------------------------
|          AOC in chan_sip           |
--------------------------------------
Asterisk supports a very basic way of sending AOC on a SIP channel to Snom
phones using an AOC specification designed by Snom.  This support is limited
to the sending of AOC-D and AOC-E pass-through messages.  No support for
AOC-E on call termination is present, so if the Snom endpoint receiving the
AOC messages from Asterisk terminates the call, the channel will be torn
down before the phone can receive the final AOC-E message.

To enable passthrough of AOC messages via the snom specification, use
the 'snom_aoc_enabled' option in sip.conf.

--------------------------------------
|   Generate AOC Messages via AMI    |
--------------------------------------
Asterisk supports a way to generate AOC messages on a channel via
the AMI action AOCMessage.  At the moment the AOCMessage action is limited
to AOC-D and AOC-E message generation.  There are some limitations
involved with delivering the final AOC-E message as well. The AOCMessage
action has its own detailed parameter documentation so this discussion will
focus on higher level use.  When generating AOC messages on a Dahdi channel
first make sure the appropriate chan_dahdi.conf options are enabled.  Without
enabling 'aoc_enable' correctly for pass-through the AOC messages will never
make it out the pri.  The same goes with SIP, the 'snom_aoc_enabled' option
must be configured before messages can successfully be set to the endpoint.

----- AOC-D Message Generation
AOC-D message generation can happen anytime throughout the call.  This
message type is very straight forward.

Example: AOCMessage action generating AOC-D currency message with Success
response.

Action: AOCMessage
Channel: DAHDI/i1/1111-1
MsgType: d
ChargeType: Currency
CurrencyAmount: 16
CurrencyName: USD
CurrencyMultiplier: OneThousandth
AOCBillingId: Normal
ActionID: 1234

Response: Success
ActionID: 1234
Message: AOC Message successfully queued on channel

----- AOC-E Message Generation
AOC-E messages are sent during call termination and represent the final charge
total for the call.  Since Asterisk call termination results in the channel
being destroyed, it is currently not possible for the AOCMessage AMI action to
be used to send the final AOC-E message on call hangup.  There is however a
work around for this issue that can be used for Dahdi channels.  By default
chan_dahdi saves any AOC-E message it receives from Asterisk during a call and
waits to deliver that message during call termination. If multiple AOC-E messages
are received from Asterisk on the same Dahdi channel, only the last message received
is stored for delivery.  This means that each new AOC-E message received on the
channel overrides the previous one.  Knowing this the final AOC-E message can be
continually updated on a Dahdi channel until call termination occurs allowing
the last update to be sent on hangup.  This method is only as accurate as the
intervals in which it is updated, but allows some form of AOC-E to be generated.

Example: AOCMessage action generating AOC-E unit message with Success response.

Action: AOCMessage
Channel: DAHDI/i1/1111-1
MsgType: e
ChargeType: Unit
UnitAmount(0): 111
UnitType(0): 6
UnitAmount(1): 222
UnitType(1): 5
UnitAmount(2): 333
UnitType(3): 4
UnitAmount(4): 444
AOCBillingId: Normal
ActionID: 1234

Response: Success
ActionID: 1234
Message: AOC Message successfully queued on channel