Asterisk manager API（AMI）文档(中文版)

Asterisk控制接口（AMI）允许管理客户端程序连接到一个asterisk实例并且可以通过TCP/IP流发送命令或读取事件。这在试图跟踪asterisk的状态或其中的电话客户端状态时很有用，AMI说明了客户端基于的一般(可能是动态的)规则。

一种简单的"key: value"协议用于已连接的管理客户端和asteriskＰＢＸ之间的信息传递。每行都用回车换行（/r/n）来结束。

协议特点：

在发送命令前，你必须建立一个连接。

在认证后，数据包任何时间都可以在两个方向上互相传输。

数据包第一行为"Action"时表明是由管理客户端发送到asterisk，第一行为"Event"或"Response"表明有asterisk发送到管理客户端。数据包内各行顺序可以变化，对数据包没有影响。

回车换行由于区分每一行，空行（两个连续回车换行）用于表明命令结束，Asterisk开始处理命令。

数据包类型：

数据包的类型通过一下几种关键字来划分

Action:一个由管理客户端发送到Asterisk的数据包，请求执行特定的动作。只有有限的几种动作供客户端使用，每个动作是由Asterisk服务器上的模块所决定的。一次只能执行一个动作，该动作数据包包含了动作名称以及执行所必需的参数。

Response:Asterisk对管理客户端动作的响应。

Event: 有关Asterisk核心或扩展模块发生事件的信息。

建立管理连接和用户身份验证：

为了与Asterisk进行管理通话，管理客户端必须建立到Asterisk服务器侦听端口（一般是5038）的TCP/IP连接，并使用登陆动作进行身份验证。这就要求在Asterisk服务器上创建用户账户，用户账户在/etc/asterisk/manager.conf中配置。账户由允许登陆的主机，登录密码以及被授予的权限列表组成。

登录和身份验证的经理，你必须发送一个" 登录 "行动，用您的用户名和秘密（密码作为参数）。 Here is an example:下面是一个例子：

Action: login
Username: admin
Secret: secret

你还可以通过"Events: off"阻止事件数据包发送到你的连接。例如：

Action: login
Username: admin
Secret: secret
Events: off

动作数据包：

向Asterisk发送动作时，额外的关键字可以提供进一步的动作信息。例如，你可能希望指定号码或通道的断开。此外，如果您的操作会导致Asterisk来执行拨号规则中的条目，你可以传递变量给拨号规则。这与你传递关键字的方式是一样的。

向Asterisk发送动作数据包时，按照以下格式：

Action: <action type><CRLF>
<Key 1>: <Value 1><CRLF>
<Key 2>: <Value 2><CRLF>
...
Variable: <Variable 1>=<Value 1><CRLF>
Variable: <Variable 2>=<Value 2><CRLF>
...
<CRLF>

管理动作（ Action ）：

通过CLI命令show manager commands的输出结果就是管理动作列表。

具体如下：

AbsoluteTimeout ：这个命令将要求Asterisk在指定秒数后挂断特定的通道，从而有效地结束通话。

参数：

Channel :哪些渠道挂断，如SIP/123-1c20

Timeout :到通道应挂断的秒数

例子：

请求信息

Action: AbsoluteTimeout

Channel: SIP/123-1c20

Timeout: 20

返回成功信息

Response: Success

Message: Timeout Set

返回失败信息

Response: Error

Message: No such channel

ChangeMonitor ：更改记录某通道信息文件名。

参数：

Channel：通道名称

File：文件名

例子：

发送请求

ACTION: ChangeMonitor

Channel: SIP/x7065558529-1c20

File: 20050103-140105_cc51

返回失败信息

Response: Error

Message: No such channel

返回成功信息

Response: Success

Message: Stopped monitoring channel

Command ：发送Asterisk CLI命令。

参数：

Command：Asterisk CLI 命令。

例子：

发送请求

ACTION: COMMAND

command: Show Channels

返回信息

Response: Follows

Channel (Context Extension Pri ) State Appl. Data

0 active channel(s)

--END COMMAND-

