Asterisk ari-request: Difference between revisions

From 탱이의 잡동사니
Jump to navigation Jump to search
 
(17 intermediate revisions by the same user not shown)
Line 303: Line 303:
}
}
</pre>
</pre>
=== /bridges/{bridge_id} DELETE ===
==== Example ====
<pre>
$ curl -v --request DELETE \
  --url http://127.0.0.1:8088/ari/bridges/3fe59477-88fa-4fa6-a6d2-81a7dafda249 \
  -u asterisk:asterisk \
  --header 'content-type: application/json'
*  Trying 127.0.0.1:8088...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 8088 (#0)
* Server auth using Basic with user 'asterisk'
> DELETE /ari/bridges/3fe59477-88fa-4fa6-a6d2-81a7dafda249 HTTP/1.1
> Host: 127.0.0.1:8088
> Authorization: Basic YXN0ZXJpc2s6YXN0ZXJpc2s=
> User-Agent: curl/7.68.0
> Accept: */*
> content-type: application/json
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 204 No Content
< Server: asterisk
< Date: Sun, 30 Aug 2020 18:00:02 GMT
< Cache-Control: no-cache, no-store
< Content-Length: 0
<
* Connection #0 to host 127.0.0.1 left intact
</pre>
=== /bridges/{bridggeId}/addChannel POST ===
Add a channel to a bridge.
'''Path parameters'''
* bridgeId: string : Bridge's Id.
'''Query parameters'''
* channel: string : (required) Ids of channels to add to bridge.
: Allows comma-separated values.
* role: string : Channel's role in the bridge.
* absorbDTMF: boolean : Absorb DTMF coming from this channel, preventing it to pass through to the bridge.
* mute: boolean : Mute audio from this channel, preventing it to pass through to the bridge.
* inhibitConnectedLineUpdates: boolean : Do not present the identity of the newly connected channel to other bridge members.


=== /bridges/{bridgeId}/record POST ===
=== /bridges/{bridgeId}/record POST ===
Line 402: Line 445:
Body parameter
Body parameter
* variables: containers - The "variables" key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { "endpoint": "SIP/Alice", "variables": {"CALLERID(name)": "Alice"}}
* variables: containers - The "variables" key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { "endpoint": "SIP/Alice", "variables": {"CALLERID(name)": "Alice"}}
: 만약 Custom SIP header 를 추가하고 싶다면 아래와 같이 하면 된다.
:    "variables": {
:        "CALLERID(all)": "test11111",
:        "PJSIP_HEADER(add,CustomSIPHeader)": "SIPHeader1111"
:    }


Error response
Error response
Line 548: Line 597:
     "state": "Down"
     "state": "Down"
}
}
</pre>
Create a channel with SIP headers
<pre>
curl --location --request POST '127.0.0.1:8088/ari/channels' \
--header 'Authorization: Basic YXN0ZXJpc2s6YXN0ZXJpc2s=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "endpoint": "pjsip/test/sip:test@127.0.0.1:5061",
    "app": "test",
    "appArgs": "context=call-out,call_id=35975fa4-d474-4a8b-9def-8d978eda5dbc",
    "channelId": "test_channel",
    "callerId": "test",
    "variables": {
        "CALLERID(all)": "test11111",
        "PJSIP_HEADER(add,VBOUT-Transport)": "1111"
    }
}'
2021/02/19 08:22:09.226759 127.0.0.1:5060 -> 127.0.0.1:5061
INVITE sip:test@127.0.0.1:5061 SIP/2.0
Via: SIP/2.0/UDP 127.0.0.1:5060;branch=z9hG4bKPjae4830dc-4a10-4811-89d8-bd80a6ea8ed8
From: "test" <sip:anonymous@10.96.0.8>;tag=2bd4d5e6-0a36-44e8-966e-b01f5b55f49c
To: <sip:test@127.0.0.1>
Contact: <sip:anonymous@127.0.0.1:5060>
Call-ID: 76311fb7-870f-4274-bc2a-5ef182b39670
CSeq: 30946 INVITE
Allow: OPTIONS, REGISTER, SUBSCRIBE, NOTIFY, PUBLISH, INVITE, ACK, BYE, CANCEL, UPDATE, PRACK, MESSAGE, REFER
Supported: 100rel, timer, replaces, norefersub, histinfo
Session-Expires: 1800
Min-SE: 90
VBOUT-Transport: 1111
...
</pre>
</pre>


Line 573: Line 655:
</pre>
</pre>


=== /channells/{channelId}/record POST ===
=== /channels/{channelId}/record POST ===
Start a recording. Record audio from a channel. Note that this will not capture audio sent to the channel. The bridge itself has a record feature if that's what you want.
Start a recording. Record audio from a channel. Note that this will not capture audio sent to the channel. The bridge itself has a record feature if that's what you want.


Line 600: Line 682:
* 422: The format specified is unknown on this system.
* 422: The format specified is unknown on this system.


=== /channels/{channelId}/play POST ===
Start playback of media. The media URI may be any of a number of URI's. Currently, sound:; recording:; number:; digits:; characters:; and tone: URI's are supported. This operation creates a playback resource that can be used to control the playback of media(pause, rewind, fast forward, etc.)


=== /channells/{channelId}/play POST ===
Path parameters(Parameters are case-sensitive)
* channelId: string: Channel's id.
 
Query parameters
* media: string: (required) Media URIs to play.
: Allows comma-separated values.
: sound:, recording:, number:, digits:, characters:, tone:
: For the tone, it reference the indications.conf file. If you want to play the busy tone, the Media URI should be the "tone:busy" or "tone:busy;<country>". Then the asterisk will repeat the given tone sound forever.
* lang: string: For sounds, selects language for sound.
* offsetms: int: Number of milliseconds to skip before playing. Only applies to the first URI if multiple media URIs are specified.
* skipms: int: Number of milliseconds to skip for forward/reverse operations.
: Default: 3000
* playbackId: string: Playback ID.
 
Error responses
* 404: Channel not found.
* 409: Channel not in a Stasis application.
* 412: Channel in an invalid state.


==== Example ====
==== Example ====
<pre>
<pre>
curl -X POST -u asterisk:asterisk -H 'Content-Type: application/json; charset=utf-8' localhost:8088/ari/channels/1548886670.0/play -d \
$ curl -X POST -u asterisk:asterisk -H 'Content-Type: application/json; charset=utf-8' localhost:8088/ari/channels/1548886670.0/play -d \
'{"media": ["sound:https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"]}'
'{"media": ["sound:https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"]}'


Line 614: Line 715:
     "state": "queued",
     "state": "queued",
     "target_uri": "channel:1548886670.0"
     "target_uri": "channel:1548886670.0"
}
</pre>
tone example. note that the tone play will keep repeat the sound.
<pre>
$ curl -X POST -u asterisk:asterisk localhost:8088/ari/channels/asterisk-call-575f54fdc4-q6f4x-1646244217.38000/play -H 'Content-Type: application/json; charset=utf-8' -d '{"media":["tone:busy"]}'
{
  "id": "82e60863-d079-4e4a-a9a2-37c041aa1d26",
  "media_uri": "tone:busy;us-old",
  "target_uri": "channel:asterisk-call-575f54fdc4-q6f4x-1646244217.38000",
  "language": "en",
  "state": "queued"
}
</pre>
=== /channels/{channelId}/snoop POST ===
==== Example ====
<pre>
$ curl -s -u asterisk:asterisk localhost:8088/ari/channels/asterisk-call-5765d977d8-c4k5q-1629250154.132/snoop \
  -H 'content-type: application/json' \
  -d '{"spy": "both", "whisper": "both", "app": "voipbin"}'
{
  "id": "asterisk-call-5765d977d8-c4k5q-1629607067.6639",
  "name": "Snoop/asterisk-call-5765d977d8-c4k5q-1629250154.132-00000000",
  "state": "Up",
  "caller": {
    "name": "",
    "number": ""
  },
  "connected": {
    "name": "",
    "number": ""
  },
  "accountcode": "",
  "dialplan": {
    "context": "default",
    "exten": "s",
    "priority": 1,
    "app_name": "",
    "app_data": ""
  },
  "creationtime": "2021-08-22T04:37:47.333+0000",
  "language": "en"
}
}
</pre>
</pre>
Line 651: Line 799:
{
{
     "value":"7486de53-1305-42a3-abc5-97a34626fe8e"
     "value":"7486de53-1305-42a3-abc5-97a34626fe8e"
}
</pre>
=== /channels/externalMedia POST ===
==== Example ====
<pre>
$ curl -s -X POST -u asterisk:asterisk 127.0.0.1:8088/ari/channels/externalMedia\?app=voipbin\&external_host=127.0.0.1:5090\&transport=udp\&format=ulaw
{
  "id": "asterisk-call-5765d977d8-c4k5q-1629605410.6626",
  "name": "UnicastRTP/127.0.0.1:5090-0x7f6d54035300",
  "state": "Down",
  "caller": {
    "name": "",
    "number": ""
  },
  "connected": {
    "name": "",
    "number": ""
  },
  "accountcode": "",
  "dialplan": {
    "context": "default",
    "exten": "s",
    "priority": 1,
    "app_name": "AppDial2",
    "app_data": "(Outgoing Line)"
  },
  "creationtime": "2021-08-22T04:10:10.331+0000",
  "language": "en",
  "channelvars": {
    "UNICASTRTP_LOCAL_PORT": "10492",
    "UNICASTRTP_LOCAL_ADDRESS": "127.0.0.1"
  }
}
</pre>
<pre>
curl -s -X POST -u asterisk:asterisk 127.0.0.1:8088/ari/channels/externalMedia \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{"app": "sdp", "external_host": "test.com:5060", "transport": "udp", "format": "ulaw", "connection_type": "client", "direction": "both", "encapsulation": "rtp"}'
{
  "id": "asterisk-call-688cdcbc46-qfxz9-1630689955.242",
  "name": "UnicastRTP/test.com-0x7fb1340012c0",
  "state": "Down",
  "caller": {
    "name": "",
    "number": ""
  },
  "connected": {
    "name": "",
    "number": ""
  },
  "accountcode": "",
  "dialplan": {
    "context": "default",
    "exten": "s",
    "priority": 1,
    "app_name": "AppDial2",
    "app_data": "(Outgoing Line)"
  },
  "creationtime": "2021-09-03T17:25:55.076+0000",
  "language": "en",
  "channelvars": {
    "UNICASTRTP_LOCAL_PORT": "10314",
    "UNICASTRTP_LOCAL_ADDRESS": "10.96.0.40"
  }
}
}
</pre>
</pre>
Line 657: Line 874:


== Endpoints ==
== Endpoints ==
=== /endpoints GET ===
==== example ====
<pre>
$ curl -X GET -u asterisk:asterisk localhost:8088/ari/endpoints
[
  {
    "technology": "PJSIP",
    "resource": "call-in",
    "state": "offline",
    "channel_ids": [
      "1589734169.2662",
      "1590042190.6700",
      "1590042642.6701"
    ]
  },
  {
    "technology": "PJSIP",
    "resource": "test",
    "state": "offline",
    "channel_ids": []
  },
  {
    "technology": "PJSIP",
    "resource": "dispatcher",
    "state": "offline",
    "channel_ids": []
  },
  {
    "technology": "PJSIP",
    "resource": "call-out",
    "state": "offline",
    "channel_ids": []
  }
]
</pre>


== Events ==
== Events ==

Latest revision as of 04:49, 3 March 2022

Overview

Asterisk ARI(Asterisk REST Interface) 내용 정리.

Basic

Asterisk-12 버전부터는 ARI(Asterisk REST Interface) 를 지원한다.

기본 사용포트 및 base uri 은 다음과 같다.

http://localhost:8088/ari

Applications

/applications GET

List all applications.

Example

Normal

$ curl -X GET -u asterisk:asterisk localhost:8088/ari/applications

[
  {
    "name": "test",
    "channel_ids": [
      "__AST_CHANNEL_ALL_TOPIC"
    ],
    "bridge_ids": [
      "__AST_BRIDGE_ALL_TOPIC"
    ],
    "endpoint_ids": [
      "__AST_ENDPOINT_ALL_TOPIC"
    ],
    "device_names": [
      "__AST_DEVICE_STATE_ALL_TOPIC"
    ],
    "events_allowed": [],
    "events_disallowed": []
  }
]

/applications/{applicationName} GET

Get detail of an application.

Path parameters

  • applicationName: string - Application's name.

Error responses

  • 404 : Application does not exist.

Example

Normal

$ curl -X GET -u asterisk:asterisk http://192.168.30.10:8088/ari/applications/test

{
  "name": "test",
  "channel_ids": [
    "__AST_CHANNEL_ALL_TOPIC"
  ],
  "bridge_ids": [
    "__AST_BRIDGE_ALL_TOPIC"
  ],
  "endpoint_ids": [
    "__AST_ENDPOINT_ALL_TOPIC"
  ],
  "device_names": [
    "__AST_DEVICE_STATE_ALL_TOPIC"
  ],
  "events_allowed": [],
  "events_disallowed": []
}

/applications/{applicationName}/subscription POST

Subscribe an application to a event source. Returns the state of the application after the subscriptions have changed.

Path parameters(parameters are case-sensitive)

  • applicationName: string - Application's name

Query parameters

  • eventSource: string - (required) URI for event source (channel: {channelId}, bridge: {bridgeId}, endpoint: {tech}[/{resource}], deviceState:{deviceName}
Allows comma separated values.

Error responses

  • 400: Missing parameter.
  • 404: Application does not exist.
  • 422: Event source does not exist.

Example

$ curl -X POST -u asterisk:asterisk http://localhost:8088/ari/applications/test/subscription -H 'content-type: application/json' \
  -d '{"eventSource": "endpoint:PJSIP"}'

{
    "bridge_ids": [
        "__AST_BRIDGE_ALL_TOPIC"
    ],
    "channel_ids": [
        "__AST_CHANNEL_ALL_TOPIC"
    ],
    "device_names": [
        "__AST_DEVICE_STATE_ALL_TOPIC"
    ],
    "endpoint_ids": [
        "__AST_ENDPOINT_ALL_TOPIC"
    ],
    "events_allowed": [],
    "events_disallowed": [],
    "name": "test"
}

/applications/{applicationName}/subscription DELETE

Unsubscribe an application from an event source. Returns the state of the application after the subscription have changed.

Path parameters(parameters are case-sensitive)

  • applicationName: string - Application's name

Query parameters

  • eventSource: string - (required) URI for event source (channel: {channelId}, bridge: {bridgeId}, endpoint: {tech}[/{resource}], deviceState:{deviceName}
Allows comma separated values.

Error responses

  • 400: Missing parameter.
  • 404: Application does not exist.
  • 409: Application not subscribed to event source.
  • 422: Event source does not exist.

Example

$ curl -X DELETE -u asterisk:asterisk http://localhost:8088/ari/applications/test/subscription -H 'content-type: application/json' -d '{"eventSource": "endpoint:PJSIP"}'

{
    "bridge_ids": [
        "__AST_BRIDGE_ALL_TOPIC"
    ],
    "channel_ids": [
        "__AST_CHANNEL_ALL_TOPIC"
    ],
    "device_names": [
        "__AST_DEVICE_STATE_ALL_TOPIC"
    ],
    "endpoint_ids": [],
    "events_allowed": [],
    "events_disallowed": [],
    "name": "test"
}

Asterisk

/asterisk/info GET

Gets Asterisk system information.

Query parameters

  • only: string: Filter information returned.
Allowed values: build, system, config, status
Allows comma separated values.

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/asterisk/info

{
    "build": {
        "date": "2019-01-08 14:16:26 UTC",
        "kernel": "4.9.0-8-amd64",
        "machine": "x86_64",
        "options": "OPTIONAL_API",
        "os": "Linux",
        "user": "pchero"
    },
    "config": {
        "default_language": "en",
        "name": "",
        "setid": {
            "group": "",
            "user": ""
        }
    },
    "status": {
        "last_reload_time": "2019-01-11T08:04:11.203+0000",
        "startup_time": "2019-01-11T08:04:11.203+0000"
    },
    "system": {
        "entity_id": "42:01:0a:84:00:12",
        "version": "GIT-master-cb214713c0M"
    }
}

/asterisk/modules GET

List Asterisk modules

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/asterisk/modules

[
    {
        "description": "Named ACL system",
        "name": "acl",
        "status": "Running",
        "support_level": "core",
        "use_count": 2
    },
    {
        "description": "Asterisk ADSI Programming Application",
        "name": "app_adsiprog.so",
        "status": "Running",
        "support_level": "deprecated",
        "use_count": 0
    },
    ...
]

/asterisk/modules/{moduleName} GET

Get Asterisk module information.

Path parameters(Parameters are case-sensitive)

  • moduleName: string: Module's name

Error responses

  • 404: Module could not be found in running modules.
  • 409: Module information could not be retrieved.

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/asterisk/modules/res_pjsip.so

{
    "description": "Basic SIP resource",
    "name": "res_pjsip.so",
    "status": "Running",
    "support_level": "core",
    "use_count": 46
}

Bridges

/bridges GET

List all active bridges in Asterisk.

Example

$ curl -s -X GET -u asterisk:asterisk localhost:8088/ari/bridges | python -m json.tool
[
    {
        "bridge_class": "stasis",
        "bridge_type": "mixing",
        "channels": [],
        "creator": "Stasis",
        "id": "3b925a5a-c464-4fc1-8fd9-8dc5dd330284",
        "name": "",
        "technology": "simple_bridge",
        "video_mode": "none"
    },
    {
        "bridge_class": "stasis",
        "bridge_type": "mixing",
        "channels": [],
        "creator": "Stasis",
        "id": "1beb554c-d752-4b16-b1d9-91b3f1375562",
        "name": "",
        "technology": "simple_bridge",
        "video_mode": "none"
    },
    {
        "bridge_class": "stasis",
        "bridge_type": "mixing",
        "channels": [],
        "creator": "Stasis",
        "id": "edfc58b1-1130-42c3-8117-0ca6d9e279f1",
        "name": "",
        "technology": "simple_bridge",
        "video_mode": "none"
    }
]

/bridges POST

Create a new bridge. This bridge persists until it has been shut down, or Asterisk has been shut down.

Query parameters

  • type: string : Comma separated list of bridge type attributes(mixing, holding, dtmf_events, proxy_media, video_sfu).
  • bridgeId: string : Unique ID to give to the bridge being created.
  • name: string : Name to give to the bridge being created.

Example

$ curl -s -X POST -u asterisk:asterisk localhost:8088/ari/bridges | python -m json.tool
{
    "bridge_class": "stasis",
    "bridge_type": "mixing",
    "channels": [],
    "creator": "Stasis",
    "id": "edfc58b1-1130-42c3-8117-0ca6d9e279f1",
    "name": "",
    "technology": "simple_bridge",
    "video_mode": "talker"
}

/bridges/{bridge_id} DELETE

Example

$ curl -v --request DELETE \
  --url http://127.0.0.1:8088/ari/bridges/3fe59477-88fa-4fa6-a6d2-81a7dafda249 \
  -u asterisk:asterisk \
  --header 'content-type: application/json'

*   Trying 127.0.0.1:8088...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 8088 (#0)
* Server auth using Basic with user 'asterisk'
> DELETE /ari/bridges/3fe59477-88fa-4fa6-a6d2-81a7dafda249 HTTP/1.1
> Host: 127.0.0.1:8088
> Authorization: Basic YXN0ZXJpc2s6YXN0ZXJpc2s=
> User-Agent: curl/7.68.0
> Accept: */*
> content-type: application/json
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 204 No Content
< Server: asterisk
< Date: Sun, 30 Aug 2020 18:00:02 GMT
< Cache-Control: no-cache, no-store
< Content-Length: 0
< 
* Connection #0 to host 127.0.0.1 left intact

/bridges/{bridggeId}/addChannel POST

Add a channel to a bridge.

Path parameters

  • bridgeId: string : Bridge's Id.

Query parameters

  • channel: string : (required) Ids of channels to add to bridge.
Allows comma-separated values.
  • role: string : Channel's role in the bridge.
  • absorbDTMF: boolean : Absorb DTMF coming from this channel, preventing it to pass through to the bridge.
  • mute: boolean : Mute audio from this channel, preventing it to pass through to the bridge.
  • inhibitConnectedLineUpdates: boolean : Do not present the identity of the newly connected channel to other bridge members.

/bridges/{bridgeId}/record POST

Start a recording. This record the mixed audio from all channels participating in this bridge.

Path parameters

  • bridgeid: string : Bridge's Id.

Query parameters

  • name: string : (required) Recording's filename.
  • format: string : (required) Format to encode audio in.
  • maxDurationSeconds: int : Maximum duration of the recording, in seconds. 0 for no limit.
Allowed range: Min: 0; Max: None.
  • maxSilenceSeconds: int : Maximum duration of the silence, in seconds. 0 for no limit.
Allowed range: Min: 0; Max: None.
  • ifExists: string : Action to take if a recording with the same name already exists.
Default: fail
Allowed values: fail, overwrite, append.
  • beep: boolean : Play beep when recording begins.
  • terminateOn: string : DTMF input to terminate recording.
Default: None.
Allowed values: none, any, *, #.

Exmaples

curl -X "POST" "http://localhost:8088/ari/bridges/e2e8dc59-8a2a-4729-848a-d4926bd08876/record" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'asterisk:asterisk' \
     -d $'{
  "name": "testrecording-202002101204",
  "format": "wav"
}'

