Справочник API

Contacts

Список контактов

Возвращает контакты в реальном времени. limit: 1..100, по умолчанию 50. Невалидные или устаревшие cursor обрабатываются провайдерами по-разному.

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/contacts

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

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

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

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

Заголовки

X-Api-Key
stringобязательно

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

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

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

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

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

cursor
string

Непрозрачный next_cursor. Пропустите для первой страницы; невалидные или устаревшие курсоры обрабатываются провайдерами по-разному.

limit
integer

Размер страницы от 1 до 100; значение по умолчанию указано на странице эндпоинта.

minimum: 1 · maximum: 100

q
string

Поисковый фильтр по display_name, phone или username.

updated_since
string

Метка времени RFC3339; возвращает только контакты, обновлённые с этого момента, для инкрементальной синхронизации там, где провайдер её поддерживает.

format: date-time

Тело запроса

Этот эндпоинт не требует JSON-тела запроса.

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

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

Ответ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "id": "user_example",
        "conversation_id": "peer_example",
        "display_name": "Alice",
        "avatar_url": "",
        "provider_user_id": "user_example",
        "extra": {
          "phone": "8600000000000"
        }
      }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

Тело ответа

id
string

Идентификатор контакта.

conversation_id
string

Идентификатор беседы для этого контакта; используйте его для отправки сообщений или поиска чата.

display_name
string

Отображаемое имя контакта или пустая строка, если оно отсутствует.

avatar_url
string

URL аватара контакта или пустая строка, если он отсутствует.

provider_user_id
string

Идентификатор пользователя на стороне провайдера для контакта.

is_blocked
boolean

Заблокирован ли контакт подключённым аккаунтом.

extra
object

Дополнительные поля, специфичные для провайдера, например phone.

phone
string

WhatsApp phone JID 中解析出的纯手机号。

first_name
string

当前账号通讯录中保存的联系人简称或名字部分。

full_name
string

当前账号通讯录中保存的完整联系人名称。

push_name
string

联系人自行在 WhatsApp 设置的个人名称。

business_name
string

WhatsApp Business 账号的商业或认证名称。

redacted_phone
string

Provider 仅返回部分号码时的遮蔽手机号。

next_cursor
string

Непрозрачный курсор для следующей страницы. Передайте его обратно как cursor; пустая строка означает, что больше страниц нет.

has_more
boolean

true, когда за пределами этой страницы доступно больше результатов.

Ответы

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

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 и активность рабочего пространства.