Skip to end of metadata
Go to start of metadata

The Asterisk External Application Protocol (AEAP) is used to communicate configuration, data, and other information using a simple request/response messaging system. Currently, JSON is the only supported message description format. At present, the following request/response messages are supported:

  • setup - Initializes a remote application
  • get - Retrieves settings and other information from a remote application
  • set - Updates settings and other information on a remote application

Every request and response type will always contain the following fields:

  • request | response : <name>
  • id: <unique id>

Each request has a specified name that's shared with a subsequent matching response. For example, if the request name is "hello", then the response to that request will also have the name "hello". Similarly, every new request has a unique message id that's echoed in the response.


A "setup" must be the first request sent. It is used to determine if further interactions will be allowed, and if so then any given parameters are used to establish initial configuration and setup.

offer request

"request", "id", and "version" are all required fields and must be included. The version is a value that represents the current AEAP message version. As well, at least one or more "codecs" must be specified. While the codec "name" is mandatory, codec attributes are optional. However, if a codec attribute is given then both the attribute "name" and "value" must be provided. "params" is optional, but when given each parameter must be specified as a "name"/"value" pair.

Example 1 offer request  Expand source
Example 2 offer request  Expand source
Example 3 offer request  Expand source

A "setup" response must only be sent in response to a "setup" request, and must be formatted as follows:

offer response okay

Much like the initial request, "response", "id", and "codecs" are required fields. The codec "name" is also required, and must match one of the names given in the request's codec list. "attributes" are again optional.

Example 1 offer response okay  Expand source


A "get" request can be sent anytime after an initial "setup" is accepted, and is used to retrieve attributes, settings, and other data (e.g. results). A "get" request has the following form:

get request

All fields are required, and at least one parameter name to retrieve must be specified. Parameter names should be the name of the attribute, setting, etc... to be retrieved.

Example 1 get request  Expand source

A "get" response is similar, but retrieved "params" are made available in name/value pairs:

get response okay

Be aware that the returned value's type is named parameter dependent. For instance, depending on the given "param" the returned "value" could be a string, an integer, or even an array of values.

Example 1 get response okay  Expand source


A "set" request can be sent anytime after an initial "setup" is accepted, and is used to set attributes, settings, and other data on the remote. A "set" request has the following form, and can be used to even set multiple parameters at once:

set request

All fields are required. Similar to "get", a named parameter's value type varies based on the parameters themselves.

Example 1 set request  Expand source

A "set" response to a successful request is just a basic acknowledgment that only contains response name and id:

set response
Example 1 set response okay  Expand source


When an error occurs for any given request all responses follow the same format. Similar to a regular response the response name and id are the same as that of the request. The only other additional field is an "error_msg", which is a text description of the error:

error response
Example 1 setup error  Expand source
Example 2 get error  Expand source
Example 3 set error  Expand source




  • No labels