☰
Navigation :

RTP Messages

Introduction

The N2SIP package delivers various “SIP applications” including SrpSipApp and LhoSipApp.

Collectively we refer to any one of these applications as an “SipApp”, which is the common SIP framework on top of which all of them is built.

The LhoSipApp is capable of playing both “local announcements” (using RTP) and “remote announcements” (using SIP messaging to redirect the call to a different application). The SrpSipApp supports only playing of “local announcements”.

To play a local announcement, the controlling SIP application sends and receives RTP-... messages across the IPC message bus to a local RtpApp application. For load-sharing purposes, the RtpApp application will typically be configured as a “repeat” application which executes more than once in order to use multiple processes.

The internal messages used between any “SipApp” and the RtpApp are:

RTP-ESTABLISH

The RTP-ESTABLISH message is sent by any of the SIP Applications to request the reservation of an RTP port (or pair of RTP ports when RTCP is used) and the establishment (perhaps partial) of an RTP stream relationship.

The RtpApp will assign a local port (or ports) and create an RTP instance to process the stream. The assignment and acceptance is confirmed with an RTP-ESTABLISHED, or declined using RTP-SHUTDOWN.

The RTP-ESTABLISH specifies the sender context, which identifies the initiating SipInstance requesting the assignment.

The establishment has two modes:

This applies when we are the UAS processing an inbound A-Leg INVITE using the “early offer” patterns 1 and 3 from “Table 1: Summary of SIP Usage of the Offer/Answer Model” from RFC 6337.

This half-accept mode also applies for the scenario where we are the UAC initiating a new call by sending an outbound A-Leg INVITE. In this case we know only our endpoint information, but we cannot start streaming until the far-end completes the establishment by providing an SDP answer.

The attributes of the RTP-ESTABLISH message are:

Field Type Description
stream_number Integer [Required] A sequence number for each RTP-ESTABLISH performed during a call.
First session per call is 1. This will be echoed back to disambiguate late/overlapping responses.
sip Object [Required] The SIP parameters for the message.
.call_id String [Required] The SIP Call ID. This is used for debug/tracing purposes only.
.sdp_content String The body of the SDP Offer from the SIP INVITE Request (for incall) or SIP INVITE Response (for outcall).
(Default = no SDP Offer has been received yet, we will construct the SDP Offer).

RTP-ESTABLISHED

The RTP-ESTABLISHED message is sent from the RtpApp back to the originating SipApp, and indicates that the RTP stream has been fully-or-partly established.

The message supports two modes:

This applies when we are the UAS processing an inbound A-Leg INVITE using the “early offer” patterns 1 and 3 from “Table 1: Summary of SIP Usage of the Offer/Answer Model” from RFC 6337.

In this case, the RTP relationship is defined at both ends, and the RTP App and is now ready to receive instructions to play and optionally collect audio and DTMF.

This applies when we are the UAS processing an inbound A-Leg INVITE using the “delay offer” (aka “late offer”) pattern 2 from “Table 1: Summary of SIP Usage of the Offer/Answer Model” from RFC 6337.

This half-established mode also applies for the scenario where we are the UAC initiating a new call by sending an outbound A-Leg INVITE.

In this case, the RTP is only half-established. The first RTP-PLAY message must provide the sdp_answer_content for us to parse in order to finalise the stream establishment.

Note that even in the case where the stream is fully-established, playing of silence packets does not begin until the first RTP-PLAY is received.

The attributes of the RTP-ESTABLISHED message are:

