Getting Started

Add asterisk-rs to your project:

[dependencies]
asterisk-rs = "0.2"

Or pick individual protocols:

[dependencies]
asterisk-rs = { version = "0.2", default-features = false, features = ["ami"] }

Or use crates directly:

[dependencies]
asterisk-rs-ami = "0.2"

Protocols

Domain Types

Common Asterisk constants are available as typed enums in asterisk_rs_core::types: hangup causes, channel states, device states, dial statuses, and more. See Domain Types for the full list.

Requirements

• Rust 1.83+ (for async fn in trait / RPITIT)
• tokio runtime
• A running Asterisk instance for integration

Domain Types

Typed enums for Asterisk domain constants, available in asterisk_rs_core::types.

HangupCause

Q.931/Q.850 hangup cause codes used across AMI and ARI

ChannelState

channel state as reported by Asterisk

DeviceState

device state values used in device state events and queries

DialStatus

result of a dial attempt, set in the DIALSTATUS channel variable

CdrDisposition

CDR disposition values

PeerStatus

SIP/PJSIP peer registration status

QueueStrategy

queue member selection strategy

ExtensionState

extension hint state values

AgiStatus

AGI response status codes

AMI (Asterisk Manager Interface)

AMI is a TCP protocol on port 5038 for monitoring and controlling Asterisk. The client handles authentication, reconnection, and event dispatch automatically.

Quick Start

use asterisk_rs_ami::AmiClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AmiClient::builder()
        .host("10.0.0.1")
        .credentials("admin", "secret")
        .build()
        .await?;

    let resp = client.ping().await?;
    println!("{resp:?}");

    client.disconnect().await?;
    Ok(())
}

Capabilities

• Typed events and actions covering the full Asterisk 23 AMI surface
• MD5 challenge-response and plaintext authentication
• Automatic reconnection with re-authentication
• Filtered subscriptions – receive only events you care about
• Event-collecting actions – send_collecting() gathers multi-event responses
• Command output capture for Response: Follows
• Configurable timeouts, backoff, and event buffer size

See Connection & Authentication for setup details, Events for the event system, and Reference for complete event/action lists.

Connection & Authentication

Builder

use asterisk_rs_ami::AmiClient;
use asterisk_rs_core::config::ReconnectPolicy;
use std::time::Duration;

let client = AmiClient::builder()
    .host("10.0.0.1")
    .port(5038)
    .credentials("admin", "secret")
    .timeout(Duration::from_secs(10))
    .reconnect(ReconnectPolicy::exponential(
        Duration::from_secs(1),
        Duration::from_secs(30),
    ))
    .event_capacity(2048)
    .build()
    .await?;

Authentication

The client tries MD5 challenge-response first, falling back to plaintext. Authentication happens automatically during build() and after every reconnect.

Reconnection

When the TCP connection drops, the background task reconnects with exponential backoff and re-authenticates before setting the connection state to Connected.

Policies:

• ReconnectPolicy::exponential(initial, max) — doubling delay with jitter
• ReconnectPolicy::fixed(interval) — constant delay
• ReconnectPolicy::none() — no retry
• .with_max_retries(n) — cap attempts

Connection State

Monitor connection health:

use asterisk_rs_core::config::ConnectionState;

let state = client.connection_state();
match state {
    ConnectionState::Connected => { /* ready */ }
    ConnectionState::Reconnecting => { /* waiting */ }
    _ => { /* down */ }
}

Disconnect

client.disconnect().await?;

Sends a Logoff action before closing the TCP connection.

Events

AMI delivers real-time events as things happen in Asterisk. Events are parsed into typed AmiEvent variants. See Reference for the complete list.

Subscribing

let mut sub = client.subscribe();

while let Some(event) = sub.recv().await {
    println!("{}: {}", event.event_name(), event.channel().unwrap_or("n/a"));
}

Filtered Subscriptions

Subscribe to specific event types without processing every event:

let mut hangups = client.subscribe_filtered(|e| {
    e.event_name() == "Hangup"
});

while let Some(event) = hangups.recv().await {
    if let AmiEvent::Hangup { channel, cause, cause_txt, .. } = event {
        println!("hangup on {channel}: {cause} ({cause_txt})");
    }
}

Event-Generating Actions

Actions like Status, CoreShowChannels, and QueueStatus return results as a sequence of events. Use send_collecting to gather them:

use asterisk_rs_ami::action::StatusAction;

let result = client.send_collecting(&StatusAction { channel: None }).await?;
println!("got {} channel status events", result.events.len());
for event in &result.events {
    println!("  {}", event.event_name());
}

Common Accessors

Every AmiEvent has:

• event_name() — the raw event name string
• channel() — the associated channel name, if any
• unique_id() — the unique channel identifier, if any

Unknown Events

Events not covered by typed variants arrive as AmiEvent::Unknown:

if let AmiEvent::Unknown { event_name, headers } = event {
    println!("unhandled: {event_name}");
    for (k, v) in &headers {
        println!("  {k}: {v}");
    }
}

AMI Reference

Events (181 typed variants)

Actions (150 typed structs)

AGI (Asterisk Gateway Interface)

AGI allows external programs to control Asterisk dialplan execution. This crate implements a FastAGI TCP server that accepts connections from Asterisk and dispatches them to a handler.

Quick Start

use asterisk_rs_agi::{AgiServer, AgiHandler, AgiRequest, AgiChannel};

struct MyHandler;

