Skip to content

Asterisk

Jump to bottom Edit New page
Ben Langfeld edited this page Oct 27, 2011 · 13 revisions

Asterisk Rayo Extension

rayo-asterisk extends the Rayo specification and has its base namespace at urn:xmpp:rayo:asterisk. It provides the means to access raw AGI and AMI transports via Rayo.

AMI

AMI actions and events are supported by way of the server's own AMI connections. Events are sent to all registered parties by way of an XMPP presence stanza:

<presence to="[email protected]/1" from="call.rayo.net">
  <event xmlns="urn:xmpp:rayo:asterisk:ami:1" name="Newchannel">
    <attribute name="Channel" value="SIP/101-3f3f"/>
    <attribute name="State" value="Ring"/>
    <attribute name="Callerid" value="101"/>
    <attribute name="Uniqueid" value="1094154427.10"/>
  </event>
</presence>

Actions constitute a component for the purposes of the Rayo specification. This allows actions to have a complex lifecycle. One executes an action like so:

<iq id="1234" type="set" to="call.rayo.net" from="[email protected]/1">
  <action xmlns="urn:xmpp:rayo:asterisk:ami:1" name="Originate">
    <param name="Channel" value="SIP/101test"/>
    <param name="Context" value="default"/>
    <param name="Exten" value="8135551212"/>
    <param name="Priority" value="1"/>
    <param name="Callerid" value="3125551212"/>
    <param name="Timeout" value="30000"/>
    <param name="Variable" value="var1=23|var2=24|var3=25"/>
    <param name="Async" value="1"/>
  </action>
</iq>

The server will respond with a unique ID for the component like so:

<iq id='1234' type='result' to='[email protected]/1' from='call.rayo.net'>
  <ref id='fgh4590' xmlns='urn:xmpp:rayo:1'/>
</iq>

If the action raises events (is a 'causal action') then these will be received from the component like so:

<presence from="call.rayo.net/fgh4590" to="[email protected]/1">
  <event xmlns="urn:xmpp:rayo:asterisk:ami:1" name="OriginateResponse">
    <attribute name="Exten" value="8135551212"/>
    <attribute name="CallerID" value="3125551212"/>
    ...
  </event>
</presence>

Once the event finishes executing (returns a response), you will receive a complete event like so:

<presence from="call.rayo.net/fgh4590" to="[email protected]/1">
  <complete xmlns="urn:xmpp:rayo:ext:1">
    <success xmlns="urn:xmpp:rayo:asterisk:ami:complete:1">
      <message>Originate successfully queued</message>
    </success>
  </complete>
</presence>

AGI

AGI actions may be executed on a Rayo call like so:

<iq id="1234" type="set" to="[email protected]/1" from="[email protected]/1">
  <action xmlns="urn:xmpp:rayo:asterisk:agi:1" name="GET VARIABLE">
    <param value="UNIQUEID"/>
  </action>
</iq>

The server will respond with a unique ID for the component like so:

<iq id='1234' type='result' to='[email protected]/1' from='[email protected]/1'>
  <ref id='fgh4590' xmlns='urn:xmpp:rayo:1'/>
</iq>

You will then receive a complete event indicating the result of the command's execution:

<presence from="[email protected]/fgh4590" to="[email protected]/1">
  <complete xmlns="urn:xmpp:rayo:ext:1">
    <success xmlns="urn:xmpp:rayo:asterisk:agi:complete:1">
      <code>200</code>
      <result>0</result>
      <data>1187188485.0</data>
    </success>
  </complete>
</presence>

Mapping Rayo to Asterisk AsyncAGI + AMI

Events

Offer

An incoming call to Asterisk will result in an event similar to this:

Event: AsyncAGI
Privilege: agi,all
SubEvent: Start
Channel: SIP/501-081f0730
Env: agi_request:%20async%0aagi_channel:%20SIP/501-081f0730%0aagi_language:%20es%0aagi_type:%20SIP%0
aagi_uniqueid:%20edialer-sercom-1238148792.62%0aagi_callerid:%20unknown%0aagi_calleridname:%20unknow
n%0aagi_callingpres:%200%0aagi_callingani2:%200%0aagi_callington:%200%0aagi_callingtns:%200%0aagi_dn
id:%20unknown%0aagi_rdnis:%20unknown%0aagi_context:%20sip_sercom%0aagi_extension:%20801%0aagi_priori
ty:%202%0aagi_enhanced:%200.0%0aagi_accountcode:%20%0a%0a

