AmiStream — Documentation

Overview

AmiStream is a lightweight, stable, and extensible Java library for working with the Asterisk AMI (Asterisk Manager Interface). It is designed for server-side applications such as PBX integrations, call automation, billing, monitoring and support systems. The library provides connection management, action/response correlation, asynchronous handling and event listeners.

Reliable connections

Connection and authentication to AMI with automatic reconnection and configurable timeouts.

Real-time events

Receive and handle AMI events in real time via EventListener interfaces.

Async API

Send actions synchronously or asynchronously (CompletableFuture) with transaction correlation.

Integration-ready

Designed for multithreaded server applications and easy integration with frameworks.

Quick Start

Minimal example: connect to AMI, send an action and print the response.

import com.siperf.amistream.AmiClient;
import com.siperf.amistream.ActionResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        AmiClient client = AmiClient.builder()
            .host("127.0.0.1")
            .port(5038)
            .username("admin")
            .password("secret")
            .build();

        client.connect();
        ActionResponse resp = client.action("CoreShowChannels").send().get();
        System.out.println(resp.getBody());
        client.disconnect();
    }
}

API Highlights

AmiClient

Primary client for connection management: connect(), disconnect(), action(...).

ActionBuilder / ActionResponse

Build and send AMI actions; receive synchronous or asynchronous responses and access response body/headers.

Event / EventListener

Subscribe to and process AMI events delivered by the server in real time.

Examples

1) Basic connection (synchronous)

// See Quick Start example above — synchronous action send and get()

2) Event listener

import com.siperf.amistream.AmiClient;
import com.siperf.amistream.event.Event;
import com.siperf.amistream.event.EventListener;

AmiClient client = AmiClient.builder()
    .host("127.0.0.1")
    .port(5038)
    .username("admin")
    .password("secret")
    .build();

client.connect();
client.addEventListener(new EventListener() {
    @Override
    public void onEvent(Event event) {
        System.out.println("Event: " + event.getName());
        System.out.println(event.getAttributes());
    }
});

3) Asynchronous actions

import java.util.concurrent.CompletableFuture;
import com.siperf.amistream.AmiClient;
import com.siperf.amistream.ActionResponse;

AmiClient client = AmiClient.builder() /* ... */ .build();
client.connect();
CompletableFuture future = client.action("CoreShowChannels").sendAsync();
future.thenAccept(resp -> System.out.println(resp.getBody()))
      .exceptionally(ex -> { System.err.println(ex.getMessage()); return null; });

Installation

Add AmiStream to your Maven project:

<dependency>
    <groupId>com.siperf</groupId>
    <artifactId>amistream</artifactId>
    <version>0.8.17</version>
</dependency>

Changelog

0.8.17 — 2024-12-27

Minor update: small fixes and stability improvements.

0.8.16 — 2024-08-02

Minor update.

0.8.15 — 2023-10-29

Minor update.

0.8.14 — 2022-02-16

Minor update.