API чатов магазина
REST API и вебхуки для интеграции переписок вашего магазина с внешней системой (CRM,
бот). Отвечайте покупателям программно и получайте события о новых сообщениях.
Базовый адрес — https://goodseek.ru.
Все запросы — с заголовком
Authorization: Bearer gsk_… (API-ключ магазина из кабинета, раздел
«Вебхуки (API)»). Ключ идентифицирует магазин; сообщения отправляются от лица
владельца. Без ключа — 401.
Отправка сообщения
Отправляет ответ от лица магазина в существующий диалог. subject_id
берётся из входящего вебхука.
multipart/form-data (обязательно для вложений) или
application/x-www-form-urlencoded. Поля передаются как form-поля, а не
JSON-объект.
Заголовки
| Authorization | required | Bearer gsk_… API-ключ магазина |
Тело запроса · form-data
| subject_id | required | integer — идентификатор диалога (из вебхука) |
| text | optional* | string ≤ 1000 — текст сообщения |
| file | optional | binary — вложение (одно, ≤ 15 МБ). Только
multipart/form-data |
* Обязателен
text ИЛИ file.
Ответы
curl -X POST https://goodseek.ru/api/v1/messages \ -H "Authorization: Bearer gsk_..." \ -F "subject_id=4567" \ -F "text=Здравствуйте! Деталь в наличии."
curl -X POST https://goodseek.ru/api/v1/messages \ -H "Authorization: Bearer gsk_..." \ -F "subject_id=4567" \ -F "text=Фото детали" \ -F "file=@photo.jpg"
{
"ok": true,
"message": {
"id": 987700,
"subject_id": 4567,
"sender_id": 141906442,
"reciver_id": 94235311,
"text": "Здравствуйте! Деталь в наличии.",
"deleted": 0,
"direction": "out",
"created_at": "2026-06-26 12:01:00",
"files": [{ "name": "photo.jpg", "url": "https://cdn.goodseek.ru/…" }]
}
}
Удаление сообщения
Мягко удаляет ваше сообщение: из истории оно не пропадает, а помечается удалённым
(deleted: 1). Удалять можно только собственные отправленные
сообщения. Идемпотентно.
DELETE:
POST /api/v1/messages/{id}/delete.Параметры пути
| id | required | integer — идентификатор сообщения |
Ответы
curl -X DELETE https://goodseek.ru/api/v1/messages/987700 \
-H "Authorization: Bearer gsk_..."
{
"ok": true,
"message": { "id": 987700, "deleted": 1, … }
}
Проверка ключа
Проверяет валидность API-ключа и возвращает магазин, к которому он привязан.
Ответы
curl https://goodseek.ru/api/v1/ping \
-H "Authorization: Bearer gsk_..."
{
"ok": true,
"shop": { "id": 123, "name": "TopGear77" },
"time": "2026-06-26T12:00:00+00:00"
}
Приём событий
GoodSeek отправляет POST на ваш URL, когда покупатель написал в магазин.
URL задаётся в кабинете. Типы событий: message.created,
message.deleted, message.read, а также ping
при проверке адреса.
Заголовки доставки
| X-Goodseek-Event | тип события | |
| X-Goodseek-Delivery | UUID доставки (дедуп) | |
| X-Goodseek-Timestamp | время (в подписи) | |
| X-Goodseek-Signature | sha256=<HMAC> |
sha256 = HMAC_SHA256(secret, "<timestamp>.<тело>"); секрет
whsec_… из кабинета. Отвечайте 200 OK за ~2 секунды.$secret = 'whsec_...'; $body = file_get_contents('php://input'); $ts = $_SERVER['HTTP_X_GOODSEEK_TIMESTAMP'] ?? ''; $exp = 'sha256=' . hash_hmac('sha256', $ts.'.'.$body, $secret); if (!hash_equals($exp, $_SERVER['HTTP_X_GOODSEEK_SIGNATURE'] ?? '')) { http_response_code(401); exit; } http_response_code(200);
{
"event": "message.created",
"delivery_id": "6f1e…e2",
"shop_id": 123,
"data": {
"message": { "id": 987654, "subject_id": 4567, "text": "Есть в наличии?", "direction": "in", … },
"sender": { "id": 94235311, "name": "Иван", "phone": "+7…", … },
"subject": { "type": "advert", "advert": { "title": "…", "price": 15000, … } }
}
}
message.id
— порядок доставки не гарантирован (ретраи).
MAX