Field Type Description
stream_number Integer [Required] Echo of original value from preceding RTP-ESTABLISHED.
sip Object [Required] The SIP response parameters associated with the RTP stream.
.early_media_ok 0 / 1 [Required] Do we believe that SIP Early Media (RTP established via proceeding 1XX Response) can support RTP audio and PACUI?
rtp Object [Required] The SIP response parameters associated with the RTP stream for answer (early offer) or offer (delay offer) case.
.answer Object Used when the original received INVITE contains an early SDP offer, and the RtpApp is providing the SDP answer.
This supports patterns 1 and 3 from "Table 1: Summary of SIP Usage of the Offer/Answer Model" in RFC 6337.
The answer in this case includes exactly one audio stream descriptor, and at most one telephone-event descriptor.
In this case the RTP-ESTABLISHED indicates that the stream is ready for use.
.dtmf_inband 0 / 1 [Required] Is this RTP application intending to perform inband DTMF detection?
Should be set to 0 when .telephone_event_payload_type is present in the answer.
.rtp_local_ip IP Address [Required] The local IP address which the RtpApp has reserved for this stream.
.rtp_local_port Integer [Required] The local port number which the RtpApp has reserved for this stream.
.rtp_remote_ip IP Address [Required] The RTP remote IP to which we will send (and from which we expect to receive) packets.
.rtp_remote_port Integer [Required] The RTP remote UDP port to which we will send (and from which we expect to receive) packets.
.audio_payload_type Integer [Required] The audio payload type either static or dynamically negotiated by SDP for the audio in this RTP stream.
.audio_encoding_name PCMU / PCMA / AMR / AMR-WB [Required] Which codec to use for the audio in this RTP stream.
.audio_clock_rate Integer [Required] The clock rate to use for the audio in this RTP stream.
.audio_encoding_params String Optional SDP rtpmap.encoding-params for the audio in this RTP stream.
.audio_fmtp Array of String Optional array of SDP fmtp attributes negotiated for the stream.
(Default = no additional attributes).
.audio_sendonly 1 / 0 Did we negotiate for this stream to be sendonly?
(Default = the stream is bi-directional).
.telephone_event_payload_type Integer The payload type negotiated by SDP for the telephone events in this RTP stream.
Should not be present when .dtmf_inband = 1.
(Default = do not expect RTP telephone events).
.telephone_event_name String The negotiated telephone event name, e.g. telephone-event.
(Default = we do not offer to process RTP telephone events).
.telephone_event_clock_rate Integer [Required] The clock rate to use for the telephone events in this RTP stream.
.telephone_event_fmtp Array of String Optional array of SDP fmtp attributes negotiated for the telephone events.
(Default = no additional attributes).
.offer Object Used when the original received INVITE did not contain an SDP offer. The RtpApp is providing the SDP offer.
This is pattern 2 from "Table 1: Summary of SIP Usage of the Offer/Answer Model" in RFC 6337.
In this case the RTP-ESTABLISHED indicates that the stream is ready for use.
.rtp_local_ip IP Address [Required] The local IP address which the RtpApp has reserved for this stream.
.rtp_local_port Integer [Required] The local port number which the RtpApp has reserved for this stream.
.media Array [Required] Array of all offered media (audio) formats.
.audio_payload_type Integer [Required] The audio payload type either static or dynamically offered by SDP for the audio in this RTP stream.
.audio_encoding_name PCMU / PCMA / AMR / AMR-WB [Required] Which codec to use for the audio in this RTP stream.
.audio_clock_rate Integer [Required] The clock rate to use for the audio in this RTP stream.
.audio_encoding_params String Optional SDP rtpmap.encoding-params for the audio in this RTP stream.
.audio_fmtp Array of String Optional array of SDP fmtp attributes offered for the stream.
(Default = no additional attributes).
.events Array Array of all offered telephone-event detection formats.
(Default = the RTP App is not offering to detect RTP telephone events).
.telephone_event_payload_type Integer The payload type offered by SDP for the telephone events in this RTP stream.
Should not be present when .dtmf_inband = 1.
(Default = do not expect RTP telephone events).
.telephone_event_name telephone-event The offered telephone event encoding name, e.g. telephone-event.
(Default = do not expect RTP telephone events).
.telephone_event_clock_rate Integer [Required] The clock rate to use for the telephone events in this RTP stream.
.telephone_event_fmtp Array of String Optional array of SDP fmtp attributes offered for the telephone events.
(Default = no additional attributes).
.audio_sendonly 1 / 0 Indication of whether the offered session would be bi-directional (sendrecv) or uni-directional (sendonly).
(Default = the stream is bi-directional).

RTP-HANGUP

The RTP-HANGUP message is sent by any of the SIP Applications to indicate that the RTP stream is no longer required, as the SIP session is being ended.

This is a final message. No further messages are valid after this message is sent.

The RTP-HANGUP message has no attributes.

RTP-PLAY

The RTP-PLAY message is sent by any of the SIP Applications to request that an RTP stream begin pushing audio packets on the previously established RTP stream.

This may also involve digit collection. This will continue until either of the “natural” end conditions has occurred.

When one of these occurs, an RTP-PLAYED event is sent. Note that the case when insufficient digits are entered is still considered to be a successful interaction, even though the service logic will typically consider this to be a “soft error”.

Alternative, the following message can be used to end an RTP-PLAY request.

The attributes of the RTP-PLAY message are:

