SkillAgentSearch skills...

AmiClient

Modern .NET Standard client for accessing the Asterisk AMI protocol using async/await and Reactive Extensions (Rx)

GenerateConvertImprove

Install / Use

/learn @alexforster/AmiClient
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

AmiClient

Asterisk Management Interface (AMI) client library for .NET

  • https://github.com/alexforster/AmiClient/
  • https://www.nuget.org/packages/AmiClient

Features

  • Designed to be used with async/await
  • Methods can be safely called from multiple threads
  • The AmiClient class is IObservable for use with Reactive Extensions (Rx)

Dependencies

  • System.Reactive.Interfaces

Note: While it's not a dependency, you will probably want to use the System.Reactive.Linq package alongside this library.

Quick start

Here's an easy way to set up an Asterisk 13 development environment:

First, build an Asterisk 13 Docker image...

cat <<'EOF' | docker build -t asterisk13 -
FROM amd64/ubuntu:bionic
SHELL ["/bin/bash", "-e", "-u", "-o", "pipefail", "-c"]

RUN \
	export DEBIAN_FRONTEND=noninteractive; \
	apt-get update; \
	apt-get -y install ca-certificates apt-utils; \
	apt-get -y install asterisk;

RUN printf '%s\n' \
	'[general]' \
	'enabled = yes' \
	'bindaddr = 0.0.0.0' \
	'port = 5038' \
	'timestampevents = yes' \
	'' \
	'#include "manager.d/*.conf"' \
> /etc/asterisk/manager.conf

RUN printf '%s\n' \
	'[admin]' \
	'secret = amp111' \
	'read = all' \
	'write = all' \
> /etc/asterisk/manager.d/admin.conf

VOLUME /etc/asterisk
USER asterisk:asterisk
EXPOSE 5038/tcp
EXPOSE 5060/udp
EXPOSE 10000-10500/udp

ENTRYPOINT ["/usr/sbin/asterisk", "-vvvvvvvvv", "-ddddddddd", "-c"]
EOF

Then, run your new Asterisk 13 Docker image in a temporary container...

docker run -it --rm \
           --name asterisk13-dev \
           -p 5060:5060 -p 5060:5060/udp \
           -p 10000-10500:10000-10500/udp \
           -p 5038:5038 \
           asterisk13

Use the example code below as a starting point for learning the AmiClient API...

Example code

using System;
using System.Text;
using System.Net.Sockets;
using System.Threading.Tasks;
using System.Reactive.Linq;

using Ami;

namespace Playground
{
  internal static class Program
  {
    public static async Task Main(String[] args)
    {
      // Let's create the AmiClient and set up some general event handling...

      var client = new AmiClient();

      // Activity on the wire can be observed and logged using the DataSent
      // and DataReceived events...

      client.DataSent += (s, e) =>
        Console.Error.Write($"{Encoding.UTF8.GetString(e.Data)}");
      client.DataReceived += (s, e) =>
        Console.Error.Write($"{Encoding.UTF8.GetString(e.Data)}");

      // To make testing possible, an AmiClient can operate on any underlying
      // Stream object that is readable and writable. This means that the user
      // is responsible for maintaining a TCP connection to the AMI server...

      var socket = new TcpClient(hostname: "127.0.0.1", port: 5038);

      // The Stopped event can be used to observe when the AmiClient stops
      // processing the underlying stream for any reason...

      client.Stopped += (s, e) =>
      {
        if(e.Exception != null)
        {
          Console.Error.WriteLine($"Exception: {e.Exception}");
        }
      };

      // Let's go...

      using(socket)
      using(client)
      {
        // First, complete the AMI protocol handshake and start a background
        // I/O task to consume data from the socket...

        await client.Start(socket.GetStream());

        // Next, let's authenticate using the Login() helper function...

        if(!await client.Login(username: "admin", secret: "amp111", md5: true))
        {
          Console.Out.WriteLine("Login failed");
          return;
        }

        // In case the Asterisk server hasn't finished booting, let's wait
        // until it's ready...

        await client.Where(message => message["Event"] == "FullyBooted").FirstAsync();

        // Now, let's issue a PJSIPShowEndpoints command...

        var response = await client.Publish(new AmiMessage
        {
          { "Action", "PJSIPShowEndpoints" },
        });

        // Because we didn't specify an ActionID, one was implicitly
        // created for us by the AmiMessage object. That's how we track
        // requests and responses, allowing this client to be used
        // by multiple threads or tasks.

        if(response["Response"] == "Success")
        {
          // After the PJSIPShowEndpoints command successfully executes,
          // Asterisk will begin emitting EndpointList events.

          // Each EndpointList event represents a single PJSIP endpoint,
          // and has the same ActionID as the PJSIPShowEndpoints command
          // that caused it.

          // Once events have been emitted for all PJSIP endpoints,
          // an EndpointListComplete event will be emitted, again with
          // the same ActionID as the PJSIPShowEndpoints command
          // that caused it.

          // Using System.Reactive.Linq, all of that can be modeled with
          // a simple Rx IObservable consumer...

          await client
              .Where(message => message["ActionID"] == response["ActionID"])
              .TakeWhile(message => message["Event"] != "EndpointListComplete")
              .Do(message =>
                  Console.Out.WriteLine(
                    $"~~~ \"{message["ObjectName"]}\" ({message["DeviceState"]}) ~~~"));
        }

        // We're done, so let's be a good client and use the Logoff()
        // helper function...

        if(!await client.Logoff())
        {
          Console.Out.WriteLine("Logoff failed");
          return;
        }
      }
    }
  }
}