HTTP/1.1 201 Created
Server: Asterisk
Date: Mon, 10 Feb 2020 11:05:26 GMT
Connection: close
Cache-Control: no-cache, no-store
Location: /ari/recordings/live/testrecording-202002101204
Content-type: application/json
Content-Length: 128

{"name":"testrecording-202002101204","format":"wav","state":"queued","target_uri":"bridge:e2e8dc59-8a2a-4729-848a-d4926bd08876"}

Channels

/channels GET

Example

$ curl localhost:8088/ari/channels

[
  {
    "id": "test_call",
    "name": "PJSIP/sipp-uac-00000000",
    "state": "Up",
    "caller": {
      "name": "",
      "number": ""
    },
    "connected": {
      "name": "",
      "number": ""
    },
    "accountcode": "",
    "dialplan": {
      "context": "sipp-uac",
      "exten": "s",
      "priority": 1
    },
    "creationtime": "2019-03-15T23:16:26.026+0100",
    "language": "en"
  }
]

/channels POST

Create a new channel(originate). The new channel is created immediately and a snapshot of it returned. If a Stasis application is provided it will be automatically subscribed to the originated for further events and updates.

Query parameters

  • endpoint: string - (required) Endpoint to call.
  • extension: string - The extension to dial after the endpoint answers. Mutually exclusive with 'app'.
  • context: string - The context to dial after the endpoint answers. If omitted, uses 'default'. Mutually exclusive with 'app'.
  • priority: long - The priority to dial after the endpoint answers. If omitted, uses 1. Mutually exclusive with 'app'.
  • label: string - The label to dial after the endpoint answers. Will supersede 'priority' if provided. Mutually exclusive with 'app'.
  • app: string - The application that is subscribed to the originated channel. When the channel is answered, it will be passed to this Stasis application. Mutually exclusive with 'context', 'extension', 'priority' and 'label'.
  • appArgs: string - The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.
  • callerid: string - CallerID to use when dialing the endpoint or extension.
