Каждый диалог и каждый звонок относятся к клиенту — одному и тому же человеку во всех ваших каналах. Клиенты объединяются только по данным, которые нельзя подделать, например по номеру, с которого звонят, или по ID, который ваш сайт подписывает для вошедшего посетителя; email или телефон, который человек вводит сам, сохраняется в профиле, а объединяет клиентов ваша команда в панели. Ваши системы могут читать базу клиентов, поддерживать её в актуальном виде и добавлять то, что происходит вне EvaSay.
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/v1/voice/contacts | Клиенты, сначала недавние: q ищет по именам, email, телефонам, компаниям и тегам, 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 принимает ключи ваших собственных полей (добавьте их на странице Клиенты; их перечисляет GET /api/v1/voice/contact-fields) со значением типа поля; пустая строка очищает значение. Значение, которое ваша команда ввела в панели, сохраняется: API его не перезаписывает, и агент тоже. Смена email или телефона не объединяет клиента с другим, у которого они такие же. Стандартные данные (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": "Order 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 (оба вида звонков включают звонки голосом ИИ). Каждое имеет состояние granted, withdrawn или, пока записей нет, unknown. Изменение никогда не правится, а только добавляется в историю с источником и подтверждением:
{ "kind": "marketing_calls", "status": "granted", "note": "Ticked 'Call me about offers' on order 1042" }
Записывать согласия могут только ключи владельцев и администраторов, и note — ваше подтверждение — обязателен.
Группы — это сохранённые фильтры по базе клиентов: те, что есть в каждом рабочем пространстве (все клиенты, VIP, новые за последние 7 дней и другие), группы вашей отрасли и те, что вы создаёте на странице Клиенты. GET /api/v1/voice/segments перечисляет их с id; передайте его как segment_id, чтобы получить клиентов группы.
Ваши системы также могут узнавать об изменениях сразу: contact.created, contact.updated, contact.consent_changed и contact.merged — это события вебхуков.