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 — рекомендуемый
POST https://wappi.pro/api/sync/message/send?profile_id=PROFILE_ID
Authorization: YOUR_WAPPI_TOKEN
Content-Type: application/json{
"chat_id": "123456789012345@lid",
"body": "Здравствуйте! Получили ваше сообщение."
}Поле recipient можно не передавать.
Вариант B: LID в recipient
Тот же метод принимает:
{
"recipient": "123456789012345@lid",
"body": "Здравствуйте! Получили ваше сообщение."
}Передавайте суффикс @lid обязательно. Поле только с цифрами будет обработано как телефон, а не как LID.
Вариант C: обычный номер телефона
{
"recipient": "79991234567",
"body": "Здравствуйте!"
}Если переданы оба поля
Если указан корректный chat_id с @lid, он имеет приоритет над recipient. Это не отправка по двум адресам и не автоматическая повторная отправка по номеру при ошибке LID. Чтобы избежать неоднозначности, передавайте один выбранный адрес.
Полный пример cURL
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:
входящее сообщение: whatsapp_chat_id
↓ сохранить без изменений
исходящий запрос: chat_idУчебный фрагмент объекта входящего сообщения — не полный конверт webhook:
{
"id": "EXAMPLE_MESSAGE_ID",
"from": "123456789012345@lid",
"whatsapp_chat_id": "123456789012345@lid",
"body": "Здравствуйте! Хочу уточнить наличие."
}В таком событии from тоже содержит LID: телефон отправителя не представлен этим адресом. Создайте или найдите контакт по LID, сохраните сообщение и отвечайте по chat_id — отсутствие телефона не должно блокировать обработку.
Возможен и другой вариант:
{
"id": "EXAMPLE_MESSAGE_ID_2",
"from": "79991234567@c.us",
"whatsapp_chat_id": "123456789012345@lid",
"body": "Здравствуйте!"
}Здесь одновременно известны телефонный адрес и LID. Это не следует помечать как «номер скрыт» только из-за наличия whatsapp_chat_id. Сохраните оба идентификатора как связь одного контакта в контексте данного профиля.
Как выбирать адрес ответа в личном диалоге
- Если
whatsapp_chat_idсодержит полный LID вида<цифры>@lid, используйте его какchat_id. - Если это поле отсутствует, но
fromуже содержит полный@lid, сохраните этот LID и используйте его какchat_id. - Иначе используйте подтверждённый телефон из телефонного адреса, например
79991234567@c.us, черезrecipient. - Если ни LID, ни подтверждённого телефона нет, не выдумывайте адрес: сохраните событие для разбора.
4. Получение истории по LID
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
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 → телефон
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— querychat_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. План перехода интеграции
- Добавьте строковое поле LID отдельно от телефона и храните его вместе с
profile_id. - Обновите обработчик входящих сообщений: сохраняйте
whatsapp_chat_idи не отбрасывайте сообщения без телефона. - Для личных диалогов выбирайте LID, если он известен; иначе оставьте прежний маршрут по телефону.
- Не удаляйте
@lid, не добавляйте+, код страны или суффикс@c.usк цифрам LID. - Сопоставляйте контакт по подтверждённой связи телефон ↔ LID, а не по совпадению имени. Сохраняйте существующую историю и связи CRM.
- Разделите адрес группы и идентификатор её участника.
- Проверьте на согласованном тестовом контакте входящее сообщение, ответ текстом, отправку файла, чтение истории и финальный delivery status. Отдельно проверьте обратную совместимость обычного телефона.
- Не делайте повторную отправку «на всякий случай» только из-за смены формата адреса: это может породить дубли.
Кратко
Получили whatsapp_chat_id с @lid → сохранили целиком → отправили как chat_id через тот же профиль.
Если интеграции удобнее единое поле назначения, актуальные методы отправки также принимают полный @lid в recipient. Телефон для продолжения переписки не обязателен.