이 항목을 설정하게 되면 SIP INVITE 메시지의 FROM header 가 변경되게 된다. 아래와 같이 설정하면 된다.
+0123456789
"pchero" <+0123456789>
  • timeout: int - Timeout(in seconds) before giving up dialing, or -1 for no timeout.
Default: 30
  • channelId: string - The unique id to assign the channel on creation.
  • otherChannelId: string - The unique id to assign the second channel when using local channels.
  • originator: string - The unique id of the channel which is originating this one.
  • formats: string - The format name capability list to use if originator is not specified. Ex. "ulaw, slin16". Format names can be found with "core show codecs".

Body parameter

  • variables: containers - The "variables" key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { "endpoint": "SIP/Alice", "variables": {"CALLERID(name)": "Alice"}}
만약 Custom SIP header 를 추가하고 싶다면 아래와 같이 하면 된다.
"variables": {
"CALLERID(all)": "test11111",
"PJSIP_HEADER(add,CustomSIPHeader)": "SIPHeader1111"
}


Error response

  • 400 : Invalid parameters for originating a channel.
  • 409 : Channel with given unique ID already exists.

Example

$ curl -X POST http://192.168.200.20:8088/ari/channels\?api_key=asterisk:asterisk\&endpoint=pjsip/test@sippuas\&app=test