注意：返回的事件响应结果并不是发送一个回车换行（/r/n）,而只发送回车（/n）,如果你在中断处理程序中只等待回车换行，那么这条信息将会被被抛弃。

例如command返回信息如下：

Response: Follows/r/n
Channel Location State Application(Data)/n
SIP/x7065551212b-1af (None) Ringing AppDial((Outgoing Line))/n
SIP/x7065551212c-2aa 29@default:2 Ring Dial(SIP/x7065551212b)/n
2 active channels/n
1 active call/r/n
--END COMMAND--/r/n
/r/n

Events ：事件控制流，用于启用/禁用发送给管理客户端的事件。

参数：

EventMask: 'on'表示所有事件均会被发送到管理客户端。

'off'表示所有时间都不会被发送。

'system,call,log'用于选择被发送的事件。

提示：有些事件是启用或禁已经在.conf文件中配置了， They might be disabled by default.他们可能是默认为禁用。

例子：

注意在此例子中EventMask事件没有立即返回的响应信息，只有在设备注销时才返回相关信息。

发送请求：

ACTION: EVENTS
EVENTMASK: ON
返回信息：
Event: PeerStatus
Peer: SIP/ChannelName
PeerStatus: Unregistered
Cause: Expired

当EventMask参数为'off'时会立即返回响应信息，如下：

发送：

ACTION: EVENTS
EVENTMASK: OFF
返回：
Response: Events Off

ExtensionState ：检查分机的状态。

参数：Exten，Context，ActionID

例子：

发送：

ACTION: ExtensionState

Context: default

Exten: 2001

ActionID: 1

接收：

Response: Success

ActionID: 1

Message: Extension Status

Exten: 2001

Context: default

Hint: SIP/2001

Status: 0

Status状态代码：

-1 =扩展找不到

0 =空闲

1 =在使用

2 =忙

4 =不可用

8 =振铃

16 =正等待

GetVar：获取一个通道变量。

参数：Channel，Variable，actionID

ActionID是一个可选的参数匹配信息。

例子：

发送：

ACTION: GetVar

Channel: SIP/5060-44d225d0

Variable: extension

成功返回：

Response: Success

Value: 17065551419

失败返回：

Response: Error

Message: No such channel

或

Response: Success

varname: (null)

Hangup：挂断指定通道。

参数：Channel

例子：

发送：

ACTION: Hangup

Channel: SIP/x7065558529-99a0

接收：

Event: Unlink

Channel1: SIP/127.180.254.109-44df88e8

Channel2: SIP/x7065558529-99a0

Uniqueid1: 1124989110.20473

Uniqueid2: 1124989110.20474

Event: Hangup

Channel: SIP/x7065558529-99a0

Uniqueid: 1124989110.20474

Cause: 16

Event: Hangup

Channel: SIP/127.180.254.109-44df88e8

Uniqueid: 1124989110.20473

Cause: 16

Response: Success

Message: Channel Hungup

IAXpeers ：显示iax信息列表。

例子：

发送：

Action: IAXPeers

接收：

Name/Username Host Mask Port Status

8002 (Unspecified) (D) 255.255.255.255 0 UNKNOWN

8001 192.168.0.91 (D) 255.255.255.255 4569 OK (5 ms)

2 iax2 peers [1 online, 1 offline, 0 unmonitored]

ListCommands ：显示命令列表。

参数：ActionID

例子:

发送：

Action：ListCommands

接收：Response: Success

AbsoluteTimeout: Set Absolute Timeout (Priv: call,all)

AgentCallbackLogin: Sets an agent as logged in by callback (Priv: agent,all)

AgentLogoff: Sets an agent as no longer logged in (Priv: agent,all)

Agents: Lists agents and their status (Priv: agent,all)

ChangeMonitor: Change monitoring filename of a channel (Priv: call,all)

Command: Execute Asterisk CLI Command (Priv: command,all)

DBGet: Get DB Entry (Priv: system,all)

DBPut: Put DB Entry (Priv: system,all)

Events: Control Event Flow (Priv: )