Field Type Description
stream_number Integer [Required] The sequence number from the most recent RTP-ESTABLISH.
play_id Integer [Required] A sequence number for the RTP-PLAY following the most recent RTP-ESTABLISH.
First play after acceptance is 1. This will be echoed back to disambiguate late/overlapping responses.
announcement Object [Required] Container for the attributes of the announcement to be constructed and played.
.message_id Integer A single message ID to play.
This ID must be configured within the RtpApp database or file-based configuration.
The definition of this ID may depend on the specified language, and the definition may allow multiple audio file fragements and/or one or more variable parts.
Specify exactly one of .message_id or .message_ids or .files.
.message_ids Array of Integer An array of one or more message IDs to play in sequence.
Each ID listed here must be configured within the RtpApp database or file-based configuration.
If variable part expansion is being used, then only a single message ID is permitted.
Specify exactly one of .message_id or .message_ids or .files.
.files Array of String Explicit Array of one or more filenames to play in sequence. Specifying this parameter will bypass the message ID translation process in RtpApp and allows the service logic to explicitly control the audio file fragments to be streamed.
All filenames must be from the announcement language, it is not possible to override the language per-fragment.
Each filename must not include the audio file type suffix part e.g. must not contain the .ul, or .amr.
Each filename must include the subdirectory announcements or variable_parts.
The directory name "a" is a supported abbreviation for "announcements".
The directory name "vp" or "v" is a supported abbreviation for "variable_parts".
Example files list: [ 'a/You_Entered', 'v/1', 'vp/4' ].
.language String Optional language name to use instead of the default value configured within the RtpApp.
The RtpApp will use this when mapping announcement ID/IDs into a file list.
The RtpApp will use this expanding variable parts into audio file fragments.
This language name must be configured within the RtpApp database or file-based configuration.
This language name is mandatory to be present if any variable parts are provided.
Refer to the RtpApp configuration documentation.
(Default = The default language configured in the RtpApp)
.repetition Integer A requested repetition count, the announcement will be repeated up to the indicated number of times.
(Default = Play the announcement list only once).
.duration Integer [Required] The total permitted duration of the interaction including repetitions and any silence.
This value must be present, the calling application must supply a default value if the service logic did not.
.variables Array of Object An array of variable values to substitute into pre-defined placeholders in the message structure.
If this attribute is present then (a) exactly one message ID must be supplied, and (b) the language name attribute is mandatory.
Each variable part is an object which specifies exactly one of the attributes as follows.
.integer Integer An integer value to speak as a variable part.
.number_digits Integer An integer value to speak as a variable part.
.time_hhmm <HHMM> An integer hour and minute to speak as a variable part.
Value is in the range 0000-2400.
.date_yymmdd <YYMMDD> A 6-digit integer year/month/day to speak as a variable part.
This will be converted to a YYYYMMDD value by putting the year in range 1951-2050.
.date_yyyymmdd <YYYYMMDD> An 8-digit integer year/month/day to speak as a variable part.
.price_digits Integer An integer value of "cents" to speak as a variable part.
.collect Object Container for information related to digit collection.
Digit collection will be performed if and only if this container element is present.
(Default = do not collect user input digits).
.min_num_digits 1 - 32 Minimum number of digits to collect.
If this amount of digits is not reached, then do not return any digits at all.
(Default = The default value configured in the RtpApp).
.max_num_digits 1 - 32 Maximum number of digits to collect.
If this amount of digits is reached, then immediately return.
(Default = The default value configured in the RtpApp).
.cancel_digit #*A-F0-9 Digit which user can use to clear the input buffer and restart entry.
(Default = there is no Cancel Input digit).
.end_digit #*A-F0-9 Digit which user can use to indicate that they have completed entry.
(Default = there is no End of Input digit).
.first_digit_timeout Positive Integer The number of seconds allowed between completing the announcement and entering the first digit.
(Default = The default value configured in the RtpApp).
.inter_digit_timeout Positive Integer The number of seconds allowed between entering one digit and entering the subsequent digit.
(Default = The default value configured in the RtpApp).
.private_digits 0 / 1 Indicates that the collected digits are private, e.g. PIN entry, and the RtpApp should not log them to EDR.
(Default = the collected digits are not private).
.interruptable 0 / 1 Informs the RtpApp that DTMF input from the user should interrupt the playing of the prompt.
(Default = the prompt will be interrupted when user input begins).

RTP-PLAYED

The RTP-PLAYED message is sent by RtpApp to the controlling SIP Application to indicate that the play request has completed by one of the “natural” end conditions as described above under the RTP-PLAY message description.

The RtpApp will now wait for further instructions, being either another RTP-PLAY or an RTP-HANGUP. These instructions must be received within the instruction timer window as configured on the RtpApp.

The attributes of the RTP-PLAYED message are:

Field Type Description
stream_number Integer [Required] Echo of original value from preceding RTP-PLAY.
play_id Integer [Required] Echo of original value from preceding RTP-PLAY.
rtp Object [Required] The RTP parameters for the message.
.collected_digits String If the RTP-PLAY did not request digit collection, this will be absent or undefined.
If the RTP-PLAY requested digit collection, then this will be present and defined.
If not enough digits were entered, then this will be the empty string `''`.
.dtmf_source INBAND / RTP-EVENT / SIP The source of the collected digits, for informational purposes, if applicable.

RTP-SHUTDOWN

The RTP-SHUTDOWN message is sent by the RtpApp to the originating SIP app to indicate that the RTP stream has been unexpectedly shutdown by some error within the RtpApp.

This is a final message. No further messages are valid after this message is sent.

The attributes of the RTP-SHUTDOWN message are:

Field Type Description
stream_number Integer [Required] Echo of original value from originating RTP-ESTABLISH.
success 0 [Required] Always 0 to indicate unexpected failure.
error String [Required] Indicates the reason why the RTP session unexpectedly failed.