帮我吧文档:数据接口:客户管理:联系人 [帮我吧开发文档]

联系人接口

为了支持比较复杂的自定义字段类型，我们对接口进行了升级，凡是接口名称中包含“_v2”的均为新接口，不包含的仍为旧接口，新接口的增加不对旧接口的逻辑产生任何影响，可放心使用旧接口。

新接口与旧接口的区别：

新接口新增了对“高级复选框”、“级联”类型的自定义字段的支持。
新接口的请求数据或返回值中如果包含下拉列表类型的字段，则传值为选项ID，旧接口则是选项内容。

JSON格式

名称	类型	只读	必填	注释
cId	int	是	否	联系人ID，系统自动生成
url	varchar	是	否	该联系人的url
name	varchar	否	否	姓名
mobile	varchar	否	是	手机号码，创建联系人时手机号码、座机号码任填写一个即可
fixnumber	varchar	否	是	座机号码，创建联系人时手机号码、座机号码任填写一个即可
email	varchar	否	否	邮件
position	varchar	否	否	职位
state	int	否	否	联系人状态（1-在职、2-离职、3-已删除）
QQ	varchar	否	否	QQ号码
note	varchar	否	否	联系人备注
companyId	int	是	否	联系人所属公司ID，如果是2B模式必填，2C模式不用填
uniqueId	varchar	是	否	联系人下的远程ID，远程客户端安装完毕后自动生成的。旧接口的返回值
uniqueIds	array	否	否	联系人下的远程ID及ID的备注。新接口的返回值
supportId	int	是	否	负责该联系人的客服ID，系统自动生成
createrId	int	否	否	创建人id
default	tinyint	否	否	是否是该公司的默认联系人，取值为：1-默认联系人，0-普通联系人
createDT	date	是	否	创建时间，格式为：2018-02-03 00:00:00
updateDT	date	是	否	更新时间，格式为：2018-02-03 00:00:00
custom_fields	array	否	否	联系人自定义字段
userGroup	int	否	否	联系人所属分组，2C模式下存在该字段，默认取值为0，即不属于任何分组，多个分组用,分隔
tableName	varchar	否	否	标签，多个英⽂逗号隔开

JSON示例

{
  "cId": 1,
  "url": "https://www.bangwo8.com/api/v1/users_v2/1.json",
  "name": "张三",
  "mobile": "13240138429",
  "email": "234576@163.com",
  "fixnumber": "010-63701717",
  "position": "项目经理",
  "QQ": "601100987",
  "note": "这里是联系人的备注",
  "companyId": 123,
  "uniqueId": "291045895",
  "supportId": 3,
  "createDT": "2017-09-12 10:12:22",
  "updateDT": "2017-09-12 10:12:22",
  "custom_fields": [
      {
	"key": "field_1",
	"value": "4334"
      },
      {
	"key": "field_3",//复选框
	"value": "是" 
      },
      {
	"key": "field_2",//下拉列表
	"value": "下拉菜单的某一项"//选项ID
      }
      {
	"key": "field_5",//高级复选框
	"value": "232,565,454"//勾选项的ID列表，以逗号分隔
      }
      {
	"key": "field_7",//级联
	"value": [
	  {
            "level_id":"s1",//级联的第一级别的id
            "item_key":"11"//选中项的ID
          },
          {
            "level_id":"s2",//级联的第二级别的id
            "item_key":"21"
          },
          {
	    "level_id":"s3",//级联的第三级别的id
	    "item_key":"31"
          }
	]
     }
   ],
   "userGroup": 221
}

获取联系人列表

GET /api/v1/users_v2.json

旧接口 “GET /api/v1/users.json”
获取全部数据（包含已删除数据），需在链接后拼接deStat=1，/api/v1/users_v2.json?deStat=1

查询参数

名称	必需的	类型	注释
created_start	否	string	按创建时间筛选，开始时间，包含当天
created_end	否	string	按创建时间筛选，结束时间，包含当天
updated_start	否	string	按更新时间筛选，开始时间，包含当天
updated_end	否	string	按更新时间筛选，结束时间，包含当天
created_order	否	string	按创建时间排序，取值为：asc-升序，desc-降序
updated_order	否	string	按更新时间排序，取值为：asc-升序，desc-降序
page	否	int	分页获取，默认为1
per_page	否	int	每页大小，默认为100