{
	"id": "1543782963.26",
	"name": "PJSIP/sippuas-0000000d",
	"state": "Down",
	"caller": {
		"name": "",
		"number": ""
	},
	"connected": {
		"name": "",
		"number": ""
	},
	"accountcode": "",
	"dialplan": {
		"context": "sippuas",
		"exten": "s",
		"priority": 1
	},
	"creationtime": "2018-12-02T21:36:03.239+0100",
	"language": "en"
}

/channels/{channelId} GET

Example

$ curl localhost:8088/ari/channels/test_call
{
  "id": "test_call",
  "name": "PJSIP/sipp-uac-00000000",
  "state": "Up",
  "caller": {
    "name": "",
    "number": ""
  },
  "connected": {
    "name": "",
    "number": ""
  },
  "accountcode": "",
  "dialplan": {
    "context": "sipp-uac",
    "exten": "s",
    "priority": 1
  },
  "creationtime": "2019-03-15T23:16:26.026+0100",
  "language": "en"
}

/channels/{channelId}/answer POST

Example

$ curl -X POST -u asterisk:asterisk localhost:8088/ari/channels/1548886670.0/answer

/channels/{channelId}/continue POST

Exit application; continue execution in the dialplan.

Path parameters(Parameters are case-sensitive)

  • channelId: string - Channel's Id

Query parameters

  • context: string - The context to continue to.
  • extension: string - The extension to continue to.
  • priority: int - The priority to continue to.
  • label: string - The label to continue to - will supersede 'priority' if both are provided.

Error responses

  • 404: Channel not found
  • 409: Channel not in a Stasis application.
  • 412: Channel in invalid state.

Example

Normal

$ curl -X POST http://192.168.200.20:8088/ari/channels/1543782963.26/continue\?api_key=asterisk:asterisk

No channel info

~$ curl -X POST http://192.168.200.20:8088/ari/channels/1543782963.26/continue\?api_key=asterisk:asterisk

{"message":"Channel not in Stasis application"}

/channels/{channelId}/create POST

Create channel.

Query parameters

  • endpoint: string - (required) Endpoint for channel communication.
  • app: string - (required) Stasis Application to place channel into.
  • appArgs: string - The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.
  • channelId: string - The unique id to assign the channel on creation.
  • otherChannelId: string - The unique id to assign the second channel when using local channels.
  • originator: string - Unique ID of the calling channel.
  • formats: string - The format name capability list to use if originator is not specified. Ex. "ulaw,slin16". Format names can be found with "core show codecs".

Error responses

  • 409: Channel with given unique ID already exists.

Example

Normal

## Asterisk - test_call2: create channel only
curl -X "POST" "http://localhost:8088/ari/channels/create" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'asterisk:asterisk' \
     -d $'{
  "appArgs": "pchero_dialed=1",
  "channelId": "test_call2",
  "app": "pchero_voip",
  "endpoint": "PJSIP/pchero-voip/sip:test@127.0.0.1",
  "callerId": "pchero"
}'

