Справочник API

Contacts

Получить контакт

Обычный отсутствующий контакт возвращает 404 contact_not_found. Если не существует целевая беседа, возвращается 422 contact_not_found, numeric_code 35000 и сообщение Conversation not found.

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

Поддерживаемые каналы

WhatsAppLINEWhatsApp Protocol

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

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

Откуда взять параметры
account_id
Возьмите data.id из создания или запроса аккаунта. Идентификатор относится к рабочему пространству X-Api-Key. Получить аккаунт
contact_id
Идентификатор контакта у провайдера; передавайте как непрозрачную строку. whatsapp и whatsapp-protocol используют LID (xxx@lid). whatsapp-protocol может вернуть успех даже при отсутствии полей профиля контакта; ориентируйтесь на фактически возвращённые поля.

WhatsApp Protocol: Для сведений о контакте нужен существующий LID (xxx@lid). Используйте data.sender.id или data.conversation.id только с окончанием @lid. Protocol не предоставляет список контактов, а этот API не вычисляет LID по номеру телефона. Без LID выполнить запрос нельзя. Успешный ответ может не содержать часть профиля.

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

Заголовки

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

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

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

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

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

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

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

Идентификатор контакта у провайдера; передавайте как непрозрачную строку. whatsapp и whatsapp-protocol используют LID (xxx@lid). whatsapp-protocol может вернуть успех даже при отсутствии полей профиля контакта; ориентируйтесь на фактически возвращённые поля.

Тело запроса

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

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

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

Ответ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "user_example",
    "conversation_id": "peer_example",
    "display_name": "Alice",
    "avatar_url": "",
    "provider_user_id": "user_example",
    "extra": {
      "phone": "8600000000000"
    }
  }
}

Тело ответа

id
string

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

conversation_id
string

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

display_name
string

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

avatar_url
string

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

provider_user_id
string

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

is_blocked
boolean

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

extra
object

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

phone
string

Номер телефона, извлечённый из телефонного JID WhatsApp.

first_name
string

Краткое имя контакта или его личное имя, сохранённое в адресной книге текущего аккаунта.

full_name
string

Полное имя контакта, сохранённое в адресной книге текущего аккаунта.

push_name
string

Имя профиля, которое контакт самостоятельно указал в WhatsApp.

business_name
string

Название компании или подтверждённое имя аккаунта WhatsApp Business.

redacted_phone
string

Замаскированный номер телефона, если провайдер возвращает только часть номера.

Ответы

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

404

Not Found

Запрошенный ресурс не найден. Сверьте error.code с текущей операцией.

409

Conflict

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

422

Unprocessable Entity

Запрос корректен, но целевую беседу провайдера разрешить не удалось.

500

Internal Server Error

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

501

Not Implemented

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

502

Bad Gateway

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

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

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

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