NAV
shell python

DaoVoice API 介绍

欢迎使用 DaoVoice 开放 API,在这里你可以操作 DaoVoice 的用户和对话。你可以使用右侧的 Shell 或者 Python 来直接调试。

认证

获取认证

打开你的 APP 设置 页面, 找到 开放API,可以看到用于调用接口的 ACCESS-TOKEN。

使用认证

ACCESS-TOKEN 可以让您直接访问API。

你需要在请求的 HTTP 的 headers中传入 设置ACCESS-TOKEN。 Authorization: token ACCESS-TOKEN

提交样例说明

其中,<your token>替换为你的ACCESS-TOKEN。

所有的POST提交需要将给定的参数放进一个json对象,然后直接放入HTTP的消息体。 HTTP 请求头里面必须加入Content-Type: application/json,否则可能返回400错误。

用户

User

字段 类型 描述
user_id String 用户自定义的id
name String 用户自定义的name
email String 用户自定义的email
wx_open_id String 在APP绑定微信公众号之后,用户微信的OPENID
companies Company Array 用户所属公司数组
custom_attributes Object 用户自定义参数

创建用户

通过这个API可以创建用户到自己的应用中。

HTTP请求

POST https://api.daovoice.io/v1/users

请求参数

字段 类型 是否必要 描述
user_id String 若 email, wx_open_id 和 name 都不存在,则必须 开发者自定义的ID,用于标识用户,比 email 更优先
email String 若user_id, wx_open_id和name都不存在,则必须 开发者自定义的email,用于标识用户 ,如果没有user_id,以此为准
wx_open_id String 若user_id, email和name都不存在,则必须 在APP绑定微信公众号之后,用户微信的OPENID,如果没有user_id和email,以此为准
name String 若user_id, wx_open_id和email都不存在,则必须 开发者自定义的name,用于标识用户 ,如果没有user-id,email,以此为准
companies Company Array 用户所属公司信息,其中,Company对象可以只设置company_id或name属性,数组最大长度为10
custom_attributes Object 用户自定义属性,为数据字典

提交样例

curl "https://api.daovoice.io/v1/users" \
     -X POST \
     -H "Authorization: token <your token>" \
     -H "Content-Type: application/json" \
     -d '{
        "user_id": "NO_a18af07b",
        "email": "a18af07b@daocloud.io", 
        "wx_open_id": "xxx",
        "custom_attributes":{
            "msn":"msn_test_id",
            "ip": "1.2.3.4",
            "nick": "Roby"
        },
        "companies":[{
                "company_id":"a18af07b-c5d9"
            },{
                "name":"Test company name"
            }
        ]
    }'
import requests

response = requests.post(
    'https://api.daovoice.io/v1/users',
    json={
        "user_id": "NO_a18af07b",
        "email": "a18af07b@daocloud.io", 
        "wx_open_id": "xxx",
        "custom_attributes":{
            "msn":"msn_test_id",
            "ip": "1.2.3.4",
            "nick": "Roby"
        },
        "companies":[{
                "company_id":"a18af07b-c5d9"
            },{
                "name":"Test company name"
            }
        ]
    },
    headers={
        'Authorization': 'token <your token>',
        'Content-Type': 'application/json'
    }
)
print(response.json())

请求结果

如果成功调用,会返回一个用户模型对象。

成功示例

{
    "companies":[
        {
            "company_id": "a18af07b-c5d9",
            "company_name": ""
        },
        {
            "company_id": "b8c6d6d0-ca41-4669-b548-da90b91020db",
            "company_name": "Test company name"
        }
    ],
    "user_id": "NO_a18af07b",
    "email": "a18af07b@daocloud.io",
    "wx_open_id": "xxx",
    "custom_attributes":{
        "nick": "Roby",
        "msn": "msn_test_id",
        "ip": "1.2.3.4"
    },
    "name": "a18af07b@daocloud.io"
}

列出用户

HTTP 请求

GET https://api.daovoice.io/v1/users

请求参数

字段 类型 必需 描述
sort_by String 排序字段 last_seen,signed_up,first_seen
sort_direction String 倒序还是顺序 asc,desc
page Integer 需要获取哪一页用户,从1开始,默认为1
page_size Integer 每页显示个数,最大为1000,默认为20
curl "https://api.daovoice.io/v1/users" \
     -H "Authorization: token <your token>"
import requests