ExtensionState: Check Extension Status (Priv: call,all)

Getvar: Gets a Channel Variable (Priv: call,all)

Hangup: Hangup Channel (Priv: call,all)

IAXnetstats: Show IAX Netstats (Priv: )

IAXpeers: List IAX Peers (Priv: )

ListCommands: List available manager commands (Priv: )

Logoff: Logoff Manager (Priv: )

MailboxCount: Check Mailbox Message Count (Priv: call,all)

MailboxStatus: Check Mailbox (Priv: call,all)

MeetmeMute: Mute a Meetme user (Priv: call,all)

MeetmeUnmute: Unmute a Meetme user (Priv: call,all)

Monitor: Monitor a channel (Priv: call,all)

Originate: Originate Call (Priv: call,all)

Park: Park a channel (Priv: call,all)

ParkedCalls: List parked calls (Priv: )

PauseMonitor: Pause monitoring of a channel (Priv: call,all)

Ping: Keepalive command (Priv: )

PlayDTMF: Play DTMF signal on a specific channel. (Priv: call,all)

QueueAdd: Add interface to queue. (Priv: agent,all)

QueuePause: Makes a queue member temporarily unavailable (Priv: agent,all)

QueueRemove: Remove interface from queue. (Priv: agent,all)

Queues: Queues (Priv: )

QueueStatus: Queue Status (Priv: )

Redirect: Redirect (transfer) a call (Priv: call,all)

SetCDRUserField: Set the CDR UserField (Priv: call,all)

Setvar: Set Channel Variable (Priv: call,all)

SIPpeers: List SIP peers (text format) (Priv: system,all)

SIPshowpeer: Show SIP peer (text format) (Priv: system,all)

Status: Lists channel status (Priv: call,all)

StopMonitor: Stop monitoring a channel (Priv: call,all)

UnpauseMonitor: Unpause monitoring of a channel (Priv: call,all)

UserEvent: Send an arbitrary event (Priv: user,all)

WaitEvent: Wait for an event to occur (Priv: )

ZapDialOffHook: Dial over channel while offhook (Priv: )

ZapDNDoff: Toggle channel Do Not Disturb status OFF (Priv: )

ZapDNDon: Toggle channel Do Not Disturb status ON (Priv: )

ZapHangup: Hangup Channel (Priv: )

ZapRestart: Fully Restart channels (terminates calls) (Priv: )

ZapShowChannels: Show status channels (Priv: )

ZapTransfer: Transfer Channel (Priv: )

Logoff ：注销管理客户端。

例子：

发送：

ACTION: LOGOFF

接收：

Response: Goodbye

Message: Thanks for all the fish.

MailboxCount ：检查语音信箱是否有新信息。

参数：MailBox，actionID

例子：

发送：

Action: MailboxCount

Mailbox: 2001@device

接收:

Response: Success

Message: Mailbox Message Count

Mailbox: 2001@device

NewMessages: 1

OldMessages: 0

MailboxStatus:检查语音信箱状态。

参数：MailBox，actionID

例子：

发送：

Action: MailboxStatus

Mailbox: 2001@device

接收:

Response: Success

Message: Mailbox Status

Mailbox: 2001@device

Waiting: 1

Monitor：监听某个通道。

参数：Channel, File, Format, Mix

例子：

发送:

ACTION: Monitor

Channel: SIP/x7062618529-643d

File: channelsavefile

Mix: 1

返回：

Response: Success

Message: Started monitoring channel

失败返回

Response: Error

Message: No such channel

Originate ：产生一个呼叫。(privilege: call,all)

参数：

Channel：呼叫连接产生的通道。

Context：呼叫连接所使用的Context（Context，Exten，Priority必须同时使用）

Exten： 呼叫连接所使用的分机（Context，Exten，Priority必须同时使用）

Priority：呼叫连接的优先级。（Context，Exten，Priority必须同时使用）

TimeOut：呼叫连接的超时（，单位为毫秒，默认为30000毫秒）

CallID：呼叫连接的来电显示。

