Заметка контакта WhatsApp: задать или очистить частное имя

Чтобы задать частное отображаемое имя контакта WhatsApp через UnifyPort, вызовите POST /v1/accounts/{account_id}/contacts/note, передав contact_id и строку note. Для очистки явно передайте note: "". Операция меняет заметку контакта на стороне аккаунта, а не публичный профиль клиента, сообщение в чате или личный псевдоним отдельного оператора в CRM.

Главное

• В документации действие поддерживается для whatsapp, но не для всех провайдеров и не для whatsapp-protocol.
• Поле note обязательно. Пустая строка означает очистку; неизменённая форма не должна отправлять запрос.
• «Видно только аккаунту» не означает разграничение доступа между операторами общего входящего ящика.
• Запись заметки, синхронизация имён адресной книги и отправка сообщений — разные операции.

Какое именно имя вы меняете

В официальном сообщении об управлении контактами WhatsApp описывает работу с контактами на связанных устройствах. Это контекст для данных аккаунта, но не спецификация операции UnifyPort.

Задача	Подходящий уровень
Свое имя контакта для подключённого аккаунта	Заметка контакта UnifyPort
Псевдоним, видимый лишь одному оператору	Собственное хранилище и права доступа приложения
Изменения имён из адресной книги провайдера	Отдельное представление для синхронизации
Передача контактных данных в чате	Сообщение с карточкой контакта

Для входящих изменений адресной книги используйте руководство по contact.updated. Это событие не перезаписывает псевдонимы и не является документированным подтверждением записи заметки. Если нужно сохранить или передать контакт, см. добавление контакта и отправку vCard.

В интерфейсе стоит разделить «Имя для аккаунта» и «Мой псевдоним». Не называйте оба поля частным именем, незаметно меняя место сохранения.

Как задать и очистить заметку контакта WhatsApp

Справочник Set contact note определяет метод, запрос и успешный ответ. Перед включением кнопки сохранения для канала проверьте матрицу поддерживаемых действий.

Подготовьте серверный API-ключ рабочего пространства и выбранный аккаунт для обмена сообщениями. Найдите нужный контакт в этом же аккаунте по справочнику контактов. Храните идентификаторы как непрозрачные строки: не создавайте их из отображаемого имени и не считайте, что все операции принимают один формат.

Поле	Назначение
contact_id	Контакт, к которому применяется действие
note	Пользовательское отображаемое имя; "" очищает заметку

Функция JavaScript ниже иллюстрирует документированный вызов. Передавайте реальные идентификаторы, выбранные сервером, а ключ загружайте из защищённой конфигурации. Автоматических повторов здесь нет; это не полная реализация входящего ящика.

async function setContactNote({ apiKey, accountId, contactId, note }) {
  if (typeof note !== 'string') throw new TypeError('note must be a string');
  if (!accountId || !contactId) throw new Error('Select account and contact');

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/contacts/note`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ contact_id: contactId, note })
    }
  );
  const result = await response.json();
  return { httpStatus: response.status, result };
}

Для сохранения передайте одобренную пользователем строку. Для очистки вызовите ту же функцию с пустой строкой. Не подставляйте пустую строку вместо отсутствующего значения формы: иначе отсутствие правки превратится в очистку. Отклоняйте null на стороне приложения, не придумывая ещё один способ удаления значения.

Документированный успех — 200 OK с data.ok: true. Прежде чем показать «Сохранено», проверьте результат: завершение fetch само по себе не означает успех.

Как не затереть новую правку старым запросом

Ниже — рекомендации для приложения, а не дополнительные поля API или гарантии управления конкурентными записями:

1. Ограничивайте редактор и задания рабочим пространством, аккаунтом и контактом. Совпадение имён не является идентификатором.
2. Различайте отсутствие изменений, редактирование и явную очистку. При необходимости запрашивайте подтверждение очистки.
3. Выполняйте записи для одной цели последовательно внутри приложения. Убирайте повторные клики и отклоняйте устаревшие локальные задания до отправки.
4. Сохраняйте запрошенное значение, результат и request_id в соответствии с политикой хранения. Не записывайте API-ключ в журнал.
5. При тайм-ауте показывайте неизвестный результат. Не объявляйте операцию неудачной и не отправляйте старое значение автоматически: другой редактор мог уже сохранить новое.

Локальная последовательная обработка не координирует все связанные клиенты. Публичный справочник не определяет условие версии, отдельное поле для чтения заметки или гарантированный webhook об её изменении. Не стройте цикл подтверждения на придуманных полях. Проверьте поведение аккаунта в контролируемом тесте; если результат нельзя наблюдать, сохраняйте статус неопределённости.

В справочнике ошибок set_contact_note_failed обозначает сбой записи на сервере или у провайдера, а unsupported_by_provider — неподдерживаемое действие. Отсутствие поддержки не повод бесконечно повторять запрос.

Проверки и вопросы

Проверьте установку, замену, явную очистку, неизменённую форму, нестроковый ввод, две конкурирующие правки, неподдерживаемый провайдер и тайм-аут. Это предлагаемые тесты, а не результаты эксплуатации.

Это конфиденциальная заметка к обращению?

Нет. Справочник описывает заметку контакта как пользовательское отображаемое имя. Подробную историю обращения и чувствительные комментарии операторов храните в CRM с контролем доступа, не в поле имени.

Очистка заметки удаляет контакт?

Нет. Документированная операция очищает заметку. Она не удаляет контакт или сообщения.

Можно использовать её для LINE, Zalo или WhatsApp Protocol?

Текущая матрица описывает эту запись только для whatsapp. Неофициальный интерфейс UnifyPort унифицирует форму API, но не делает возможности каналов одинаковыми.

Можно подтверждать сохранение через contact.updated?

Нет. Событие описывает изменение имён адресной книги, а не гарантированную квитанцию записи пользовательской заметки.

Следующий шаг и источники

Изучите Set contact note и проверьте один контролируемый контакт, прежде чем разрешать изменения на стороне аккаунта в общем входящем ящике.

Проверено 2026-10-13:

• UnifyPort: Set contact note
• UnifyPort: поддержка действий
• UnifyPort: стандартные события
• WhatsApp: управление контактами