impl AgiHandler for MyHandler {
    async fn handle(&self, request: AgiRequest, mut channel: AgiChannel)
        -> asterisk_rs_agi::error::Result<()>
    {
        channel.answer().await?;
        channel.stream_file("hello-world", "").await?;
        channel.hangup(None).await?;
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (server, _shutdown) = AgiServer::builder()
        .bind("0.0.0.0:4573")
        .handler(MyHandler)
        .max_connections(100)
        .build()
        .await?;

    server.run().await?;
    Ok(())
}

Capabilities

• Every AGI command with typed async methods
• Handler trait using native async fn (RPITIT, no macro needed)
• Request environment parsing from Asterisk
• Configurable concurrency limits
• Graceful shutdown via ShutdownHandle

See FastAGI Server for server details and Reference for the complete command list.

FastAGI Server

Binding

The server binds a TCP listener and dispatches each connection to your handler. Asterisk connects via the AGI() dialplan application:

exten => 100,1,AGI(agi://your-server:4573)

Handler Trait

pub trait AgiHandler: Send + Sync + 'static {
    fn handle(&self, request: AgiRequest, channel: AgiChannel)
        -> impl Future<Output = Result<()>> + Send;
}

The handler receives the AGI request (parsed environment variables from Asterisk) and a channel for sending commands back.

Request Environment

AgiRequest contains the agi_* variables sent by Asterisk at connection start: channel name, caller ID, called extension, context, language, etc.

Channel Commands

AgiChannel provides typed async methods for every AGI command: answer, hangup, stream_file, get_data, say_digits, record_file, database_get, speech_create, and more. See Reference.

Concurrency

Limit concurrent connections with max_connections:

let (server, _shutdown) = AgiServer::builder()
    .bind("0.0.0.0:4573")
    .handler(MyHandler)
    .max_connections(50)
    .build()
    .await?;

Graceful Shutdown

build() returns a ShutdownHandle that stops the accept loop:

let (server, shutdown) = AgiServer::builder()
    .bind("0.0.0.0:4573")
    .handler(MyHandler)
    .build()
    .await?;

// stop accepting after ctrl-c
tokio::spawn(async move {
    tokio::signal::ctrl_c().await.ok();
    shutdown.shutdown();
});

server.run().await?;

AGI Reference

Commands (47 total)

Channel Methods (48 total)

ARI (Asterisk REST Interface)

ARI provides full call control through a REST API combined with a WebSocket event stream for Stasis applications.

Quick Start

use asterisk_rs_ari::{AriClient, AriConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = AriConfig::builder("my-app")
        .host("10.0.0.1")
        .username("asterisk")
        .password("secret")
        .build()?;

    let client = AriClient::connect(config).await?;
    let mut events = client.subscribe();

    while let Some(msg) = events.recv().await {
        println!("[{}] {:?}", msg.application, msg.event);
    }

    Ok(())
}

Capabilities

• REST client and WebSocket listener covering the full Asterisk 23 ARI surface
• Typed events with metadata (application, timestamp, asterisk_id)
• Filtered subscriptions – receive only events you care about
• Resource handles for channels, bridges, playbacks, recordings
• System management – modules, logging, config, global variables
• URL-safe query encoding, HTTP timeouts, WebSocket lifecycle management

See Stasis Applications for the event model, Resources for the handle pattern, and Reference for complete endpoint lists.

Stasis Applications

ARI routes calls to your application via the Stasis() dialplan application:

exten => 100,1,Stasis(my-app,arg1,arg2)

Event Stream

Events arrive via WebSocket as AriMessage structs containing metadata and a typed AriEvent:

use asterisk_rs_ari::event::{AriEvent, AriMessage};

let mut events = client.subscribe();
while let Some(msg) = events.recv().await {
    println!("app={} time={}", msg.application, msg.timestamp);
    match msg.event {
        AriEvent::StasisStart { channel, args, .. } => {
            println!("call from {} with args {:?}", channel.name, args);
        }
        AriEvent::StasisEnd { channel } => {
            println!("call ended: {}", channel.name);
        }
        _ => {}
    }
}

Filtered Subscriptions

let mut calls = client.subscribe_filtered(|msg| {
    matches!(msg.event, AriEvent::StasisStart { .. } | AriEvent::StasisEnd { .. })
});

Event Metadata

Every AriMessage carries:

• application — the Stasis app that received the event
• timestamp — ISO 8601 when the event was created
• asterisk_id — unique Asterisk instance ID (for clusters)
• event — the typed AriEvent payload

See Reference for the complete event list.

Resources

ARI resources are managed through handle objects that bundle a resource ID with a client reference.

Handle Pattern

use asterisk_rs_ari::resources::channel::{ChannelHandle, originate, OriginateParams};

// originate a channel
let params = OriginateParams {
    endpoint: "PJSIP/100".into(),
    app: Some("my-app".into()),
    ..Default::default()
};
let channel = originate(&client, &params).await?;

// wrap in a handle for operations
let handle = ChannelHandle::new(channel.id, client.clone());
handle.answer().await?;
handle.play("sound:hello-world").await?;
handle.hangup(None).await?;

Available Handles

Module Functions

Each resource module also provides free functions for list/get/create:

use asterisk_rs_ari::resources::channel;
use asterisk_rs_ari::resources::bridge;

let channels = channel::list(&client).await?;
let bridges = bridge::list(&client).await?;

Asterisk System

The asterisk resource module provides system management:

use asterisk_rs_ari::resources::asterisk;

let info = asterisk::info(&client, None).await?;
let pong = asterisk::ping(&client).await?;
asterisk::reload_module(&client, "res_pjsip.so").await?;

See Reference for all operations per resource.

ARI Reference

Events (44 typed variants)

Resources (10 modules)

Application (5 operations)

Asterisk (16 operations)

Bridge (BridgeHandle, 16 operations)

Channel (ChannelHandle, 32 operations)

Device State (4 operations)

Endpoint (7 operations)

Mailbox (4 operations)

Playback (PlaybackHandle, 3 operations)

Recording (RecordingHandle, 8 operations)

Sound (2 operations)