{"id":16389295,"url":"https://github.com/marcelog/elixir_ami","last_synced_at":"2025-03-23T04:31:35.366Z","repository":{"id":57494266,"uuid":"44890319","full_name":"marcelog/elixir_ami","owner":"marcelog","description":"An Elixir AMI client","archived":false,"fork":false,"pushed_at":"2017-01-22T17:09:01.000Z","size":38,"stargazers_count":13,"open_issues_count":1,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-15T09:31:12.751Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcelog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-25T00:22:01.000Z","updated_at":"2023-08-22T08:13:15.000Z","dependencies_parsed_at":"2022-09-02T06:12:44.892Z","dependency_job_id":null,"html_url":"https://github.com/marcelog/elixir_ami","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelog%2Felixir_ami","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelog%2Felixir_ami/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelog%2Felixir_ami/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelog%2Felixir_ami/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcelog","download_url":"https://codeload.github.com/marcelog/elixir_ami/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245056889,"owners_count":20553855,"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":[],"created_at":"2024-10-11T04:32:16.963Z","updated_at":"2025-03-23T04:31:34.981Z","avatar_url":"https://github.com/marcelog.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ElixirAmi\n\nAn [Asterisk](http://www.asterisk.org/) client for the [AMI](https://wiki.asterisk.org/wiki/display/AST/AMI+v2+Specification)\nprotocol written in [Elixir](http://elixir-lang.org/). For a quick introduction to AMI you can read [this](http://marcelog.github.io/articles/php_asterisk_manager_interface_protocol_tutorial_introduction.html).\n\nThis is similar to [PAMI](https://github.com/marcelog/PAMI) for PHP, [NAMI](https://github.com/marcelog/Nami) for NodeJS, and\n[erlami](https://github.com/marcelog/erlami) for Erlang.\n\n----\n\n# Using it with Mix\n\nTo use it in your Mix projects, first add it as a dependency:\n\n```elixir\ndef deps do\n  [{:elixir_ami, \"~\u003e 0.0.10\"}]\nend\n```\nThen run mix deps.get to install it.\n\nAlso add the app in your mix.exs file:\n```elixir\n  [\n    applications: [:logger, :elixir_ami],\n    ...\n  ]\n```\n----\n\n# Connecting to Asterisk\n\nTo create a connection, you need to specify the connection information like this:\n\n```elixir\nalias ElixirAmi.Connection, as: Conn\n\nconnection_data = %Conn{\n  name: :my_connection,       # The gen_server connection will be registered with this name\n  host: \"192.168.0.123\",\n  port: 5038,\n  username: \"frank\",\n  password: \"lean\",\n  connection_timeout: 5000,   # How many millseconds to wait when connecting\n  reconnect_timeout: 5000,    # Wait this many milliseconds before attempting reconnection,\n  ssl_options: nil            # Or [ssl:ssl_option()]. Will try a regular TCP connection if this value is nil\n}\n```\n## Using the built in supervisor\n\nThe recommended way to create a connection is to take advantage of the built in supervisor,\nusing `ElixirAmi.Supervisor.Ami` (this connection will be automatically supervised and restarted\nin case of a crash):\n\n```elixir\nalias ElixirAmi.Supervisor.Ami, as AmiSup\n\n{:ok, pid} = AmiSup.new connection_data\n```\n\n## Creating a connection without the supervisor\n\nTo start a connection under your own supervision tree or OTP application structure,\nuse `ElixirAmi.Connection.start_link` or `ElixirAmi.Connection.start` as follows:\n\n```elixir\n\n{:ok, pid} = Conn.start_link connection_data\n```\n\n# Sending an action\n\nYou can find actions inside the [Action](https://github.com/marcelog/elixir_ami/blob/master/lib/elixir_ami/action.ex)\nmodule (feel free to open pull requests to add more!).\n\n```elixir\nalias ElixirAmi.Action, as: Action\n\nConn.send_action :my_connection, Action.ping\n\n%ElixirAmi.Response{\n  source: :my_connection,\n  action_id: \"-576460752303423460\",\n  complete: true,\n  events: [],\n  keys: %{\n    \"ping\" =\u003e \"Pong\",\n    \"timestamp\" =\u003e \"1445770404.871145\"\n  },\n  success: true,\n  variables: %{}\n}\n```\nThe response will *make its best* to return all related events for the response (there might be\ncases where the Asterisk will violate the AMI protocol and this will **not** be possible). Sometimes\nthe implementation of the events is not consistent, or it's just broken. Please report any issues you\nmay have and I'll try to fix them.\n\nAll related events will be returned in the `events` key of the response.\n\n## Sending custom actions\n\nIf you want to send an action that is not already supported in the `Action` module, you have two choices:\n\n * Open a pull request (recommended :))\n * Use the function `Action.new/3` to create your custom action and send it. This is actually\n the function used behind the scenes to send the supported actions.\n\n### Using Action.new\n\n```elixir\nConn.send_action :my_connection, Action.new(\n  \"my_cool_action\",\n  %{mykey: \"myvalue\"},\n  %{myvar: \"myvarvalue\"}\n)\n```\n\nWhere the arguments are:\n\n  1. The action name\n  2. The key values for the action (optional)\n  3. Additional variables (optional)\n\n----\n\n# Receiving events\n\nTo receive asynchronous events (i.e: not related to a response) you can register listeners\nwith their filters, both are of type function and will receive 3 arguments:\n\n * source: The connection name.\n * listener_id: The current listener id.\n * event: The event received from asterisk.\n\n## Registering event listeners\n\n```elixir\nlistener_id = Conn.add_listener(\n  :my_connection,\n  fn(source, listener_id, event) -\u003e event.event === \"varset\" end,\n  \u0026MyModule.my_function/3\n)\n```\n\nThe filter must return `true` or `false`. If it returns `true`, the second function\n(in this case `MyModule.my_function/2` will be called with the same arguments) to\nprocess the event, the result is discarded.\n\n## Removing event listeners\n\n```elixir\nConn.del_listener :my_connection, listener_id\n```\n\n----\n\n# Async AGI Support\nAsync AGI is supported with the use of [elixir_agi](https://github.com/marcelog/elixir_agi).\n\n```elixir\nConn.async_agi :my_connection, TestAgiApp, :run\n```\n\nThis will start listening for [AsyncAGIStart](https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+ManagerEvent_AsyncAGIStart) events\non the given connection and launch the AGI App by spawning a process and calling `TestAgiApp.run/1`.\n\nNote that this will listen for AsyncAGIStart events for **all channels**. You can specify a channel name with the\noptional ending argument:\n\n```elixir\nConn.async_agi :my_connection, TestAgiApp, :run, true, \"SIP/trunk-234132423\"\n```\n\n----\n# Documentation\n\nFeel free to take a look at the [documentation](http://hexdocs.pm/elixir_ami/)\nserved by hex.pm or the source itself to find more.\n\n----\n\n# License\nThe source code is released under Apache 2 License.\n\nCheck [LICENSE](https://github.com/marcelog/elixir_ami/blob/master/LICENSE) file for more information.\n\n----\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelog%2Felixir_ami","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcelog%2Felixir_ami","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelog%2Felixir_ami/lists"}