response = requests.get(
    'https://api.daovoice.io/v1/users',
    params={
        'sort_by': 'last_seen',
        'sort_direction': 'desc'
    },
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

如果成功调用,会返回一个数据字典,包含两个属性。 paginate为一个Paginate模型对象,users为用户模型数组。

成功示例

{
    "paginate": {
        "total_counts": 25080,
        "total_pages": 8360,
        "page": 1,
        "page_size": 3
    },
    "users": [
        {
            "user_id": "eb6e9241-d596-47b2-ab98-963e48284463",
            "name": "Angela Owens",
            "companies": [],
            "custom_attributes": {
                "location_data": {
                    "region_name": "北卡罗来纳州",
                    "longitude": -78.6253,
                    "country_name": "美国",
                    "postal_code": "27668",
                    "continent_code": "NA",
                    "country_code": "US",
                    "latitude": 35.7977,
                    "timezone": "America/New_York",
                    "city_name": "罗利"
                }
            },
            "wx_open_id": null,
            "email": "scott85@gmail.com"
        },
        {
            "user_id": "4dfa7508-5a04-4fb3-9ac2-791bc3bab2ca",
            "name": "hello",
            "companies": [],
            "custom_attributes": {},
            "wx_open_id": null,
            "email": "6455166@qq.com"
        },
        {
            "user_id": "536ecbe1-6b29-4ee2-be78-82a0375ff4da",
            "name": "George Hickman",
            "companies": [],
            "custom_attributes": {
                "location_data": {
                    "region_name": null,
                    "longitude": 9.491,
                    "country_name": "德国",
                    "postal_code": null,
                    "continent_code": "EU",
                    "country_code": "DE",
                    "latitude": 51.2993,
                    "timezone": null,
                    "city_name": null
                }
            },
            "wx_open_id": null,
            "email": "ryansandoval@hotmail.com"
        }
    ]
}

标签 Tag

Tag

字段 类型 描述
name String 标签名

创建标签

HTTP请求

POST https://api.daovoice.io/v1/tags

请求参数

字段 类型 必需 描述
name String Tag 名
users User Array 给特定的用户打标签

如果 users 里 user 对象 untagtrue, 则是把该用户的标签删除。

提交样例

curl "https://api.daovoice.io/v1/tags" \
     -X POST \
     -H "Authorization: token <your token>" \
     -H "Content-Type: application/json" \
     -d '{
          "tag_name": "example_tag",
          "users":[
                {
                "user_id":"1234",
                "untag":true
            }
          ]
        }'
