emilianodellacasa/ruby-asterisk

View on GitHub
README.md

Summary

Maintainability
Test Coverage
# RUBY-ASTERISK

[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/emilianodellacasa/ruby-asterisk)
[![Donate via Zerocracy](https://www.0crat.com/contrib-badge/CE8UGB6NP.svg)](https://www.0crat.com/contrib/CE8UGB6NP)
[![Managed by Zerocracy](https://www.0crat.com/badge/CE8UGB6NP.svg)](https://www.0crat.com/p/CE8UGB6NP)
[![Maintainability](https://api.codeclimate.com/v1/badges/2861728929db934eb376/maintainability)](https://codeclimate.com/github/emilianodellacasa/ruby-asterisk/maintainability)

This gem add support to your Ruby or RubyOnRails projects to Asterisk Manager Interface

There was a project with the same name, but it appears to be discontinued so I decided to start a new project

## Installation

### Rails3

Add to your Gemfile and run the `bundle` command to install it.

```ruby
 gem "ruby-asterisk"
```

### Rails2

Simply run in your terminal

```ruby
 gem install ruby-asterisk
```

## Usage

### INITIALIZE

To create a new AMI session, just call the following command

```ruby
 @ami = RubyAsterisk::AMI.new("192.168.1.1",5038)
```

### LOGIN

To log in, provide to the created sessions a valid username and password 

```ruby
 @ami.login("mark","mysecret")
```

Like all commands, it will return a Response command that could be parsed accordingly

### CORE SHOW CHANNELS

To get a list of all channels currently active on your Asterisk installation, use the following command

```ruby
 @ami.core_show_channels
```

### PARKED CALLS

To get a list of all parked calls on your Asterisk PBX, use the following command

```ruby
 @ami.parked_calls
```

### ORIGINATE

To start a new call use the following command

```ruby
 @ami.originate("SIP/9100","OUTGOING","123456","1","var1=12,var2=99") # CHANNEL, CONTEXT, CALLEE, PRIORITY, VARIABLES
```


### COMMAND

To execute a cli command use the following code

```ruby
 @ami.command("core show channels")
```

### MEETME LIST

To get a list of all active conferences use the following command

```ruby
 @ami.meet_me_list
```

### EXTENSION STATE

To get the state of an extension use the following command

```ruby
 @ami.extension_state(@exten,@context)
```

### DEVICE STATE LIST

To get list of states of devices

```ruby
 @ami.device_state_list(@exten,@context)
```

### SKINNY DEVICES AND LINES

To get list of skinny devices

```ruby
 @ami.skinny_devices
```

To get list of skinny lines

```ruby
 @ami.skinny_lines
```

### QUEUE PAUSE
                                                                                         
To pause or unpause a member in a call queue
                                                                                                        
```ruby
 @ami.queue_pause("SIP/100", "true", "myqueue", "reason")                                                                            
```

### PING

To ping asterisk AMI

```ruby
 @ami.ping
```

### EVENT MASK                                                            

To enable or disable sending events to this manager connection

```ruby
 @ami.event_mask("on")
```

### SIPpeers

To get a list of sip peers (equivalent to "sip show peers" call on the asterisk server).  This can be used to get a buddy list. 

```ruby
 @ami.sip_peers
```

### SIP SHOW PEER

To get info of a peer (equivalent to "sip show peer" call on the asterisk server).

```ruby
 @ami.sip_show_peer(peer)
```

### SIP SHOW REGISTRY

Retrieve a status of SIP registries and their statuses from the Asterisk server.

```ruby
 @ami.sip_show_registry
```

### STATUS
                                                                                                                        
To get a status of a single channel or for all channels                                                                                                                                  
```ruby
 @ami.status 
```

### ATXFER

Attendand transfer

```ruby
 @ami.atxfer(channel, exten, context, priority = '1')
```

### WAIT EVENT

Wait for an event to occur. Timeout in seconds to wait for events, -1 means forever

```ruby
 wait_event(timeout=-1)
```

### MONITOR

Monitor a channel

```ruby
 monitor(channel,mix=false,file=nil,format='wav')
```

### STOP MONITOR

Stop monitoring a channel

```ruby
 stop_monitor(channel)
```

### PAUSE MONITOR

Pause monitoring of a channel

```ruby
 pause_monitor(channel)
```

### UNPAUSE MONITOR

Unpause monitoring of a channel

```ruby
 unpause_monitor(channel)
```

### CHANGE MONITOR

Change monitoring filename of a channel

```ruby
 change_monitor(channel,file)
```

### THE RESPONSE OBJECT

The response object contains all information about all data received from Asterisk. Here follows a list of all object's properties:

- type
- success
- action_id
- message
- data
- raw_response

The data property contains all additional information obtained from Asterisk, like for example the list of active channels after a "core show channels" command.

## Todo List

- Adding initialization parameters for Telnet options like Output_log, Waittime, Dump_log, timeout;
- Adding test cases for better code coverage;
- Refactoring of ruby-asterisk.rb, adding method_missing for the purpose of supporting as much AMI commands as possible

## Development

Questions or problems? Please post them on the [issue tracker](https://github.com/emilianodellacasa/ruby-asterisk/issues). You can contribute changes by forking the project and submitting a pull request. You can ensure the tests passing by running `bundle` and `rake`.

This gem is created by Emiliano Della Casa and is under the MIT License and it is distributed by courtesy of [Engim srl](http://www.engim.eu/en).