# 创建坐席分机

## 接口描述

创建一个坐席分机。坐席用它登录微信小程序、软电话或 SIP 话机接听/拨打。

分机号在同一 SIP 域名内全局唯一：不能与已有的坐席分机、设备分机、呼叫中心号码重复。坐席分机数量受公司配额限制。

通过 `voip_group_id` 指定所属对讲分组；不传或传 `0` 表示公司级默认分组。对讲分组的概念参见[遍历对讲分组](/voip/遍历对讲分组.md)。

## 请求说明
| 接口ID | 协议 | 方法 | PATH |
| --- | --- | --- | --- |
| 101 | HTTPS | POST | /openapi/v1/voip/agents |

### PATH参数

无

### URL参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| accesskey_id | string | 是 | 参见[签名认证](/签名认证.md) |
| expires | int | 是 | 参见[签名认证](/签名认证.md) |
| signature | string | 是 | 参见[签名认证](/签名认证.md) |

### HTTP请求头
| 名称 | 必填 | 说明 |
| --- | --- | --- |
| Content-Type | 是 | `application/json` |

### 请求参数

请求参数以Json格式放置于Body中，如下：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| dial_id | string | 是 | 分机号，5-20 位，只能包含字母、数字及 `_.-` |
| password | string | 是 | 分机密码（SIP 注册与坐席登录使用） |
| display_name | string | 是 | 坐席显示名称 |
| remark | string | 否 | 备注 |
| voip_group_id | int | 否 | 所属对讲分组ID；不传或传 `0` 表示公司级默认分组 |
| agent_call_timeout | int | 否 | 坐席振铃时长（秒），即来电分配给该坐席后的等待接听时长；不传默认 20 |
| agent_wrap_up_time | int | 否 | 通话完毕后，再次接收呼叫的间隔（秒） |
| agent_reject_delay_time | int | 否 | 坐席拒绝后，再次接听呼叫的间隔（秒） |
| agent_busy_delay_time | int | 否 | 坐席忙时，再次接听呼叫的间隔（秒） |
| agent_no_answer_delay_time | int | 否 | 坐席无应答时，再次接听呼叫的间隔（秒） |

> 坐席分机创建后默认为启用状态，坐席上下班（上线/下线）由坐席登录后自行操作（参见[坐席上下班](/voip/坐席上下班.md)）。

### 请求示例

```
POST https://open.vzicloud.com/openapi/v1/voip/agents?accesskey_id=8d9EsDAD2115Q5PM8tuP6g1IdAglkayp&expires=1619022787&signature=G29eTBjMm0gZF7cpXNLX7Hrn0yM%3D HTTP/1.1
Host: open.vzicloud.com
Content-Type: application/json

{
  "dial_id": "80001",
  "password": "80001pwd",
  "display_name": "客服-张三",
  "remark": "",
  "voip_group_id": 12,
  "agent_call_timeout": 20
}
```

## 返回说明

### 返回参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| id | int | 坐席分机ID |
| dial_id | string | 分机号 |
| display_name | string | 坐席显示名称 |
| enable | int | 启用状态（0:启用 / 1:停用） |
| remark | string | 备注 |
| agent_call_timeout | int | 坐席振铃时长（秒） |
| wx_online | int | 微信小程序端是否在线（0:离线 / 1:在线） |
| domain | string | SIP 域名（公司级如 `2.voip1.sip`，分组级如 `2.xiaoqu-a.voip1.sip`） |
| voip_group_id | int | 所属对讲分组ID；`0` = 公司级默认分组（与修改接口的 `voip_group_id` 取值一致） |
| voip_group_name | string | 所属对讲分组名称；公司级默认分组时为 `-` |
| pms_user_id | int | 关联的臻云账号用户ID；未关联时不返回该字段 |

**注：返回参数里可能还包含其他信息但未在上面的表格内列出，请勿使用！**

### 返回示例


```json
{
  "id": 501,
  "dial_id": "80001",
  "display_name": "客服-张三",
  "enable": 0,
  "remark": "",
  "agent_call_timeout": 20,
  "wx_online": 0,
  "domain": "2.xiaoqu-a.voip1.sip",
  "voip_group_id": 12,
  "voip_group_name": "小区A"
}
```