{"id":19185693,"url":"https://github.com/staskobzar/amiws","last_synced_at":"2025-10-26T20:07:21.570Z","repository":{"id":24755640,"uuid":"92418274","full_name":"staskobzar/amiws","owner":"staskobzar","description":"Asterisk Management Interface (AMI) to Web-socket proxy","archived":false,"fork":false,"pushed_at":"2023-05-24T01:13:27.000Z","size":5597,"stargazers_count":83,"open_issues_count":16,"forks_count":51,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-04-14T10:56:16.224Z","etag":null,"topics":["ami","asterisk","frozen","lemon","mongoose","re2c","ssl","vuejs","websocket","websocket-proxy","yaml-configuration"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/staskobzar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-25T15:38:16.000Z","updated_at":"2023-12-24T10:06:01.000Z","dependencies_parsed_at":"2024-11-09T11:12:15.884Z","dependency_job_id":"42a8202d-6b84-45e4-b767-48aec376d53e","html_url":"https://github.com/staskobzar/amiws","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staskobzar%2Famiws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staskobzar%2Famiws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staskobzar%2Famiws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staskobzar%2Famiws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/staskobzar","download_url":"https://codeload.github.com/staskobzar/amiws/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249124283,"owners_count":21216649,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ami","asterisk","frozen","lemon","mongoose","re2c","ssl","vuejs","websocket","websocket-proxy","yaml-configuration"],"created_at":"2024-11-09T11:11:34.318Z","updated_at":"2025-10-26T20:07:21.487Z","avatar_url":"https://github.com/staskobzar.png","language":"C","readme":"## amiws - Asterisk Manager Interface (AMI) to web-socket proxy\n\n[![Build Status](https://travis-ci.org/staskobzar/amiws.svg?branch=master)](https://travis-ci.org/staskobzar/amiws)\n![](https://img.shields.io/badge/license-GPL_3-green.svg \"License\")\n[![codecov](https://codecov.io/gh/staskobzar/amiws/branch/master/graph/badge.svg)](https://codecov.io/gh/staskobzar/amiws)\n![verion-2.2.1](https://img.shields.io/badge/version-2.2.1-blue.svg)\n\n\n### Introduction\n*amiws* is simple proxy from AMI to WEB. It can connect to one or more Asterisk PBXs via AMI (Asterisk Manager Interface), read messages from AMI stream and send actions/commands to it. Received messages are parsed and converted to JSON.\n*amiws* also provides HTTP/WebSocket interface and sends JSON messages to all connected users via HTTP.\n\n\nHere is simple workflow scheme:\n![amiws workflow](https://github.com/staskobzar/amiws/blob/master/doc/amiws.workflaw.png)\n\n\n*amiws* proxy can help to build interactive, real-time dashboards for Asterisk PBX single or multiple servers. The example of a simple dashboard can be found in directory \"web_root\". Here is how it would look like when connecting two Asterisk PBXs:\n![web interface](https://github.com/staskobzar/amiws/blob/master/doc/amiws.user.screen.png)\n\n\n### Features\n* AMI protocol implementation\n* Plain TCP or SSL/TLS connection to AMI\n* Logging with syslog\n* HTTP and WebSocket server\n* SSL/TLS encrypted connection for HTTP and WebSocket\n* WWW Digest authentication with username/password for HTTP(s)\n* YAML configuration file\n\n\n### Command line arguments\nUsage: ```amiws [OPTIONS]```\n\nOptions:\n\u003cpre\u003e\n-h, --help              Printf this help message.\n-f, --file FILENAME     Configuration file. By default '/etc/amiws.yaml'\n-d, --daemon            Daemonize process.\n-p, --pidfile FILENAME  PID file when run as daemon. By default '/tmp/amiws.pid'\n-D, --wdir PATH         Working directory when run as daemon. By default '/tmp'\n\u003c/pre\u003e\n\n### Dependences and libraries\n* ```libyaml``` - to read YAML configuration files.\n* ```openssl``` - TLS/SSL for AMI and HTTP. Only if compiled with ssl support.\n\n*amiws* relies on several greate projects:\n* [mongoose](https://github.com/cesanta/mongoose) - awesome embedded networking library from [Cesanta](https://www.cesanta.com/).\n* [frozen](https://github.com/cesanta/frozen) - awesome JSON parser and emitter from [Cesanta](https://www.cesanta.com/).\n* [re2c](http://re2c.org/) - awesome lexer generator for AMI protocol implementation.\n* [cmocka](https://cmocka.org/) - awesome unit testing framework for C.\n* [lemon](http://www.hwaci.com/sw/lemon/lemon.html) - parser generator to process YAML tokens\n\nThey do not need to be installed. *mongoose* and *frozen* are already included. *re2c* and *cmocka* are only needed for developers.\n\n### Building and install\n```\nautoreconf -if\n./configure\nmake \u0026\u0026 make install\n```\n\nIn case of problems, try to run script ```./bootstrap```.\n\nTo enable SSL support:\n```\n./configure --with-ssl\nmake \u0026\u0026 make install\n```\n\nTo create source documentation:\n```\nmake doc\n```\n\nTo run unit tests (requires cmocka):\n```\nmake check\n```\n\nThis repo also provides init scripts for [System V](https://github.com/staskobzar/amiws/blob/master/etc/amiws.sysv.init)\nand [systemctl](https://github.com/staskobzar/amiws/blob/master/etc/amiws.service) in \"etc/\" directory.\n\n### Configuration\n\nProgram behaviour is controlled by configuration file. Configuration parameters are described in sample file [\"amiws.annotated.yaml\"](https://github.com/staskobzar/amiws/blob/master/etc/amiws.annotated.yaml) in directory \"etc\" of this repository.\n\n### JSON message\n\nExample of *amiws* JSON message:\n\n```JSON\n{\n   \"type\": 3,\n   \"server_id\": 1,\n   \"server_name\": \"asterisk01.local\",\n   \"ssl\": false,\n   \"data\": {\n      \"Event\": \"Hangup\",\n      \"Privilege\": \"call,all\",\n      \"Channel\": \"SIP/sipp-00000a6a\",\n      \"ChannelState\": \"6\",\n      \"ChannelStateDesc\": \"Up\",\n      \"CallerIDNum\": \"16464964806\",\n      \"CallerIDName\": \"Alice\",\n      \"ConnectedLineNum\": \"\u003cunknown\u003e\",\n      \"ConnectedLineName\": \"\u003cunknown\u003e\",\n      \"Language\": \"en\",\n      \"AccountCode\": \"\",\n      \"Context\": \"from-sip\",\n      \"Exten\": \"55213477583\",\n      \"Priority\": \"8\",\n      \"Uniqueid\": \"1495919040.5315\",\n      \"Linkedid\": \"1495919040.5315\",\n      \"Cause\": \"0\",\n      \"Cause-txt\": \"Unknown\"\n   }\n}\n```\n\n* *type* - AMI message type (see below)\n* *server_id* - Asterisk server ID. Sequential number generated by *amiws* for each AMI connection.\n* *server_name* - AMI connection server name as in configuration file.\n* *ssl* - Flag to indicate id AMI connection is SSL encrypted.\n* *data* - AMI message itself.\n\n\n_AMI message types_:\n- 0 - Unknown\n- 1 - Prompt\n- 2 - Action\n- 3 - Event\n- 4 - Response\n- 5 - Respons with command output\n- 6 - Queues list. AMI returns queues list not as AMI packet but as a text (like command: queue show). That's why here is special type.\n\nAMI description in details can be found in [Asterisk wiki](https://wiki.asterisk.org/wiki/display/AST/Home).\n\n*amiws* also accepts JSON messages and sends them back to all Asterisk servers:\n```javascript\nsock.send(JSON.stringify({\"Action\": \"CoreStatus\", \"ActionID\": \"12345\"}));\n```\nBeware that this will send same Action to all AMI servers!\n\nKeep this in mind when you deploy *amiws* on public Internet and protect access to it.\n\n#### Special header AMIServerID\nTo send message to specified AMI server you can use header ```AMIServerID```.\nThis should correspond to the ```server_id``` in requests.\n\nExample:\n```javascript\nsock.send(JSON.stringify({\"Action\": \"CoreStatus\", \"AMIServerID\": 1}));\n```\n\n#### Sending multiple variables\nIn some cases, you will need to send multiple variables. This can be done with a list:\n\nExample:\n```javascript\nsock.send(JSON.stringify({\"Action\": \"CoreStatus\", \"Variable\": [\"Trunk=provider07\", \"Hop=hop315\"]}));\n```\n\nList is unnecessary when there is only one variable:\n```javascript\nsock.send(JSON.stringify({\"Action\": \"CoreStatus\", \"Variable\": \"Trunk=provider07\"}));\n```\n\n### SSL/TLS transport\nSSL/TLS transport usage is described in this blog article:\nhttp://staskobzar.blogspot.ca/2017/05/amiws-asterisk-manager-iterface-to-web.html\n\nSome more information can be found in annotated configuration file.\n\n### Digest Authentication\nHTTP content can be protected with username/password. When this option is enabled, anyone trying to access web-page will have to provide username and password to proceed.\n\nConfiguration parameters to set are:\n```\nauth_domain   : example.com\nauth_file     : /var/www/.htaccess\n```\n\nParameter *auth_file* is a path to the file with username, password and domain. This file can be generated with utility \"htdigest\" which is the part of Apache httpd server package. For example:\n```\n$ htdigest -c /var/www/.htaccess example.com admin\n```\n\nSecond argument, domain \"example.com\", must be the same as set in parameter *auth_domain*. \n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstaskobzar%2Famiws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstaskobzar%2Famiws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstaskobzar%2Famiws/lists"}