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.

Setup

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.

"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.

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

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.

Get

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:

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.

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

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.

Set

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:

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

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

Errors

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: