WhatsApp API: переход на работу с @lid

Назад к списку статей
Содержание

1. Что такое LID

LID — идентификатор пользователя в WhatsApp, который в API имеет вид 123456789012345@lid. Это не телефонный номер и не «лид»/сделка в CRM.

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

  • Если известен только LID, по нему можно продолжать переписку — получать телефон для отправки не обязательно.
  • LID нельзя вычислить из номера телефона или превратить в телефон удалением @lid.
  • Храните LID строкой, целиком вместе с суффиксом. Не преобразуйте его в числовой тип.
  • Телефон и LID храните отдельно. Не записывайте цифры LID в поле телефона CRM.
  • Сохраняйте связку с profile_id, через который получено сообщение. Для ответа используйте тот же профиль.
  • Обычная отправка по номеру продолжает работать: переход не требует немедленно заменять все сохранённые телефоны на LID.

2. Отправка через chatid и recipient

Для новой интеграции рекомендуется chat_id. В актуальной версии поддерживается и полный LID в recipient.

Вариант A: LID в chatid — рекомендуемый

http
POST https://wappi.pro/api/sync/message/send?profile_id=PROFILE_ID
Authorization: YOUR_WAPPI_TOKEN
Content-Type: application/json
json
{
  "chat_id": "123456789012345@lid",
  "body": "Здравствуйте! Получили ваше сообщение."
}

Поле recipient можно не передавать.

Вариант B: LID в recipient

Тот же метод принимает:

json
{
  "recipient": "123456789012345@lid",
  "body": "Здравствуйте! Получили ваше сообщение."
}

Передавайте суффикс @lid обязательно. Поле только с цифрами будет обработано как телефон, а не как LID.

Вариант C: обычный номер телефона

json
{
  "recipient": "79991234567",
  "body": "Здравствуйте!"
}

Если переданы оба поля

Если указан корректный chat_id с @lid, он имеет приоритет над recipient. Это не отправка по двум адресам и не автоматическая повторная отправка по номеру при ошибке LID. Чтобы избежать неоднозначности, передавайте один выбранный адрес.

Полный пример cURL

bash
curl --request POST \
  'https://wappi.pro/api/sync/message/send?profile_id=PROFILE_ID' \
  --header 'Authorization: YOUR_WAPPI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"chat_id":"123456789012345@lid","body":"Здравствуйте!"}'

Для асинхронной отправки используйте /api/async/message/send с теми же полями адресации. HTTP 200 асинхронного метода означает принятие задачи, а не доставку: проверяйте итог задачи и события delivery_status.

3. Получение сообщения и поле LID в webhook

Для получения входящих сообщений должен быть настроен webhook и включён тип события incoming_message. Отдельного типа события для LID не требуется.

Нужное поле в объекте сообщения: whatsapp_chat_id. Для отправки его значение переносится в поле запроса chat_id:

text
входящее сообщение: whatsapp_chat_id
                    ↓ сохранить без изменений
исходящий запрос:   chat_id

Учебный фрагмент объекта входящего сообщения — не полный конверт webhook:

json
{
  "id": "EXAMPLE_MESSAGE_ID",
  "from": "123456789012345@lid",
  "whatsapp_chat_id": "123456789012345@lid",
  "body": "Здравствуйте! Хочу уточнить наличие."
}

В таком событии from тоже содержит LID: телефон отправителя не представлен этим адресом. Создайте или найдите контакт по LID, сохраните сообщение и отвечайте по chat_id — отсутствие телефона не должно блокировать обработку.

Возможен и другой вариант:

json
{
  "id": "EXAMPLE_MESSAGE_ID_2",
  "from": "79991234567@c.us",
  "whatsapp_chat_id": "123456789012345@lid",
  "body": "Здравствуйте!"
}

Здесь одновременно известны телефонный адрес и LID. Это не следует помечать как «номер скрыт» только из-за наличия whatsapp_chat_id. Сохраните оба идентификатора как связь одного контакта в контексте данного профиля.

Как выбирать адрес ответа в личном диалоге

  1. Если whatsapp_chat_id содержит полный LID вида <цифры>@lid, используйте его как chat_id.
  2. Если это поле отсутствует, но from уже содержит полный @lid, сохраните этот LID и используйте его как chat_id.
  3. Иначе используйте подтверждённый телефон из телефонного адреса, например 79991234567@c.us, через recipient.
  4. Если ни LID, ни подтверждённого телефона нет, не выдумывайте адрес: сохраните событие для разбора.

4. Получение истории по LID

http
GET https://wappi.pro/api/sync/messages/get?profile_id=PROFILE_ID&chat_id=123456789012345%40lid&limit=50&offset=0&mark_all=false
Authorization: YOUR_WAPPI_TOKEN

%40 — URL-кодирование символа @. Через HTTP-клиент удобнее передавать параметры отдельно и поручить ему кодирование.

