Руководство August 14, 2026

WhatsApp Contact API: добавить контакт или отправить vCard

Добавление контакта WhatsApp и отправка карточки контакта — это две разные задачи API. Чтобы изменить список контактов подключённого аккаунта, используйте POST /v1/accounts/{account_id}/contacts/add. Чтобы отправить в чат одну или несколько структурированных карточек, используйте POST /v1/messages с message.type: "contact". Отправка карточки не заменяет операцию с адресной книгой.

Главное

Add contact меняет список контактов подключённого messaging account.
Send contact доставляет контактные данные как сообщение пользователю или группе.
Для добавления нужен хотя бы один из параметров: phone_number или username.
Для отправки нужен непустой массив message.contacts, а в каждой карточке обязательно поле name.
Сейчас обе операции в UnifyPort предназначены для WhatsApp, но у них разные маршруты и разные ошибки при отсутствии поддержки.

Добавить контакт или отправить vCard: таблица выбора

Цель	Маршрут	Обязательные данные	Результат
Сохранить человека в списке контактов подключённого аккаунта	`POST /v1/accounts/{account_id}/contacts/add`	`phone_number` или `username`	Объект контакта с идентификаторами, включая `id` и `conversation_id`
Поделиться контактными данными в чате	`POST /v1/messages`	`account_id`, `to` и contact-сообщение как минимум с одной подписанной карточкой	Принятый результат сообщения с `message_id`

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

Если вы ещё выбираете общий способ подключения WhatsApp, сравните Cloud API, BSP и unofficial interface. История появления структурированных contact/vCard-сообщений описана в обновлении UnifyPort API.

Вариант 1: добавить контакт в подключённый аккаунт

Запрос из документации Add contact выглядит так:

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/contacts/add \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "8600000000000",
    "whatsapp_options": {
      "first_name": "Jane",
      "full_name": "Jane Doe",
      "sync_to_device_contacts": false
    }
  }'

Укажите хотя бы один из параметров phone_number или username. Настройки имени и синхронизации устройства, относящиеся к WhatsApp, должны находиться внутри whatsapp_options. Не переносите first_name, full_name или sync_to_device_contacts на верхний уровень.

При успехе API возвращает объект контакта. Сохраните полученный conversation_id, если он понадобится для последующих сообщений или операций со списком контактов. Не формируйте этот идентификатор самостоятельно из номера телефона — используйте ответ API.

Эта операция подходит для требований «сохранить человека», «добавить в адресную книгу подключённого аккаунта» или «получить канонические идентификаторы контакта и беседы после добавления». Провайдеры без такой операции возвращают 501 unsupported_by_provider.

Вариант 2: отправить одну или несколько карточек vCard

Документация Send contact message использует единый маршрут сообщений:

curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_8c21d0",
    "to": {
      "id": "8613912345678@s.whatsapp.net",
      "type": "user"
    },
    "message": {
      "type": "contact",
      "contacts": [
        {
          "name": "Jane Doe",
          "phones": [{ "number": "+8613800000000", "type": "CELL" }],
          "emails": [{ "address": "jane@example.com" }],
          "organization": "ACME",
          "title": "PM"
        }
      ]
    }
  }'

UnifyPort создаёт vCard из структурированного JSON, поэтому собирать строку BEGIN:VCARD вручную не нужно. Сам формат vCard стандартизирован в RFC 6350, а этот API принимает более узкий набор полей из документации.

В каждой карточке обязательно поле name. Поля phones[].number, emails[].address, organization и title необязательны. Массив может содержать одну или несколько карточек. Пустой массив или карточка без name приводят к 400 invalid_request. Для аккаунта не в WhatsApp этот тип сообщения возвращает 400 unsupported_message_type.

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

Безопасная последовательность, если нужны обе операции

Вызывайте /contacts/add, только если список контактов подключённого аккаунта действительно должен измениться.
Сохраните возвращённые идентификаторы, особенно conversation_id.
Отправьте карточку ответственного сотрудника отдельным запросом к /v1/messages.
Записывайте результаты двух вызовов отдельно. Успешное добавление не подтверждает приём сообщения, а принятое сообщение не подтверждает изменение адресной книги.
Обрабатывайте unsupported_by_provider, unsupported_message_type и invalid_request с учётом операции, которая вернула ошибку.

Такое разделение упрощает повторные попытки. Если нужно повторить отправку сообщения, не следует автоматически повторять уже успешное изменение адресной книги.

Ограничения и компромиссы

Сейчас обе контактные операции в UnifyPort имеют поддержку для WhatsApp. Если продукт должен одинаково работать с Telegram, LINE, TikTok, Zalo и X, проверьте матрицу возможностей и предусмотрите текстовый вариант вместо предположения о наличии структурированной карточки везде.

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

Частые вопросы

Отправка WhatsApp vCard добавляет человека в контакты подключённого аккаунта?

Нет. Для списка контактов используется /contacts/add, а для сообщения в чате — /v1/messages с message.type: "contact".

Можно отправить несколько карточек одним запросом?

Да. Добавьте несколько объектов в message.contacts. В каждом объекте должно быть поле name.

При добавлении контакта всегда нужен `phone_number`?

Нет. Достаточно хотя бы одного из двух полей: phone_number или username.

Можно отправить такую структурированную карточку через LINE или Telegram?

Документированная операция сейчас поддерживает WhatsApp. Для других провайдеров возвращается 400 unsupported_message_type.

Нужно самостоятельно формировать строку vCard?

Нет. Отправьте структурированный JSON по документации, и UnifyPort сформирует vCard.

Следующий шаг

Для обмена данными в чате начните с Send contact message API. Для управления адресной книгой используйте Add contact API.

Источники

Источники и поддержка провайдеров проверены 14 августа 2026 года.