Variable：通道变量设置。本地通道和连接通道都将被设置。

Account：呼叫所用密码。

Application：使用此次呼叫的应用程序。（使用参数和数据）

Data：应用程序参数所使用的数据。

Async：呼叫是否为异步。（允许多次调用不等待响应生成）

ActionID：请求标识符。 It allows you to identify the response to this request.它允许您确定这一请求的响应信息。 You may use a number or a string. Useful when you make several simultaneous requests.当您有用几个并发请求，您可以使用一个数字或字符串来区分。

事件的顺序:首先SGI通道鸣响，然后当他被接听后，通过上下文呼叫另一端的分机。注意超时只用于呼叫通道，呼叫分机时的超时另外指定。

使用异步导致1 OriginateResponse事件，包含了失败的原因。 Reason may be one of the following:原因可能是下列之一：
0 = no such extension or number 0 =没有这样的延长或编号
1 = no answer 1 =无应答
4 = answered 4 =回答
8 = congested or not available 8 =拥挤或不可用

例1（从SIP通道呼叫一个分机，这将导致外部呼叫无法产生直到sip通道挂断）

发送：

Action: Originate
Channel: SIP/101test
Context: default
Exten: 8135551212
Priority: 1
Callerid: 3125551212
Timeout: 30000
Variable: var1=23|var2=24|var3=25
ActionID: ABC45678901234567890

分机8135551212是外呼号码。这个例子表明了变量的使用方法

例2（从呼出通道呼叫一个本地分机，这将导致该分机不再响铃直到zap通道挂断）

发送：

Action: Originate

Channel: Zap/g2/8135551212

Context: default

Exten: 101

Priority: 1

Timeout: 30000

Callerid: 3125551212

101为一个本地分机号。

例3（运行系统命令）

发送：

Action: Originate
Channel: Local/1@dummy
Application: system
Data: /path/to/script

提示：如果你希望通道连接到任意分机和上下文，需要指定一个本地通道

ParkedCalls ：设置显示保持的呼叫列表。

参数：ActionID

发送：

Action: PakedCalls

返回：

Response: Success
Message: Parked calls will follow

Event: ParkedCallsComplete

Ping

例子：

发送：

Action: ping

返回：

Response: Pong

QueueAdd ：添加队列成员。

参数：

Queue：添加成员的队列名。

Interface: 成员名（例如sip/2001）

Penalty：数值，值越高越靠后。

Paused：暂停（true）或不暂停（false）

ActionID：（前面已介绍）

例子：

发送：

Action: QueueAdd
Queue: 200
Interface: sip/3001
Penalty: 1
Paused: true

返回：

Response: Success

Message: Added interface to queue

Event: QueueMemberAdded

Privilege: agent,all

Queue: 200

Location: sip/3001

MemberName: sip/3001

Membership: dynamic

Penalty: 1

CallsTaken: 0

LastCall: 0

Status: 5

Paused: 1

QueueRemove ：移除队列成员。

参数：

Queue：移除成员的队列名。

Interface: 成员名（例如sip/2001）

例子：

发送：

Action: QueueRemove
Queue: 200
Interface: sip/3001

返回：

Response: Success

Message: Removed interface from queue

Event: QueueMemberRemoved

Privilege: agent,all

Queue: 200

Location: sip/3001

MemberName: sip/3001

Queues ：返回全部队列的配置以及电话数据信息。

例子：

发送：

Action： Queues

返回：

200 has 0 calls (max unlimited) in 'ringall' strategy (0s holdtime), W:0, C:0, A:0, SL:0.0% within 0s

Members:

Local/2002@from-internal/n (Invalid) has taken no calls yet

Local/2003@from-internal/n (Invalid) has taken no calls yet

Local/2001@from-internal/n (Invalid) has taken no calls yet

No Callers

default has 0 calls (max unlimited) in 'ringall' strategy (0s holdtime), W:0, C:0, A:0, SL:0.0% within 0s

No Members

No Callers

上一篇： 鼠标屏幕取号开发原理

下一篇： 浅谈crm与IPPBX集成方式