В этом GET-методе LID передаётся в query-параметре chat_id, а не в JSON-теле и не в whatsapp_chat_id. История зависит от сообщений, доступных профилю; запрос не гарантирует получение всей давней переписки с телефона.

5. Как получить LID по телефону и телефон по LID

Телефон → LID

http
GET https://wappi.pro/api/sync/contact/check?profile_id=PROFILE_ID&phone=79991234567
Authorization: YOUR_WAPPI_TOKEN

При успешной проверке смотрите:

  • on_whatsapp — результат проверки номера;
  • chat_id — LID, если удалось получить соответствие.

Сохраняйте непустой chat_id с @lid. Отсутствие LID в ответе не равнозначно on_whatsapp=false: это разные результаты.

Параметр phone предназначен для телефона. Не передавайте туда LID.

LID → телефон

http
GET https://wappi.pro/api/sync/contact/phone/get?profile_id=PROFILE_ID&lid=123456789012345%40lid
Authorization: YOUR_WAPPI_TOKEN

Параметр lid принимает полный LID с суффиксом или его цифровую часть. Исключение касается именно этого специального параметра: для отправки в chat_id/recipient сохраняйте @lid.

При успешном результате status=done ответ содержит phone и chat_id. Получение телефона не гарантировано: соответствие может быть недоступно профилю. Обрабатывайте status=error и detail/error.

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

6. Методы с поддержкой LID-адресации

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

Отправка: sync и async

Для следующих POST-методов доступны варианты /api/sync/… и /api/async/…. Поля назначения — chat_id либо полный LID в recipient:

ОперацияПуть после /api/sync или /api/async
Текст/message/send
Изображение/message/img/send
Документ/message/document/send
Аудио/message/audio/send
Видео/message/video/send
Файл по URL/message/file/url/send
Геолокация/message/location/send
Карточка контакта/contact/send
Пересылка сообщения/message/forward
Ответ на сообщение/message/reply
Опрос/poll/create

У /contact/send LID указывает получателя карточки; телефон внутри передаваемой карточки — отдельный параметр, его не нужно заменять на LID.

Важное текущее ограничение /message/reply: LID-маршрутизация поддерживается, но это не устраняет отдельный известный дефект цитирования медиа и части текстовых сообщений. status=done не подтверждает отображение цитаты на телефоне. До отдельного подтверждения исправления не считайте поддержку LID гарантией корректности таких цитат.

История и управление чатом

  • GET /api/sync/messages/get — query chat_id=<LID>.
  • POST /api/sync/chat/archive — архивирование.
  • POST /api/sync/chat/unarchive — возврат из архива.
  • POST /api/sync/chat/pin — закрепление/открепление; также передайте pin: true или pin: false.
  • POST /api/sync/chat/delete — удаление чата; операция изменяет состояние.
  • POST /api/sync/chat/typing/start — включение индикатора набора.
  • POST /api/sync/chat/typing/stop — выключение индикатора набора.

Для перечисленных POST-методов адрес передаётся в JSON через chat_id либо полный LID в recipient.

Специальные методы контактов

  • GET /api/sync/contact/check — проверка телефона, с возможностью получить LID в ответе.
  • GET /api/sync/contact/phone/get — попытка получить телефон по параметру lid.
  • POST /api/sync/contact/rename — переименование контакта; LID передаётся через recipient, а не через chat_id. Также передаются name и/или last_name.

Не распространяйте правило «везде можно передать LID» на остальные методы автоматически. В частности, /contact/get и /contact/info используют другую валидацию и не включены в этот список LID-методов. Старый /message/file/send, отключённые buttons/list и OTP не рекомендуются здесь как проверенный путь миграции на LID.

7. План перехода интеграции

  1. Добавьте строковое поле LID отдельно от телефона и храните его вместе с profile_id.
  2. Обновите обработчик входящих сообщений: сохраняйте whatsapp_chat_id и не отбрасывайте сообщения без телефона.
  3. Для личных диалогов выбирайте LID, если он известен; иначе оставьте прежний маршрут по телефону.
  4. Не удаляйте @lid, не добавляйте +, код страны или суффикс @c.us к цифрам LID.
  5. Сопоставляйте контакт по подтверждённой связи телефон ↔ LID, а не по совпадению имени. Сохраняйте существующую историю и связи CRM.
  6. Разделите адрес группы и идентификатор её участника.
  7. Проверьте на согласованном тестовом контакте входящее сообщение, ответ текстом, отправку файла, чтение истории и финальный delivery status. Отдельно проверьте обратную совместимость обычного телефона.
  8. Не делайте повторную отправку «на всякий случай» только из-за смены формата адреса: это может породить дубли.

Кратко

Получили whatsapp_chat_id с @lid → сохранили целиком → отправили как chat_id через тот же профиль.

Если интеграции удобнее единое поле назначения, актуальные методы отправки также принимают полный @lid в recipient. Телефон для продолжения переписки не обязателен.