说明：默认按编码升序返回。时间参数（created_start、created_end、updated_start、updated_end）格式为“2012-01-01 00:00:00”。

调用者权限

所有客服

也可以使用下面的接口

/*查看服务商下某个客户的联系人*/
GET /api/v1/companies/{company_id}/users_v2.json
GET /api/v1/companies/{company_id}/users.json

调用示例

curl https://www.bangwo8.com/api/v1/users_v2.json \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
	"users": [
		{
			"cId": 1,
			"name": "张三",
			...
		},
		{
			"cId": 2,
			"name": "李四",
			...
		}
	],
        "count": 42,
        "next_page": "https://www.bangwo8.com/api/v1/users_v2.json?per_page=40&page=2",
        "previous_page": null
}

查看指定联系人信息

GET /api/v1/users/{cid}_v2.json

旧接口 “GET /api/v1/{cid}.json”

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/{cid}_v2.json \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
    "user": {
        "cId": "41451311",
        "name": "测试1",
        "mobile": "18811119637",
        "email": "",
        "fixnumber": "",
        "position": "",
        "QQ": "",
        "note": "",
        "companyId": "0",
        "supportId": "0",
        "multiServiceList": "",
        "default": "",
        "service_groupid": "0",
        "createDT": "2022-01-10 11:10:43",
        "updateDT": "2022-02-10 15:16:16",
        "tableName": "",
        "uniqueId": "",
        "custom_fields": [
            {
                "key": "field_1",
                "value": ""
            },
            {
                "key": "authaccount",
                "value": "212108284829637117"
            },
            {
                "key": "field_3",
                "value": [
                    "北京市",
                    "海淀",
                    "清华大学"
                ]
            }
        ],
        "userGroup": "0"
    }
}

获取多个联系人信息

GET GET /api/v1/users/show_many.json?ids={ids}

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/show_many.json?ids=1,2,3 \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
  "users": [
    {
      "cId": 1,
      "name": "张三",
      ...
    },
    {
      "cId": 2,
      "name": "李四",
      ...
    }
  ]
}

创建联系人

POST /api/v1/users_v2.json

旧接口“POST /api/v1/users.json”

调用者权限

所有客服

调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214"}}'

说明：可通过mobile和fixnumber属性来创建联系人。也就是说，创建联系人时，mobile、fixnumber两者其一必须有值。

若请求数据中包含“下拉列表”，则需传递选中项的ID，调用示例如下：

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"droplist_job","value":"232"}]}}'

若请求数据中包含“复选框”，则选中时传“1”，未选中传“0”，调用示例如下：

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"checkbox_married","value":"1"}]}}'

若请求数据中包含“高级复选”，则需传递所有勾选项的ID，以逗号分隔，调用示例如下：

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"advance_checkbox_hobby","value":"21,23"}]}}'

若请求数据中包含“级联”字段，调用示例如下：

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"field_3","value":["北京市","海淀","清华大学"]}]}}'

返回值示例

Status: 200 OK
Location: https://www.bangwo8.com/api/v1/users/{id}.json

{
  "user": {
    "cId":   11,
    "name": "张三",
    ...
  }
}

[注] 联系人是与手机号码一一对应，因此：
1、2B模式下，不同公司下可以有相同联系人（手机号码），同一公司下不能有相同联系人（手机号码）（即：同一个人可能出现在多个公司里，但同一个人不能在同一公司出现两次）；
2、2C模式下，没有公司概念，所有联系人在一起，不能有相同联系人（手机号码）
否则通过API创建联系人时会报错：[{“errorMsg”:“The \”mobile\“ has been used”,“status”:“110017”}]

修改联系人信息

PUT /api/v1/users/{cid}.json

调用者权限

所有客服

更新系统字段调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users/123.json \
  -H "Content-Type: application/json" -X PUT -d '{"user": {"name": "张三"}}'

返回值示例

Status: 200 OK

{
  "user": {
    "cId":   11,
    "name": "张三",
    ...
  }
}

更新自定义字段调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users/123.json \
  -H "Content-Type: application/json" -X PUT -d '{"user":{"custom_fields":[{"key":"field_1","value":"123"}]}}'

返回值示例

Status: 200 OK

{
  "user": {
    "cId":   11,
    "name": "张三",
     "custom_fields": [
            {
                "key": "field_1",
                "value": "123"
            }
        ]
  }
}

搜索联系人