{
    "accountcode": "",
    "caller": {
        "name": "",
        "number": ""
    },
    "connected": {
        "name": "",
        "number": ""
    },
    "creationtime": "2019-02-25T13:37:26.509+0000",
    "dialplan": {
        "context": "pchero-voip",
        "exten": "s",
        "priority": 1
    },
    "id": "test_call2",
    "language": "en",
    "name": "PJSIP/pchero-voip-00000049",
    "state": "Down"
}

Create a channel with SIP headers

curl --location --request POST '127.0.0.1:8088/ari/channels' \
--header 'Authorization: Basic YXN0ZXJpc2s6YXN0ZXJpc2s=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "endpoint": "pjsip/test/sip:test@127.0.0.1:5061",
    "app": "test",
    "appArgs": "context=call-out,call_id=35975fa4-d474-4a8b-9def-8d978eda5dbc",
    "channelId": "test_channel",
    "callerId": "test",
    "variables": {
        "CALLERID(all)": "test11111",
        "PJSIP_HEADER(add,VBOUT-Transport)": "1111"
    }
}'

2021/02/19 08:22:09.226759 127.0.0.1:5060 -> 127.0.0.1:5061
INVITE sip:test@127.0.0.1:5061 SIP/2.0
Via: SIP/2.0/UDP 127.0.0.1:5060;branch=z9hG4bKPjae4830dc-4a10-4811-89d8-bd80a6ea8ed8
From: "test" <sip:anonymous@10.96.0.8>;tag=2bd4d5e6-0a36-44e8-966e-b01f5b55f49c
To: <sip:test@127.0.0.1>
Contact: <sip:anonymous@127.0.0.1:5060>
Call-ID: 76311fb7-870f-4274-bc2a-5ef182b39670
CSeq: 30946 INVITE
Allow: OPTIONS, REGISTER, SUBSCRIBE, NOTIFY, PUBLISH, INVITE, ACK, BYE, CANCEL, UPDATE, PRACK, MESSAGE, REFER
Supported: 100rel, timer, replaces, norefersub, histinfo
Session-Expires: 1800
Min-SE: 90
VBOUT-Transport: 1111
...

/channels/{channelId}/dial POST

Dial a created channel.

Path parameters(Parameters are case-sensitive)

  • ChannelId: string - Channel's id.

Query parameters

  • caller: string - Channel ID of caller.
  • timeout: int - Dial timeout.
Allowed range: Min: 0, Max: None

Example

Normal

## Asterisk - test_call: dial to test_call2
curl -X "POST" "http://localhost:8088/ari/channels/test_call/dial" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'asterisk:asterisk' \
     -d $'{
  "channelId": "test_call2"
}'

/channels/{channelId}/record POST

Start a recording. Record audio from a channel. Note that this will not capture audio sent to the channel. The bridge itself has a record feature if that's what you want.

Path parameters(Parameters are case-sensitive)

  • chanelId: string: Channel's Id.

Query parameters

  • name: string: (required)Recording's filename.
  • format: string: (required)Format to encode audio in.
  • maxDurationSeconds: int: Maximum duration of the recording, in seconds. 0 for no limit.
Allowed range: Min: 0, Max: None
  • maxSilenceSeconds: int: Maximum duration of silence, in seconds, 0 for no limit
Allowed range: Min: 0, Max: None
  • ifExists: string: Action to take if a recording with the same name already exists.
Default: fail
Allowed values: fail, overwrite, append
  • beep: boolean: Play beep when recording begins.
  • terminateOn: string: DTMF input to terminate recording.
Default: none
Allowed value: non, any, *, #

Error responses

  • 400: Invalid parameters.
  • 404: Channel not found.
  • 409: Channel is not in a Stasis application; the channel is currently bridged with other channels; A recording with the same name already exists on the system and can not be overwritten because it is in progess or ifExists=fail.
  • 422: The format specified is unknown on this system.

/channels/{channelId}/play POST

Start playback of media. The media URI may be any of a number of URI's. Currently, sound:; recording:; number:; digits:; characters:; and tone: URI's are supported. This operation creates a playback resource that can be used to control the playback of media(pause, rewind, fast forward, etc.)

Path parameters(Parameters are case-sensitive)

  • channelId: string: Channel's id.

Query parameters

  • media: string: (required) Media URIs to play.
Allows comma-separated values.
sound:, recording:, number:, digits:, characters:, tone:
For the tone, it reference the indications.conf file. If you want to play the busy tone, the Media URI should be the "tone:busy" or "tone:busy;<country>". Then the asterisk will repeat the given tone sound forever.
  • lang: string: For sounds, selects language for sound.
  • offsetms: int: Number of milliseconds to skip before playing. Only applies to the first URI if multiple media URIs are specified.
  • skipms: int: Number of milliseconds to skip for forward/reverse operations.
Default: 3000
  • playbackId: string: Playback ID.

Error responses

  • 404: Channel not found.
  • 409: Channel not in a Stasis application.
  • 412: Channel in an invalid state.

Example

$ curl -X POST -u asterisk:asterisk -H 'Content-Type: application/json; charset=utf-8' localhost:8088/ari/channels/1548886670.0/play -d \
'{"media": ["sound:https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"]}'

{
    "id": "bbd2b76c-091d-4b13-bb9d-982ddeec53d5",
    "language": "en",
    "media_uri": "sound:https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav",
    "state": "queued",
    "target_uri": "channel:1548886670.0"
}

tone example. note that the tone play will keep repeat the sound.

$ curl -X POST -u asterisk:asterisk localhost:8088/ari/channels/asterisk-call-575f54fdc4-q6f4x-1646244217.38000/play -H 'Content-Type: application/json; charset=utf-8' -d '{"media":["tone:busy"]}'