Example output

Action: Challenge
ActionID: 24871f64-ca7e-4dfb-a67f-734ba3893efb
AuthType: MD5

Response: Success
ActionID: 24871f64-ca7e-4dfb-a67f-734ba3893efb
Challenge: 158303519

Action: Login
ActionID: 214fdbe7-7c7c-4ead-abfe-037a3d4cedff
AuthType: MD5
Username: admin
Key: 6a717a8d45e8445832d5d088862654e9

Response: Success
ActionID: 214fdbe7-7c7c-4ead-abfe-037a3d4cedff
Message: Authentication accepted

Event: FullyBooted
Privilege: system,all
Status: Fully Booted

Action: PJSIPShowEndpoints
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2

Event: SuccessfulAuth
Privilege: security,all
EventTV: 2019-01-21T19:56:27.148+0000
Severity: Informational
Service: AMI
EventVersion: 1
AccountID: admin
SessionID: 0x7fcb00000d50
LocalAddress: IPV4/TCP/0.0.0.0/5038
RemoteAddress: IPV4/TCP/172.17.0.1/44628
UsingPassword: 0
SessionTV: 2019-01-21T19:56:27.148+0000

Response: Success
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
EventList: start
Message: A listing of Endpoints follows, presented as EndpointList events

Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1107
Transport: 
Aor: 1107
Auths: 1107
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1107" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1113
Transport: 
Aor: 1113
Auths: 1113
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1113" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1106
Transport: 
Aor: 1106
Auths: 1106
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1106" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1101
Transport: 
Aor: 1101
Auths: 1101
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1101" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1103
Transport: 
Aor: 1103
Auths: 1103
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1103" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1102
Transport: 
Aor: 1102
Auths: 1102
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1102" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1114
Transport: 
Aor: 1114
Auths: 1114
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1114" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1115
Transport: 
Aor: 1115
Auths: 1115
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1115" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1109
Transport: 
Aor: 1109
Auths: 1109
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1109" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1110
Transport: 
Aor: 1110
Auths: 1110
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1110" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: dcs-endpoint
Transport: 
Aor: dcs-aor
Auths: 
OutboundAuths: dcs-auth
Contacts: dcs-aor/sip:sip.digiumcloud.net,
DeviceState: Not in use
ActiveChannels: 

~~~ "dcs-endpoint" (Not in use) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1111
Transport: 
Aor: 1111
Auths: 1111
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1111" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1105
Transport: 
Aor: 1105
Auths: 1105
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1105" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1108
Transport: 
Aor: 1108
Auths: 1108
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1108" (Unavailable) ~~~
Event: Endp

alexforster

View profile

View on GitHub
GitHub Stars41
CategoryDevelopment
Updated3mo ago
Forks19
alexforster/AmiClient

Languages

C#

Security Score

92/100

Audited on Dec 15, 2025

No findings