每段对话和每通电话都归在一个客户名下,同一个人在各个渠道都是同一个客户。客户只按别人冒充不了的信息合并,例如来电号码、你的网站为已登录访客签名的用户 ID;访客自己填的邮箱或电话会记在资料上,由你的团队在工作台里合并。你的系统可以读取客户库、保持资料最新,并把 EvaSay 之外发生的事写进来。
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /api/v1/voice/contacts | 客户列表,最近联系的在前:q 搜索姓名、邮箱、电话、公司和标签,segment_id 只看一个分组,limit(最多 100)和 offset 翻页 |
| GET | /api/v1/voice/contacts/{id} | 一个客户的资料、标签、同意状态和你自己的字段 |
| PATCH | /api/v1/voice/contacts/{id} | 修改 name、email、phone、company、city、country、language、timezone、tags 或 attributes |
| GET | /api/v1/voice/contact-fields | 你自己的客户字段:每个的 key、label、type 和 options |
| GET | /api/v1/voice/contacts/{id}/events | 客户的时间线,最新的在前 |
| POST | /api/v1/voice/contacts/{id}/events | 从你自己的系统写入一个事件 |
| GET | /api/v1/voice/contacts/{id}/consent | 每一次同意变化,带来源和证据 |
| POST | /api/v1/voice/contacts/{id}/consent | 记录一次同意变化 |
| GET | /api/v1/voice/segments | 客户分组;counts=true 时附上每组现在有多少客户 |
curl https://evasay.com/api/v1/voice/contacts/CONTACT_ID \
-X PATCH \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{ "company": "Acme Dental", "tags": ["vip"], "attributes": { "plan": "Gold" } }'
tags 会替换客户的全部标签。attributes 用你自己字段的 key(在“客户”页添加,GET /api/v1/voice/contact-fields 可以列出),值要符合字段类型;传空字符串就是清空。团队成员在工作台里填的值会保留:API 不会覆盖它,Agent 也不会。修改邮箱或电话不会把这个客户和另一个有同样邮箱或电话的客户合并。标准资料(name、email、phone 等)则按传入的值直接替换。
把你自己系统里发生的事(下单、到店、续费等)写进来,它会出现在客户的时间线上:
curl https://evasay.com/api/v1/voice/contacts/CONTACT_ID/events \
-X POST \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{ "event_id": "order-1042", "name": "order_paid", "subject": "订单 1042", "values": { "total": "89.00" } }'
name 只能用小写字母、数字、_ 和 .。event_id 是你自己的 ID:同一个客户上同一个 event_id 只记一次,所以可以放心重试,重复的那次 accepted 是 false。values 放文字,flags 放 true 或 false,appointment_at 是 Unix 毫秒时间。
EvaSay 把四种同意分开记录:marketing_email、marketing_sms、marketing_calls 和 service_calls(两种电话都包括 AI 声音的来电)。每种是 granted、withdrawn,还没有任何记录时是 unknown。同意记录只追加、不修改,每条带来源和证据:
{ "kind": "marketing_calls", "status": "granted", "note": "在订单 1042 上勾选了“有优惠时给我打电话”" }
只有所有者和管理员的密钥能记录同意,而且必须带上 note(你的证据)。
分组是客户库上保存好的筛选条件:每个工作区都有的(全部客户、VIP、最近 7 天新增等)、你所在行业的,以及你在“客户”页自己建的。GET /api/v1/voice/segments 列出分组和它们的 id;把它作为 segment_id 传入,就能列出这个分组的客户。
你的系统也可以在变化发生时收到通知:contact.created、contact.updated、contact.consent_changed 和 contact.merged 都是 Webhook 事件。