{
  "id": "82e60863-d079-4e4a-a9a2-37c041aa1d26",
  "media_uri": "tone:busy;us-old",
  "target_uri": "channel:asterisk-call-575f54fdc4-q6f4x-1646244217.38000",
  "language": "en",
  "state": "queued"
}

/channels/{channelId}/snoop POST

Example

$ curl -s -u asterisk:asterisk localhost:8088/ari/channels/asterisk-call-5765d977d8-c4k5q-1629250154.132/snoop \
  -H 'content-type: application/json' \
  -d '{"spy": "both", "whisper": "both", "app": "voipbin"}'

{
  "id": "asterisk-call-5765d977d8-c4k5q-1629607067.6639",
  "name": "Snoop/asterisk-call-5765d977d8-c4k5q-1629250154.132-00000000",
  "state": "Up",
  "caller": {
    "name": "",
    "number": ""
  },
  "connected": {
    "name": "",
    "number": ""
  },
  "accountcode": "",
  "dialplan": {
    "context": "default",
    "exten": "s",
    "priority": 1,
    "app_name": "",
    "app_data": ""
  },
  "creationtime": "2021-08-22T04:37:47.333+0000",
  "language": "en"
}

/channels/{channelId}/variable GET

Get the value of a channel variable or function.

You can see the more available channel variables are here

Path Parameters

  • channelId : string : Channel's id.

Query parameters

  • variable : string : (required) The channel variable or function to get.

Example

$ curl -s -u asterisk:asterisk localhost:8088/ari/channels/test_call/variable\?variable=CHANNEL\(rtcp,all_loss\) | python -m json.tool

{
    "value": "minrxlost=0.000000;maxrxlost=8.000000;avgrxlost=0.024691;stdevrxlost=inf;reported_minlost=0.000000;reported_maxlost=0.000000;reported_avglost=0.000000;reported_stdevlost=0.000000;"
}
$ curl -s -u asterisk:asterisk localhost:8088/ari/channels/test_call/variable\?variable=CHANNEL\(rtcp,all\) | python -m json.tool

{
    "value":"ssrc=528427381;themssrc=487275306;lp=8;rxjitter=0.000000;rxcount=96231;txjitter=0.001051;txcount=900;rlp=0;rtt=0.000000"
}
$ curl -s -u asterisk:asterisk localhost:8088/ari/channels/test_call/variable\?variable=CHANNEL\(pjsip,call-id\) | python -m json.tool

{
    "value":"7486de53-1305-42a3-abc5-97a34626fe8e"
}

/channels/externalMedia POST

Example

$ curl -s -X POST -u asterisk:asterisk 127.0.0.1:8088/ari/channels/externalMedia\?app=voipbin\&external_host=127.0.0.1:5090\&transport=udp\&format=ulaw

{
  "id": "asterisk-call-5765d977d8-c4k5q-1629605410.6626",
  "name": "UnicastRTP/127.0.0.1:5090-0x7f6d54035300",
  "state": "Down",
  "caller": {
    "name": "",
    "number": ""
  },
  "connected": {
    "name": "",
    "number": ""
  },
  "accountcode": "",
  "dialplan": {
    "context": "default",
    "exten": "s",
    "priority": 1,
    "app_name": "AppDial2",
    "app_data": "(Outgoing Line)"
  },
  "creationtime": "2021-08-22T04:10:10.331+0000",
  "language": "en",
  "channelvars": {
    "UNICASTRTP_LOCAL_PORT": "10492",
    "UNICASTRTP_LOCAL_ADDRESS": "127.0.0.1"
  }
}
curl -s -X POST -u asterisk:asterisk 127.0.0.1:8088/ari/channels/externalMedia \
 -H 'Content-Type: application/json; charset=utf-8' \
 -d '{"app": "sdp", "external_host": "test.com:5060", "transport": "udp", "format": "ulaw", "connection_type": "client", "direction": "both", "encapsulation": "rtp"}'

{
  "id": "asterisk-call-688cdcbc46-qfxz9-1630689955.242",
  "name": "UnicastRTP/test.com-0x7fb1340012c0",
  "state": "Down",
  "caller": {
    "name": "",
    "number": ""
  },
  "connected": {
    "name": "",
    "number": ""
  },
  "accountcode": "",
  "dialplan": {
    "context": "default",
    "exten": "s",
    "priority": 1,
    "app_name": "AppDial2",
    "app_data": "(Outgoing Line)"
  },
  "creationtime": "2021-09-03T17:25:55.076+0000",
  "language": "en",
  "channelvars": {
    "UNICASTRTP_LOCAL_PORT": "10314",
    "UNICASTRTP_LOCAL_ADDRESS": "10.96.0.40"
  }
}

Devicestates

Endpoints

/endpoints GET

example

$ curl -X GET -u asterisk:asterisk localhost:8088/ari/endpoints

[
  {
    "technology": "PJSIP",
    "resource": "call-in",
    "state": "offline",
    "channel_ids": [
      "1589734169.2662",
      "1590042190.6700",
      "1590042642.6701"
    ]
  },
  {
    "technology": "PJSIP",
    "resource": "test",
    "state": "offline",
    "channel_ids": []
  },
  {
    "technology": "PJSIP",
    "resource": "dispatcher",
    "state": "offline",
    "channel_ids": []
  },
  {
    "technology": "PJSIP",
    "resource": "call-out",
    "state": "offline",
    "channel_ids": []
  }
]

Events

/events GET

Websocket connection for events.

Query parameters

  • app: string - (required) Applications to subscribe to.
Allows comma separated values.
  • subscribeAll: boolean - Subscribe to all Asterisk events. If provided, the applications listed will be subscribed to all events, effectively disabling the application specific subscriptions.