GET /api/v1/users/search.json

获取全部数据（包含已删除数据），需在链接后拼接deStat=1，/api/v1/users/search.json?deStat=1

调用者权限

所有客服

请求参数

名称	类型	必需的	注释
query	string	是	搜索内容
sort_by	string	否	按时间排序，目前支持：createDT-创建时间，updateDT-更新时间
sort_order	string	否	按升序还是降序返回，取值为：asc-升序，desc-降序，默认为降序

query参数说明

搜索内容	返回结果
query=2444	模糊搜索，返回姓名或者手机号包含该内容的联系人
query=mobile:13240138429	搜索手机号为“13240138429”的联系人，此为精确搜索
query=userId:9516936 mobile:13240134213	搜索公司id为“9516936”且手机号码为“13240134213 ”的联系人，此为精确搜索
query=authaccount:454	返回自定义字段唯一标识为“authaccount”为454的联系人，此条件为精准查询
query=2444 createDT>2017-07-01	返回姓名或者手机号包含“2444”，并且创建时间是2017年7月1日以后的联系人
query=2444 createDT>=2017-07-01 createDT<2017-08-01	返回姓名或者手机号包含“2444”，并且时间是7月份的联系人

说明：
1、目前不支持搜索内容本身带有空格
2、当query参数增加了时间的过滤条件时，两个条件之间要以空格分开，比如“2444 createDT>2017-07-01”
3、时间过滤条件目前支持以下几种方式：（以createDT为例）

  * createDT<2017-09-01 //过滤创建时间为2017-09-01之前的联系人，不包含2017-09-01当天
  * createDT>2017-09-01 //过滤创建时间为2017-09-01之后的联系人，不包含2017-09-01当天 
  * createDT:2017-09-01 //过滤创建时间为2017-09-01当天的联系人 
  * createDT<=2017-09-01 //过滤创建时间为2017-09-01之前的联系人，包含2017-09-01当天 
  * createDT>=2017-09-01 //过滤创建时间为2017-09-01之后的联系人，包含2017-09-01当天

调用示例

curl "https://www.bangwo8.com/api/v1/users/search.json" \
  -G --data-urlencode "query=132 createDT>2017-07-03" \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
  "results": [
    {
      "name":   "张三",
      "createDT":  "2009-05-13 10:07:08",
      "updateDT":  "2011-07-22 11:11:12",
      "cId":  111,
      "url":       "https://www.bangwo8.com/api/v1/users/111.json"
    },
    {
      "subject":   "李四",
      "createDT":  "2010-07-13 10:07:08",
      "updateDT":  "2011-07-13 11:11:12",
      "cId":  112,
      "url":       "https://www.bangwo8.com/api/v1/users/112.json"
    },
    ...
  ],
  "next_page": "https://www.bangwo8.com/api/v1/users/search.json?query=132 createDT>2017-07-03&sort_by=createDT&sort_order=desc&page=2",
  "prev_page": null,
  "count":     100
}

删除多个联系人

DELETE /api/v1/users/destroy_many.json

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/destroy_many.json?ids=123,234 \
  -v -u {account}:{password} \
  -X DELETE

返回值示例

Status: 200 OK

{
  "users": [
    {
      "cId": 123,
      "name": "张三",
      ...
    },
    {
      "cId": 234,
      "name": "李四",
      ...
    }
  ]
}

侧边栏

CRM扩展

数据接口

呼叫能力

Android IM SDK手册（暂停使用）

iOS IM SDK手册（暂停使用）

Android SIP SDK手册

iOS SIP SDK手册

客户端标准版快速集成

帮我吧远程SDK版本

网页在线客服集成

微信接入

目录

联系人接口

JSON格式

JSON示例

获取联系人列表

查看指定联系人信息

获取多个联系人信息

创建联系人

修改联系人信息

搜索联系人

删除多个联系人

侧边栏

CRM扩展

数据接口

呼叫能力

Android IM SDK手册（暂停使用）

iOS IM SDK手册（暂停使用）

Android SIP SDK手册

iOS SIP SDK手册

客户端标准版快速集成

帮我吧远程SDK版本

网页在线客服集成

微信接入

目录

联系人接口

JSON格式

JSON示例

获取联系人列表

查看指定联系人信息

获取多个联系人信息

创建联系人

修改联系人信息

搜索联系人

删除多个联系人

页面工具