import requests
response = requests.post(
    'https://api.daovoice.io/v1/tags',
    json={
          "tag_name": "example_tag",
          "users":[
            {
                "email":"example@daocloud.io"
            }
          ],
    headers={
        'Authorization': 'token <your token>',
        'Content-Type': 'application/json'
    }
)
print(response.json())

请求结果

如果请求成功,会返回一个 Tag 对象。

成功示例

{
    "tag_name":"example_tag"
}

管理员

管理员可以给用户发送消息和其它的一些操作。

Admin

字段 类型 描述
admin_id String 管理员ID
type String 管理员类型,暂时只支持admin
name String 管理员名字
is_online Boolean 是否在线
email String 管理员E-mail

获取管理员列表

获取管理员列表。

HTTP请求

GET https://api.daovoice.io/v1/admins

提交样例

curl "https://api.daovoice.io/v1/admins" \
     -H "Authorization: token <your token>"
import requests

response = requests.get(
    'https://api.daovoice.io/v1/admins',
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

如果请求成功,会返回一个管理员模型数组。

成功示例

[{
    "admin_id": "admin_123",
    "type": "admin", 
    "name": "John", 
    "is_online": true, 
    "email": "admin@test.com"
}]

团队

获取团队列表

Admin

字段 类型 描述
team_id String 团队 ID
name String 团队名

HTTP 请求

GET https://api.daovoice.io/v1/teams

提交样例

curl "https://api.daovoice.io/v1/teams" \
     -H "Authorization: token <your token>"
import requests

response = requests.get(
    'https://api.daovoice.io/v1/teams',
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

如果请求成功,会返回一个团队模型数组。

成功示例

[
    {
        "team_id": "55741ec2-add0-415b-9af1-d8babac30db9",
        "name": "example team",
        "admin_ids": [
            "337a867b-e159-40cf-a364-1fea78824095"
        ]
    }
]

事件

您可以发送自定义事件,DaoVoice 将会把该事件与当前的用户联系在一起。您也可以添加事件的数据。

Event

字段 类型 描述
event_name String 事件名称
user_id String 所属用户ID
email String 所属用户E-mail
metadata Object 一个字典,用来描述事件的详情
created_at Integer 事件创建时间,是一个 Unix Time

提交事件

HTTP请求

POST https://api.daovoice.io/v1/events

请求参数

字段 类型 必需 描述
event_name String 事件名称
user_id String 如果不存在email,则必须 事件所属用户ID
email String 如果不存在user_id,则必须 事件所属用户E-mail
created_at Integer 事件创建时间,是一个 Unix Time
metadata Object 一个字典,用来描述事件的详情

提交样例

curl "https://api.daovoice.io/v1/events" \
     -X POST \
     -H "Authorization: token <your token>" \
     -H "Content-Type: application/json" \
     -d '{
          "event_name": "this is a test.",
          "email":"test@daocloud.io",
          "created_at": 1450171262,
          "metadata": {
            "referer": "account.daocloud.io"
          }
        }'
import requests

response = requests.post(
    'https://api.daovoice.io/v1/events',
    json={
          "event_name": "this is a test.",
          "email":"test@daocloud.io",
          "created_at": 1450171262,
          "metadata": {
            "referer": "account.daocloud.io"
          }
        },
    headers={
        'Authorization': 'token <your token>',
        'Content-Type': 'application/json'
    }
)
print(response.json())

请求结果

若成功,返回一个事件模型。

成功示例

{
    "event_name": "this is a test.",
    "metadata":{
        "referer": "account.daocloud.io"
    },
    "user_id": null,
    "email": "test@daocloud.io",
    "created_at": 1450171262
}

获取用户事件

您可以通过该接口获取用户所触发的历史事件。

HTTP请求

GET https://api.daovoice.io/v1/events

请求参数

字段 类型 必需 描述
type String 为固定值user
user_id String 如果不存在email,则必须 事件所属用户ID
email String 如果不存在user_id,则必须 事件所属用户E-mail
page Integer 需要获取哪一页用户,从1开始,默认为1
page_size Integer 每页显示个数,最大为1000,默认为100

提交样例

curl "https://api.daovoice.io/v1/events?type=user&email=test@daocloud.io" \
     -H "Authorization: token <your token>"
import requests

response = requests.get(
    'https://api.daovoice.io/v1/events',
    params={
        'type': 'user',
        'email': 'test@daocloud.io'
    },
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

如果成功调用,会返回一个数据字典,包含两个属性。 paginate为一个Paginate模型对象,events为事件模型数组。

成功示例

{
    "paginate": {
        "total_counts": 1, 
        "total_pages": 1, 
        "page": 1, 
        "page_size": 100
    }, 
    "events": [
        {
            "event_name": "this is a test.", 
            "created_at": 1450171262, 
            "metadata": {
                "referer": "account.daocloud.io"
            }, 
            "user_id": null, 
            "email": "test@daocloud.io"
        }
    ]
}

消息

Message

字段 类型 描述
message_type String 消息类型
subject String 消息的Subject
body String 消息体
from Admin 发送者
to User 将要发送给的用户

发送消息

给用户发送消息

HTTP请求

POST https://api.daovoice.io/v1/messages

请求参数

字段 类型 是否必要 描述
message_type String 消息类型,in_app或者email
from Admin 是哪个管理员所发送
to User 将要发送给的用户,可以只选user_id, email之一
subject String 此字段只针对邮件发送有效
body String 消息内容

提交样例

curl "https://api.daovoice.io/v1/messages" \
     -X POST \
     -H "Authorization: token <your token>" \
     -H "Content-Type: application/json" \
     -d '{
        "message_type": "in_app",
        "subject": "Hello", 
        "body": "<p>Good morning.</p>", 
        "from": {
            "admin_id":"063b841f-45ca-4880-92a2-a0529b1ae8c3"
        }, 
        "to":{
            "user_id":"NO_27251"
        }
    }'
import requests

response = requests.post(
    'https://api.daovoice.io/v1/messages',
    json={
        "message_type": "in_app",
        "subject": "Hello", 
        "body": "<p>Good morning.</p>", 
        "from": {
            "admin_id":"063b841f-45ca-4880-92a2-a0529b1ae8c3"
        }, 
        "to":{
            "user_id":"NO_27251"
        }
    },
    headers={
        'Authorization': 'token <your token>',
        'Content-Type': 'application/json'
    }
)
print(response.json())

请求结果

返回一个消息模型。

成功示例

{
    "message_type":"in_app",
    "subject":"Hello",
    "body":"<p>Good morning.</p>",
    "from":{
            "admin_id": "063b841f-45ca-4880-92a2-a0529b1ae8c3"
        },
    "to":{
            "user_id":"NO_27251",
            "email":null
        }
}

对话

Conversation

字段 类型 描述
conversation_id String 每个对话的唯一标识符
user_type String 此对话所要发送给的用户类型,user表示注册用户,contact表示匿名用户
user User or Contact 此对话所要发送给的用户
assignee_type String 此对话分配的类型,admin或team
assignee Admin or Team 此对话分配的管理员或团队
conversation_parts ConversationPart Array 详细对话内容列表
conversation_message ConversationMessage 对话的第一条消息
is_open Bool 对话是否处于打开状态
is_read Bool 对话是否已读
url String 创建对话来源,如果是用户从网页创建,则对相应地址,如果从微信创建,则为WeChat
created_at Integer 对话创建时间,是一个 Unix Time

ConversationPart

字段 类型 描述
conversation_part_id String 对话内容唯一标识符
conversation_id String 所属于的对话ID
type String 对话内容类型,comment、note、assignment,close
body String 对话内容
author_type String 对话内容创建者类型,admin、user或rule
author Admin or User or Rule 对话内容创建者
assignee_type String 此对话分配的类型,admin或team
assignee Admin or Team 此对话分配的管理员或团队
attachments Attachment Array 附件对象列表
url String 创建对话来源,如果是用户从网页创建,则对相应地址,如果从微信创建,则为WeChat
created_at Integer 对话内容创建时间,是一个 Unix Time

获取对话列表

分页获取对话列表。

HTTP请求

GET https://api.daovoice.io/v1/conversations

请求参数

字段 类型 是否必要 描述
page Integer 需要获取哪一页用户,从1开始,默认为1
page_size Integer 每页显示个数,最大为1000,默认为100
is_open Bool 只显示打开或关闭的对话,不传为所有
admin_id String 只显示某个管理员的对话,不传为所有
assignee_id String admin_id 或者 team_id 或者 unassigned

提交样例


curl "https://api.daovoice.io/v1/conversations?page=1&page_size=100&is_open=true&admin_id=c6ffc768-c194-4a37-91de-87083811d0b0" \
     -H "Authorization: token <your token>"


import requests

response = requests.get(
    'https://api.daovoice.io/v1/conversations',
    params={
        'page': 1,
        'page_size': 100,
        'is_open': True,
        'admin_id': 'c6ffc768-c194-4a37-91de-87083811d0b0'
    },
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

如果成功调用,会返回一个数据字典,包含两个属性。 paginate为一个Paginate模型对象,conversartions为对话模型数组。

成功示例

{
    "conversations": [
        {
            "conversation_message": {
                "body": "test", 
                "seen_by_admin": true, 
                "attachments": [], 
                "author": {
                    "companies": [], 
                    "user_id": null, 
                    "email": "a@c.com", 
                    "custom_attributes": {}, 
                    "name": "Test_OPEN_API"
                }, 
                "style": "chat", 
                "conversation_message_id": "4745f670-a0dd-4d63-adf6-0035176a2f40", 
                "subject": "", 
                "author_type": "user"
            }, 
            "assignee": null, 
            "created_at": 1476683414, 
            "user_type": "user", 
            "is_read": true, 
            "assignee_type": null, 
            "is_open": true, 
            "url": "https://dashboard.daovoice.io",
            "user": {
                "companies": [], 
                "user_id": null, 
                "email": "a@c.com", 
                "custom_attributes": {}, 
                "name": "Test_OPEN_API"
            }, 
            "conversation_id": "4ca69f36-e50f-4bf4-bc33-1192cfce5a77", 
            "conversation_parts": []
        }, 
        {
            "conversation_message": {
                "body": "Test open api.~", 
                "seen_by_admin": true, 
                "attachments": [], 
                "author": {
                    "companies": [], 
                    "user_id": null, 
                    "email": "test@test.com", 
                    "custom_attributes": {}, 
                    "name": "紫色的香蕉"
                }, 
                "style": "chat", 
                "conversation_message_id": "704ea0f5-8605-4c1d-bd77-f46e7d6f1433", 
                "subject": "", 
                "author_type": "user"
            }, 
            "assignee": null, 
            "created_at": 1476683166, 
            "user_type": "user", 
            "is_read": true, 
            "assignee_type": null, 
            "is_open": true, 
            "url": "https://dashboard.daovoice.io",
            "user": {
                "companies": [], 
                "user_id": null, 
                "email": "test@test.com", 
                "custom_attributes": {}, 
                "name": "紫色的香蕉"
            }, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_parts": []
        }
    ], 
    "paginate": {
        "total_counts": 2, 
        "total_pages": 1, 
        "page": 1, 
        "page_size": 100
    }
}

获取单个对话

获取单个对话详情。

HTTP请求

GET https://api.daovoice.io/v1/conversations/{conversation_id}

请求参数

无。

提交样例


curl "https://api.daovoice.io/v1/conversations/1cc41297-b62a-4f3b-9aec-b4a86cc5755f" \
     -H "Authorization: token <your token>"


import requests

response = requests.get(
    'https://api.daovoice.io/v1/conversations/1cc41297-b62a-4f3b-9aec-b4a86cc5755f',
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

如果成功调用,会返回一个对话模型。

成功示例


{
    "conversation_message": {
        "body": "Test open api.~", 
        "seen_by_admin": true, 
        "attachments": [], 
        "author": {
            "companies": [], 
            "user_id": null, 
            "email": "test@test.com", 
            "custom_attributes": {}, 
            "name": "紫色的香蕉"
        }, 
        "style": "chat", 
        "conversation_message_id": "704ea0f5-8605-4c1d-bd77-f46e7d6f1433", 
        "subject": "", 
        "author_type": "user"
    }, 
    "assignee": {
        "type": "admin", 
        "email": "kebe.liu@daocloud.io", 
        "name": "kebe", 
        "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
    }, 
    "created_at": 1476683166, 
    "user_type": "user", 
    "is_read": false, 
    "assignee_type": "admin", 
    "is_open": true, 
    "url": "https://dashboard.daovoice.io",
    "user": {
        "companies": [], 
        "user_id": null, 
        "email": "test@test.com", 
        "custom_attributes": {}, 
        "name": "紫色的香蕉"
    }, 
    "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
    "conversation_parts": [
        {
            "body": "<p>Test api.</p>", 
            "conversation_part_type": "comment", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684078, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "7e518f87-bfcf-4fac-b599-7313f867bae1", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": null, 
            "conversation_part_type": "comment", 
            "attachments": [
                {
                    "url": "https://dn-daocom-uploads-test.qbox.me/image/svg+xml/c565905d-c8df-496f-8f14-56d65daa69b6.svg", 
                    "name": "icon.svg", 
                    "content_type": "image/svg+xml"
                }
            ], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684068, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "88275add-56ac-452f-aaa7-e26f8428a4da", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": null, 
            "conversation_part_type": "assignment", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684068, 
            "assignee_type": "admin", 
            "assignee": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "21ab43f1-fe80-4ae0-9d28-5b5928e2c8b6", 
            "url": null,
            "author_type": "admin"
        }
    ]
}

回复对话

回复对话。

HTTP请求

POST https://api.daovoice.io/v1/conversations/{conversation_id}/reply

请求参数

字段 类型 是否必要 描述
admin Admin 管理员
message_type String 消息类型,为comment或note或assignment,comment为正常对话,note为备注,只有管理员可见,assignee为将对话指派给特定的团队或管理员
body String 若message_type为comment或note,则必须 回复的具体内容
assignee_type String 若message_type为assignment则必须 指派类型,为team或admin,team表团队,admin表管理员
assignee Admin or Team 若message_type为assignment则必须 要指派给的管理员或团队

提交样例


curl "https://api.daovoice.io/v1/conversations/1cc41297-b62a-4f3b-9aec-b4a86cc5755f/reply" \
     -X POST \
     -H "Authorization: token <your token>" \
     -H "Content-Type: application/json" \
     -d '{
        "admin": {
            "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
        },
        "message_type": "comment",
        "body": "Hello"
    }'


import requests

response = requests.post(
    'https://api.daovoice.io/v1/conversations/1cc41297-b62a-4f3b-9aec-b4a86cc5755f/reply',
    json={
        "admin": {
            "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
        },
        "message_type": "comment",
        "body": "Hello"
    },
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

如果成功调用,会返回一个对话模型。

成功示例

{
    "conversation_message": {
        "body": "Test open api.~", 
        "seen_by_admin": true, 
        "attachments": [], 
        "author": {
            "companies": [], 
            "user_id": null, 
            "email": "test@test.com", 
            "custom_attributes": {}, 
            "name": "紫色的香蕉"
        }, 
        "style": "chat", 
        "conversation_message_id": "704ea0f5-8605-4c1d-bd77-f46e7d6f1433", 
        "subject": "", 
        "author_type": "user"
    }, 
    "assignee": {
        "type": "admin", 
        "email": "kebe.liu@daocloud.io", 
        "name": "kebe", 
        "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
    }, 
    "created_at": 1476683166, 
    "user_type": "user", 
    "is_read": false, 
    "assignee_type": "admin", 
    "is_open": true, 
    "url": "https://dashboard.daovoice.io",
    "user": {
        "companies": [], 
        "user_id": null, 
        "email": "test@test.com", 
        "custom_attributes": {}, 
        "name": "紫色的香蕉"
    }, 
    "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
    "conversation_parts": [
        {
            "body": "Hello", 
            "conversation_part_type": "comment", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476685033, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "56773d99-82b0-4269-bf88-25203b2d4f8c", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": "<p>Test api.</p>", 
            "conversation_part_type": "comment", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684078, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "7e518f87-bfcf-4fac-b599-7313f867bae1", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": null, 
            "conversation_part_type": "comment", 
            "attachments": [
                {
                    "url": "https://dn-daocom-uploads-test.qbox.me/image/svg+xml/c565905d-c8df-496f-8f14-56d65daa69b6.svg", 
                    "name": "icon.svg", 
                    "content_type": "image/svg+xml"
                }
            ], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684068, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "88275add-56ac-452f-aaa7-e26f8428a4da", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": null, 
            "conversation_part_type": "assignment", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684068, 
            "assignee_type": "admin", 
            "assignee": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "21ab43f1-fe80-4ae0-9d28-5b5928e2c8b6", 
            "url": null,
            "author_type": "admin"
        }
    ]
}

关闭对话

HTTP请求

PATCH https://api.daovoice.io/v1/conversations/{conversation_id}

请求参数

字段 类型 是否必要 描述
admin Admin 管理员
is_open Bool false关闭对话,true为打开对话

提交样例

curl "https://api.daovoice.io/v1/conversations/1cc41297-b62a-4f3b-9aec-b4a86cc5755f" \
     -X PATCH \
     -H "Authorization: token <your token>" \
     -H "Content-Type: application/json" \
     -d '{
        "admin": {
            "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
        },
        "is_open": false
    }'
import requests

response = requests.patch(
    'https://api.daovoice.io/v1/conversations/1cc41297-b62a-4f3b-9aec-b4a86cc5755f',
    json={
        "admin": {
            "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
        },
        "is_open": false
    },
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

如果成功调用,会返回一个对话模型。

成功示例

{
    "conversation_message": {
        "body": "Test open api.~", 
        "seen_by_admin": true, 
        "attachments": [], 
        "author": {
            "companies": [], 
            "user_id": null, 
            "email": "test@test.com", 
            "custom_attributes": {}, 
            "name": "紫色的香蕉"
        }, 
        "style": "chat", 
        "conversation_message_id": "704ea0f5-8605-4c1d-bd77-f46e7d6f1433", 
        "subject": "", 
        "author_type": "user"
    }, 
    "assignee": {
        "type": "admin", 
        "email": "kebe.liu@daocloud.io", 
        "name": "kebe", 
        "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
    }, 
    "created_at": 1476683166, 
    "user_type": "user", 
    "is_read": false, 
    "assignee_type": "admin", 
    "is_open": false, 
    "url": "https://dashboard.daovoice.io",
    "user": {
        "companies": [], 
        "user_id": null, 
        "email": "test@test.com", 
        "custom_attributes": {}, 
        "name": "紫色的香蕉"
    }, 
    "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
    "conversation_parts": [
        {
            "body": null, 
            "conversation_part_type": "close", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476685496, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "adc1777b-e9f0-4765-a240-fb969f752486", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": "Hello", 
            "conversation_part_type": "comment", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476685033, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "56773d99-82b0-4269-bf88-25203b2d4f8c", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": "<p>Test api.</p>", 
            "conversation_part_type": "comment", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684078, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "7e518f87-bfcf-4fac-b599-7313f867bae1", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": null, 
            "conversation_part_type": "comment", 
            "attachments": [
                {
                    "url": "https://dn-daocom-uploads-test.qbox.me/image/svg+xml/c565905d-c8df-496f-8f14-56d65daa69b6.svg", 
                    "name": "icon.svg", 
                    "content_type": "image/svg+xml"
                }
            ], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684068, 
            "assignee_type": null, 
            "assignee": null, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "88275add-56ac-452f-aaa7-e26f8428a4da", 
            "url": null,
            "author_type": "admin"
        }, 
        {
            "body": null, 
            "conversation_part_type": "assignment", 
            "attachments": [], 
            "author": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "created_at": 1476684068, 
            "assignee_type": "admin", 
            "assignee": {
                "type": "admin", 
                "email": "kebe.liu@daocloud.io", 
                "name": "kebe", 
                "admin_id": "c6ffc768-c194-4a37-91de-87083811d0b0"
            }, 
            "conversation_id": "3474ac13-2526-4aca-b8ff-06a5d47f238a", 
            "conversation_part_id": "21ab43f1-fe80-4ae0-9d28-5b5928e2c8b6", 
            "url": null,
            "author_type": "admin"
        }
    ]
}

用户模型

建立用户模型是观察用户使用你产品情况的最好方式之一,可根据不同的条件来定义你的用户群体(可定义“使用过任意功能”或“付费量大于某一数值”作为筛选用户群体的条件,任何符合该定义条件的用户会即刻匹配入你建立的用户模型中)

Segment

字段 类型 描述
segment_id String 用户模型ID
name String 用户模型名字
user_count Integer 用户模型中所包含用户数
created_at String 用户模型创建时间

获取所有用户模型

HTTP请求

GET https://api.daovoice.io/v1/segments

请求参数

提交样例

curl "https://api.daovoice.io/v1/segments" \
     -H "Authorization: token <your token>"
import requests

response = requests.get(
    'https://api.daovoice.io/v1/segments',
    headers={
        'Authorization': 'token <your token>'
    }
)
print(response.json())

请求结果

成功返回用户模型数组。

成功示例

[
  {
    "created_at": 1481637334,
    "user_count": 23,
    "name": "活跃用户",
    "segment_id": "127f5994-e83d-4d73-9712-dff50cb200a7"
  },
  {
    "created_at": 1481717274,
    "user_count": 4,
    "name": "test-segment-in-segment",
    "segment_id": "3357f931-e2ed-45f5-b32c-ddc4194bcbe4"
  },
  {
    "created_at": 1481717775,
    "user_count": 0,
    "name": "test-segment-in-segment",
    "segment_id": "43201bf3-69b2-42f6-b183-ede67eff16f9"
  },
  {
    "created_at": 1481716735,
    "user_count": 10,
    "name": "daocloud_users",
    "segment_id": "4ddfcb9b-6fd8-4cdd-bf98-198677fa97d1"
  },
  {
    "created_at": 1481637334,
    "user_count": 4,
    "name": "新用户",
    "segment_id": "64e85991-d8a8-4c92-9ea1-52319d634b3c"
  },
  {
    "created_at": 1481637334,
    "user_count": 0,
    "name": "流失用户",
    "segment_id": "6b2ef3a6-b805-4e64-90f8-51a147d815d5"
  },
  {
    "created_at": 1481717700,
    "user_count": 0,
    "name": "test-segment-in-segment",
    "segment_id": "a63dc6cc-0969-4269-a488-d1f5f8f1088c"
  }
]

获取单个用户模型

HTTP请求

GET https://api.daovoice.io/v1/segments/{segment_id}

请求参数

提交样例

curl "https://api.daovoice.io/v1/segments/127f5994-e83d-4d73-9712-dff50cb200a7" \
     -H "Authorization: token <your token>"
import requests

response = requests.get(
    'https://api.daovoice.io/v1/segments/127f5994-e83d-4d73-9712-dff50cb200a7',
    headers={
        'Authorization': 'token <your token>'
    }
)
print(response.json())

请求结果

成功返回用户模型对象。

成功示例

{
  "created_at": 1481637334,
  "user_count": 23,
  "name": "活跃用户",
  "segment_id": "127f5994-e83d-4d73-9712-dff50cb200a7"
}

Webhook

你可以使用Webhook实时的接受特定的通知,比如用户创建对话,回复对话等。如果你订阅了相关事件通知,那么我们会将相应事件通过HTTP请求POST一个JSON格式的通知到你指定的地址。

订阅

你在使用Webhook前,需要前往你DaoVoice APP的应用设置 -> Webhook 里面添加一条订阅,或通过OpenAPI添加订阅,设置相关参数,才能使用。

Subsctiption

字段 类型 描述
subscription_id String 订阅ID
service_type String web
topics Array 订阅事件列表,详情参阅事件
url String 事件推送地址,HTTP/HTTPS地址

添加订阅

HTTP请求

POST https://api.daovoice.io/v1/subscriptions

请求参数

字段 类型 是否必要 描述
service_type String web
topics Array 订阅事件列表,详情参阅事件
url String 事件推送地址,HTTP/HTTPS地址
secret String DaoVoice推送签名认证的secret

提交样例


curl "https://api.daovoice.io/v1/subscriptions" \
     -X POST \
     -H "Authorization: token <your token>" \
     -H "Content-Type: application/json" \
     -d '{
  "service_type": "web",
  "topics": [
    "conversation.user.created",
    "conversation.user.replied",
    "conversation.admin.replied",
    "conversation.admin.opened",
    "conversation.admin.closed",
    "conversation.admin.noted",
    "conversation.admin.assigned",
    "user.created",
    "contact.added_email"
  ],
  "url": "https://yourapp.com/hook/a123c332",
  "secret": "xxxxxxxxx"
}'


import requests

response = requests.post(
    'https://api.daovoice.io/v1/conversations/subscriptions',
    json={
  "service_type": "web",
  "topics": [
    "conversation.user.created",
    "conversation.user.replied",
    "conversation.admin.replied",
    "conversation.admin.opened",
    "conversation.admin.closed",
    "conversation.admin.noted",
    "conversation.admin.assigned",
    "user.created",
    "contact.added_email"
  ],
  "url": "https://yourapp.com/hook/a123c332",
  "secret": "xxxxxxxxx"
},
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

成功返回订阅模型对象。

成功示例

{
  "service_type": "web",
  "topics": [
    "conversation.user.created",
    "conversation.user.replied",
    "conversation.admin.replied",
    "conversation.admin.opened",
    "conversation.admin.closed",
    "conversation.admin.noted",
    "conversation.admin.assigned",
    "user.created",
    "contact.added_email"
  ],
  "url": "https://yourapp.com/hook/a123c332",
  "subscription_id": "127f5994-e83d-4d73-9712-dff50cb200a7"
}

获取所有订阅

HTTP请求

GET https://api.daovoice.io/v1/subscriptions

请求参数

无。

提交样例


curl "https://api.daovoice.io/v1/subscriptions" \
     -H "Authorization: token <your token>"


import requests

response = requests.get(
    'https://api.daovoice.io/v1/subscriptions',
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

成功返回订阅模型数组。

成功示例

[{
  "service_type": "web",
  "topics": [
    "conversation.user.created",
    "conversation.user.replied",
    "conversation.admin.replied",
    "conversation.admin.opened",
    "conversation.admin.closed",
    "conversation.admin.noted",
    "conversation.admin.assigned",
    "user.created",
    "contact.added_email"
  ],
  "url": "https://yourapp.com/hook/a123c332",
  "subscription_id": "127f5994-e83d-4d73-9712-dff50cb200a7"
}]

获取单个订阅

HTTP请求

GET https://api.daovoice.io/v1/subscriptions/{subscription_id}

请求参数

无。

提交样例


curl "https://api.daovoice.io/v1/subscriptions/127f5994-e83d-4d73-9712-dff50cb200a7" \
     -H "Authorization: token <your token>"


import requests

response = requests.get(
    'https://api.daovoice.io/v1/subscriptions/127f5994-e83d-4d73-9712-dff50cb200a7',
    headers={
        'Authorization': 'token <your token>'
    }
)

print(response.json())

请求结果

成功返回订阅模型。

成功示例

{
  "service_type": "web",
  "topics": [
    "conversation.user.created",
    "conversation.user.replied",
    "conversation.admin.replied",
    "conversation.admin.opened",
    "conversation.admin.closed",
    "conversation.admin.noted",
    "conversation.admin.assigned",
    "user.created",
    "contact.added_email"
  ],
  "url": "https://yourapp.com/hook/a123c332",
  "subscription_id": "127f5994-e83d-4d73-9712-dff50cb200a7"
}

事件

目前,我们支持的Webhook事件如下:

事件名字 描述 推送事件包含对象
conversation.user.created 用户创建一个新对话 Conversation
conversation.user.replied 用户回复对话 Conversation
conversation.admin.replied 管理员回复对话 Conversation
conversation.admin.opened 管理员打开对话 Conversation
conversation.admin.closed 管理员关闭对话 Conversation
conversation.admin.noted 管理员添加备注 Conversation
conversation.admin.assigned 管理员被指派了一个对话 Conversation
user.created 有新用户被创建 User

通知

我们发送到你服务器的数据是一个JSON格式的字符串,这个JSON字符串包含的信息就是一个通知通知会携带事件和具体的信息。

通知模型如下:

Notification

字段 类型 描述
id String 唯一标识符
topic String 本次通知的事件名字,详情见 事件
app_id String 你的APP ID
data User or Conversation 本次事件所携带的信息,比如用户创建之后会携带一个User,用户回复对话会携带一个Conversation,详情见事件

认证

Webhook提供信息来源认证。如果你需要认证,那么请在你添加订阅的时候设置你的Secret,我们在推送事件的时候,会在HTTP头里面添加一个名为X-DaoVoice-Signature的头。

我们会使用你设置的Secretsha1算法对HTTP消息体进行HASH运算,得到目标字符串,然后在前面加上sha1=,拼接成验证字符串,放入X-DaoVoice-Signature。样例X-DaoVoice-Signature: sha1=e5fa44f2b31c1fb553b6021e7360d07d5d91ff5e

解析样例

/*
POST / HTTP/1.1
Connection: close
Content-Length: 1642
Host: localhost:1234
Content-Type: application/json
X-Daovoice-Signature: sha1=f6473971f78f3dba366149d3da6ba45df96e2a1e
User-Agent: daovoice-webhook-service-client/1.0

{"topic": "conversation.user.created", "data": {"conversation_message": {"body": "test", "seen_by_admin": true, "attachments": [], "author": {"companies": [{"company_id": null, "name": null}, {"company_id": null, "name": null}, {"company_id": null, "name": null}], "user_id": null, "email": "kebe.liu@daocloud.io", "custom_attributes": {}, "name": "kebe"}, "style": "chat", "conversation_message_id": "7206b86c-587d-484e-903c-55765f57332d", "subject": "", "author_type": "user"}, "assignee": {"type": "admin", "email": "me@yeting.info", "name": "yeting", "admin_id": "6307ecf4-7567-4c04-8a25-7347d7b6e119"}, "type": "conversation", "created_at": 1478242923, "user_type": "user", "is_read": true, "assignee_type": "admin", "is_open": true, "user": {"companies": [{"company_id": null, "name": null}, {"company_id": null, "name": null}, {"company_id": null, "name": null}], "user_id": null, "email": "kebe.liu@daocloud.io", "custom_attributes": {}, "name": "kebe"}, "conversation_id": "a6aa2a0e-7ab0-4535-9e35-a29468861edf", "conversation_parts": [{"body": null, "conversation_part_type": "assignment", "attachments": [], "author": {"type": "admin", "email": "me@yeting.info", "name": "yeting", "admin_id": "6307ecf4-7567-4c04-8a25-7347d7b6e119"}, "created_at": 1478242924, "assignee_type": "admin", "assignee": {"type": "admin", "email": "me@yeting.info", "name": "yeting", "admin_id": "6307ecf4-7567-4c04-8a25-7347d7b6e119"}, "conversation_id": "a6aa2a0e-7ab0-4535-9e35-a29468861edf", "conversation_part_id": "75e35a16-c4bc-4255-9101-049452b5a12e", "author_type": "admin"}]}, "app_id": "38cf7132", "id": "2ef11e0e-dabb-4dda-95c0-80842cf308a7"}
*/

<?php
$secret = 'daovoice';
$notification_data = file_get_contents('php://input');
$signature = hash_hmac('sha1', $notification_data, $secret);
if ("sha1=$signature" != $_SERVER['HTTP_X_DAOVOICE_SIGNATURE']){
    header("HTTP/1.0 403 Permission denied.");
    echo "Permission denied.";
    exit();
}
$notification = json_decode($notification_data);
// do somethings.
echo 'OK';

响应及重试机制

为了确保正确接受及处理通知事件,如果你的服务器处理成功了,请返回一个200-299状态码,我们将认为你的正确处理了请求,不会再发送这个请求。否则,我们会重新推送,最多重试三次。

其它

Paginate

字段 类型 描述
total_counts Integer 总数量
total_pages Integer 总页数
page Integer 当前页
page_size Integer 页大小

Company

字段 类型 描述
company_id String 公司ID,唯一标识符
name String 公司名称

Rule

字段 类型 描述
rule_id String 规则ID,唯一标识符
name String 规则名称

Team

字段 类型 描述
team_id String 团队ID,唯一标识符

Tag

字段 类型 描述
name String Tag 名

Contact

字段 类型 描述
contact_id String 匿名用户ID,唯一标识符
name String 匿名用户名字
email String 匿名用户E-Mail

Attachment

字段 类型 描述
name String 附件名字
content_type String 附件的Content-Type
url String 附件的网络地址

ConversationMessage

字段 类型 描述
conversation_message_id String 唯一标识符
body String 消息内容
seen_by_admin Bool 管理员是否查看
attachments Attachment Array 附件列表
author_type String 所属用户类型,user或contact或admin
author User or Contact or Admin 所属用户
style Bool 消息格式,chat或small_announcement,chat为聊天,small_announcement为通知
subject String 主题,邮件时有效

调用次数限制

API有调用次数限制, 请检查返回 header 中的如下字段 详细可以在设置页面中看到。

header 字段 描述
X-RateLimit-Limit 每小时的限制调用次数,超过后服务器会返回 403 错误
X-RateLimit-Remaining 当前小时中还剩下的调用次数
X-RateLimit-Reset 限制重置时间 unix time

错误处理

DaoCloud API 可能返回以下错误:

Error Code Meaning
400 Bad Request – 请求格式错误,请查阅对应的文档条目
401 bad credentials – access token 过期,或请求的API超过授权
404 Not Found – 调用的 API 不存在,请查看本文档
405 Method Not Allowed – 请求 method 错误, 请查阅对应的文档条目
406 Not Acceptable – 请求不是 json 格式
500 Internal Server Error – 服务器错误,请联系 DaoCloud 客服
503 Service Unavailable – 服务器暂时下线,请稍候重试