Default: false

Example

ws://192.168.200.20:8088/ari/events?api_key=asterisk:asterisk&app=test
ws://192.168.200.20:8088/ari/events?api_key=asterisk:asterisk&app=test&subscribeAll=true

Mailboxes

Playbacks

Recordings

/recordings/live/{recordingName} GET

List live recordings.

Path parameters

  • recordingName: string : The name of the recording.

Examples

$ curl "http://localhost:8088/ari/recordings/live/testrecording-202002101246" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'asterisk:asterisk' \
     -d $'{
  "name": "testrecording-202002101204",
  "format": "wav"
}'


HTTP/1.1 200 OK
Server: Asterisk
Date: Mon, 10 Feb 2020 11:47:12 GMT
Connection: close
Cache-Control: no-cache, no-store
Content-type: application/json
Content-Length: 131

{"name":"testrecording-202002101246","format":"wav","state":"recording","target_uri":"bridge:c5630d1d-ef94-4582-bcb5-4175385e9eb2"}

/recordings/live/{recordingName}/mute DELETE

Unmute a live recording.

Path parameters

  • recordingName: string : The name of the recording.

Examples

## Recordings/live - unmute recordings
curl -X "DELETE" "http://localhost:8088/ari/recordings/live/testrecording-202002101258/mute" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'asterisk:asterisk'

HTTP/1.1 204 No Content
Server: Asterisk
Date: Mon, 10 Feb 2020 12:00:15 GMT
Connection: close
Cache-Control: no-cache, no-store
Content-Length: 0

/recordings/live/{recordingName}/mute POST

Mute a live recording. Muting a recording suspends silence detection, which will be restarted when the recording is unmuted.

진행중인 레코딩을 묵음(mute) 모드로 바꾼다. Mute 모드 시, 레코딩 중단이 아니기에 레코딩은 계속 진행되며, 묵음(slience)이 녹음된다.

Path parameters

  • recordingName: string : The name of the recording.

Examples

## Recordings/live - mute recordings
curl -X "POST" "http://localhost:8088/ari/recordings/live/testrecording-202002101258/mute" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'asterisk:asterisk'

HTTP/1.1 204 No Content
Server: Asterisk
Date: Mon, 10 Feb 2020 11:59:13 GMT
Connection: close
Cache-Control: no-cache, no-store
Content-Length: 0

/recordings/live/{recordingName}/pause DELETE

Unpause a live recording.

Pause 된 레코딩을 다시 시작한다.

Path parameters

  • recordingName: string : The name of the recording.

Examples

## Recordings/live - unpause live recordings
curl -X "DELETE" "http://localhost:8088/ari/recordings/live/testrecording-202002101246/pause" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'asterisk:asterisk'

HTTP/1.1 204 No Content
Server: Asterisk
Date: Mon, 10 Feb 2020 11:51:22 GMT
Connection: close
Cache-Control: no-cache, no-store
Content-Length: 0

/recordings/live/{recordingName}/pause POST

Pause a live recording. Pausing a recording suspends silence detection, which will be restarted when the recording is unpaused. Paused time is not included in the accounting for maxDurationSeconds.

레코딩을 잠시 중단(pause)한다. 중단시킨 시간은 maxDurationSeconds 에 포함되지 않으며 중단시킨 시간동안은 레코딩이 되지 않으므로 레코딩 파일의 play 시간에도 포함되지 않는다.

Path parameters

  • recordingName: string : The name of the recording

Examples

## Recordings/live - pause live recordings
curl -X "POST" "http://localhost:8088/ari/recordings/live/testrecording-202002101246/pause" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'asterisk:asterisk'

HTTP/1.1 204 No Content
Server: Asterisk
Date: Mon, 10 Feb 2020 11:50:05 GMT
Connection: close
Cache-Control: no-cache, no-store
Content-Length: 0

/recordings/stored GET

List recordings that are complete.

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/recordings/stored

[
    {
        "format": "wav",
        "name": "test_call"
    }
]

/recordings/stored/{recordingName} DELETE

Delete a stored recording.

Path parameters

  • recordingName: string: The name of the recording.

Error responses

  • 404: Recording not found.

Examples

Normal

$ curl -X DELETE -u asterisk:asterisk http://localhost:8088/ari/recordings/stored/test_call

Not found

$ curl -X DELETE -u asterisk:asterisk http://localhost:8088/ari/recordings/stored/test_call
{"message":"Recording not found"}

/recordings/stored/{recording name} GET

Get a stored recording's details.

Path parameters

  • recording name: string: The name of the recording.

Error response

  • 404: Recording not found

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/recordings/stored/test_call

{
    "format": "wav",
    "name": "test_call"
}

Sounds

/sounds GET

List all sounds.

Query parameters

  • lang: string: Lookup sound for specific language.
  • format: string: Lookup sound in a specific format.

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/sounds

[
    {
        "formats": [
            {
                "format": "gsm",
                "language": "en"
            }
        ],
        "id": "conf-now-unmuted",
        "text": "The conference is now unmuted."
    },
    {
        "formats": [
            {
                "format": "gsm",
                "language": "en"
            }
        ],
        "id": "queue-minutes",
        "text": "minutes"
    },
    ...
]

/sounds/{soundId} GET

Get a sound's details.

Path parameters(case-sensitive)

  • sound: string: Sound's id.

Examples

$ curl -X GET -u asterisk:asterisk http://localhost:8088/ari/sounds/demo-thanks

{
    "formats": [
        {
            "format": "gsm",
            "language": "en"
        }
    ],
    "id": "demo-thanks",
    "text": "Goodbye.  Thank you for trying out the Asterisk Open Source PBX."
}

See also