Беседы

Запросить историю диалога

Запрашивает более раннюю историю только личных чатов provider=whatsapp, исключая whatsapp-protocol. account_id должен быть одним непустым сегментом пути без пробельных символов и косых черт, включая закодированные; неверный путь возвращает 400 invalid_request. Сначала подпишитесь на conversation.history: доступные пакеты поступают асинхронно с data.history.source=on_demand. HTTP 202 и status=accepted означают только принятие запроса, не получение сообщений или завершение. request_id служит для диагностики HTTP, не является ID задачи и не связывает запрос с callback. Пакеты могут быть множественными, повторными, запоздалыми или вовсе не поступить. Для продолжения выберите самое раннее полученное нативное сообщение с содержимым и полными id, sent_at, direction для before; исключите синтетические записи type=call и не добавляйте type в before. Курсор следующей страницы и статус завершения отсутствуют: пустые пакеты, количество меньше limit и тайм-ауты не доказывают конец истории. Callback может прийти после тайм-аута HTTP; не повторяйте запрос автоматически. 400 может вернуть invalid_request, provider_invalid_request (в том числе для опоры на синтетическую запись звонка) или unsupported_conversation_type для групп/каналов. Другие провайдеры возвращают 501 unsupported_by_provider. Если путь корректен, но аккаунт отсутствует или не принадлежит текущему рабочему пространству, возвращается 404 account_not_found (numeric_code=20020); неклассифицированные внутренние ошибки возвращают 500 request_conversation_history_failed (numeric_code=37016).

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/conversations/history/request

Перед вызовом

Используйте X-Api-Key нужного рабочего пространства на сервере. Перед запуском замените все заполнители.

Откуда взять параметры

account_id: Возьмите data.id из создания или запроса аккаунта. Идентификатор относится к рабочему пространству X-Api-Key. Получить аккаунт

Запрос

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/conversations/history/request" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "100000000000002@lid",
  "before": {
    "message_id": "MSG_HISTORY_ANCHOR_001",
    "sent_at": "2026-09-28T03:00:00Z",
    "direction": "inbound"
  },
  "limit": 50
}'

Параметры запроса

Заголовки

X-Api-Key

stringобязательно

API-ключ рабочей области. Рабочая область определяется по этому заголовку.

Content-Type

stringобязательно

Используйте application/json при отправке JSON-тела запроса.

Параметры пути

account_id

stringобязательно

Идентификатор для маршрута раздела conversations.

Тело запроса

conversation_id

stringобязательно

Стандартный LID личного чата WhatsApp по шаблону ^[0-9]+@lid$, принадлежащий тому же диалогу, что и before. Номера телефонов и другие типы диалогов не принимаются.

pattern: ^[0-9]+@lid$

before

objectобязательно

Позиция одного нативного сообщения с содержимым в том же диалоге; все поля должны быть взяты из этого сообщения и не могут быть null. Синтетические записи звонков type=call недопустимы даже с тремя заполненными полями. Не включайте type в запрос.

message_id

stringобязательно

id нативного сообщения с содержимым, содержащий непробельный символ. ID синтетической записи звонка недопустим даже после удаления пробелов по краям. Нельзя подставлять id события верхнего уровня или HTTP request_id.

minLength: 1 · pattern: \S

sent_at

stringобязательно

Время отправки этого сообщения в RFC3339; число секунд Unix должно быть больше 0. Нельзя подставлять occurred_at события или текущее время.

format: date-time

direction

stringобязательно

Направление сообщения относительно текущего аккаунта: inbound — получение, outbound — отправка.

enum: inbound, outbound

limit

integer

Запрашиваемое количество, без гарантии фактического количества результатов. Значение 50 по умолчанию применяется только при отсутствии поля; null, 0, нецелые числа и значения больше 50 возвращают invalid_request. Допустимый диапазон: 1..50.

minimum: 1 · maximum: 50

Как понять результат

Следуйте описанию полей и HTTP-статуса. Успешный 204 не содержит тела; для диагностики используйте X-Request-Id. Следующий шаг указан в связанных операциях.

Ответ 202 Accepted

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "status": "accepted",
    "conversation_id": "100000000000002@lid",
    "limit": 50
  }
}

Тело ответа

status

string

accepted confirms request acceptance only, not receipt of history or completion.

enum: accepted

conversation_id

string

Standard conversation ID for this history request.

limit

integer

Effective requested count limit for this history request, from 1 to 50.

minimum: 1 · maximum: 50

Ответы

202

202 Accepted

Запрос выполнен. См. пример тела ответа.

400

Bad Request

Тело запроса, путь или параметры некорректны.

401

Unauthorized

Заголовок X-Api-Key отсутствует или недействителен.

404

Not Found

Запрошенный ресурс провайдера не найден.

409

Conflict

Запрошенная операция конфликтует с существующим аккаунтом провайдера или ресурсом.

500

Internal Server Error

Сервис столкнулся с неожиданной ошибкой.

501

Not Implemented

Выбранный провайдер не реализует эту операцию.

502

Bad Gateway

Адаптер или вышестоящий провайдер не смог завершить операцию.

При ошибке запроса

Проверьте HTTP и error.code/numeric_code, сохраните request_id. Исправьте параметры, завершите авторизацию или проверьте runtime. До повторной отправки или записи выясните результат предыдущей попытки. Справочник ошибок

invalid_request · 10000 · 400: Проверьте обязательные поля, форматы и условия канала, затем исправьте запрос.
invalid_api_key · 11001 · 401: Проверьте X-Api-Key и активность рабочего пространства.