Here, a call actor should be created, assigned an ID, and have its SIP headers fetched (using SIP_HEADER()). These headers should include:

  • Max-Forwards
  • Content-Length
  • Contact
  • To
  • CSeq
  • Via
  • Call-ID
  • Content-Type
  • From

The AGI environment variables should be added to the SIP headers as 'x-agi_request', etc.

End

A Hangup event will be received via AMI in this form:

Event: Hangup
Privilege: call,all
Channel: SIP/501-081f0730
Uniqueid: edialer-sercom-1238148792.62
Cause: 16
Cause-txt: Normal Clearing

The corresponding call actor should be looked up by channel ID and be sent this message. The reason element should be established from the "Cause" attribute, with a mapping like so:

  • 16 -> <hangup/>
  • 18,102 -> <timeout/>
  • 17 -> <busy/>
  • 19,21,22 -> <reject/>
  • 0,1,2,3,6,7,27,28,29,30,31,34,38,41,42,43,44,45,50,52,54,57,58,65,66,69,81,88,95,96,97,98,99,100,101,103,111,127 -> <error/>

Errors should have the error code set like so: <error code="127"/>

Ringing

Ringing state is established via an AMI event like so, where the state is "Ringing":

Event: Newstate
Privilege: call,all
Channel: SIP/501-081f0730
State: Ringing
CallerID: <unknown>
CallerIDName: <unknown>
Uniqueid: edialer-sercom-1238148792.62

This should result in a <ringing/> event being sent to the Rayo client.

Answered

Answered status is established via an AMI event like so, where the state is "Up":

Event: Newstate
Privilege: call,all
Channel: SIP/501-081f0730
State: Up
CallerID: <unknown>
CallerIDName: <unknown>
Uniqueid: edialer-sercom-1238148792.62

This should result in an <answered/> event being sent to the Rayo client.

Joined

Joined events should be sent to both calls whenever a bridge is confirmed as created.

Unjoined

Whenever two calls are known to be joined and one call ends, both calls should receive unjoined events. Additionally, if termination of the

Commands

Accept

In order to accept a call (send SIP 183 Session Progress), the translator should turn an <accept/> command into the following AMI dialog:

Action: AGI
Channel: SIP/501-081f0730
Command: EXEC PROGRESS

Response: Success
Message: Added AGI command to queue

Event: AsyncAGI
Privilege: agi,all
SubEvent: End
Channel: SIP/501-081f0730

Answer

In order to answer a call (send SIP 200 OK), the translator should turn an <answer/> command into the following AMI dialog:

Action: AGI
Channel: SIP/501-081f0730
Command: EXEC ANSWER

Response: Success
Message: Added AGI command to queue

Event: AsyncAGI
Privilege: agi,all
SubEvent: End
Channel: SIP/501-081f0730

Hangup

In order to hangup a call, the translator should turn an <answer/> command into the following AMI dialog:

Action: Hangup
Channel: SIP/501-081f0730

Event: Hangup
Channel: SIP/501-081f0730
Uniqueid: 1124989110.20474
Cause: 16

Response: Success
Message: Channel Hungup

Reject

In order to reject a call, the translator should turn a <reject/> command into the following AMI dialog:

The reject reason (<busy/>, <decline/> or <error/>) should be mapped to

Redirect

In order to redirect a call, the translator should turn a <redirect/> command into the following AMI dialog:

Action: Redirect
Channel: SIP/501-081f0730
Exten: 8600029
Context: default
Priority: 1

Response: Success
Message: Channel Redirected

Where 'Exten' matches the URI provided in the 'to' attribute of <redirect/>.

Mute / Unmute

Muting a channel appears not to be possible with Asterisk without a MOH related hack.

Join

Joining two calls must be done by channel ID as below:

Action: Bridge
Channel1: SIP/501-081f0730
Channel2: SIP/501-081f0735

Response: Success
Message: Channels Bridged

When the response is received, a <joined/> event should be sent to both calls.

Unjoin

It appears not to be possible to break a bridge via AMI currently, and so calls may not be forcibly unjoined.

Dial

A <dial/> command should result in the creation of a new call actor, which is assigned an ID to which a <ref/> should be returned. The call should then attempt an origination via AMI like so:

Action: Originate
Async: true
Application: AGI
Data: agi:async
Channel: sip/501
CallerID: 

Response: Success
Message: Originate successfully queued

At this point in time, it appears that a best effort attempt to match ringinging/answered status (Newchannel, Newcallerid, Newstate events) channels to the channel specified to Originate must be made until the OriginateResponse event is received for confirmation against the ActionID

Components

Input

Output

Record

Conference

Add a custom footer
Add a custom sidebar
Clone this wiki locally