В API ChatArchitect появились новые поля user_id, parent_user_id и username
API ChatArchitect предоставляет дополнительные идентификаторы пользователей WhatsApp: user_id, parent_user_idи username. Они позволяют работать с пользователями, которые взаимодействуют с компанией через имя пользователя и не раскрывают свой реальный номер телефона.
В то же время ChatArchitect сохраняет полную совместимость с существующими CRM-системами, службами поддержки, чат-ботами и другими интеграциями, которые предполагают наличие номера телефона у каждого пользователя WhatsApp.
Если реальный номер телефона пользователя недоступен, ChatArchitect автоматически создает для него синтетический номер. Таким образом, поле для ввода номера телефона остается видимым:
- Входящих сообщениях.
- В веб-хуках состояния.
- В других связанных вебхуках.
- При отправке исходящих сообщений.
Интеграция может продолжать использовать номер телефона в качестве основного идентификатора контакта без изменения существующей логики.
Краткое содержание
Входящие сообщения используют следующие поля:
payload.sender.phone payload.sender.user_id payload.sender.parent_user_id payload.sender.username
Использование веб-хуков статуса:
payload.destination payload.userId payload.parentUserId payload.profileUsername
Для отправки сообщения используйте один из следующих способов:
место назначения
или:
ID пользователя
Параметр destination принимает либо реальный номер телефона, либо синтетический номер, созданный ChatArchitect.
Параметр userId принимает либо BSUID, либо BSUID родительского объекта.
1. Что означает user_id
user_id — это идентификатор пользователя, относящийся к конкретной бизнес-задаче, сокращенно обозначаемый как BSUID.
Идентификатор BSUID однозначно идентифицирует пользователя WhatsApp в рамках конкретной компании. Он создается для каждой комбинации «компания-пользователь» и позволяет взаимодействовать с пользователем, даже если его реальный номер телефона недоступен.
Идентификатор BSUID создается независимо от того, указал ли пользователь имя пользователя в WhatsApp.
Примеры BSUID:
США.13491208655302741918 Индиана.34661116580198991
Идентификатор начинается с двухбуквенного кода страны по стандарту ISO, за которым следует точка и уникальная последовательность символов.
Общий формат:
<ISO country code>.<unique identifier>
Пример:
СК.34661116580198991
Сохраните BSUID точно в том виде, в котором он получен из API ChatArchitect.
Не:
- Измените регистр букв.
- Удалите код страны.
- Удалите точку.
- Преобразуйте значение в число.
- Сократите идентификатор.
- Сгенерируйте BSUID самостоятельно.
Идентификатор BSUID может измениться, например, если пользователь изменит номер телефона, связанный с WhatsApp. В этом случае обработайте изменение и обновите сохраненные данные пользователя.
2. Где найти user_id во входящем веб-хуке?
В исходящем сообщении идентификатор BSUID находится по следующему адресу:
payload.sender.user_id
Пример:
{ "version": 2, "type": "message", "payload": { "sender": { "phone": "4210012345678", "user_id": "SK.34661116580198991", "parent_user_id": "", "name": "Customer name", "username": "customer_username" } } }
Объект отправителя содержит номер телефона и дополнительные идентификаторы пользователя :
идентификатор пользователя телефона идентификатор родителя имя пользователя
Поле номера телефона всегда присутствует.
Если реальный номер пользователя доступен, то в телефоне содержится информация о реальном номере.
Если реальный номер недоступен, ChatArchitect создает синтетический номер и возвращает его в том же телефона .
Это позволяет устаревшим интеграциям продолжать работать без обязательной поддержки BSUID.
3. Синтетические данные ChatArchitect
Если пользователь взаимодействует с компанией через имя пользователя WhatsApp и не указывает свой настоящий номер телефона, ChatArchitect автоматически создает для этого пользователя синтетический номер.
Общий формат:
+<country code> 00<internal identifier>
Ключевым признаком синтетического номера являются две цифры 00, следующие непосредственно за кодом страны.
Пример:
+42100...
Здесь:
+421
это код страны, и:
00
Это означает, что номер был создан программой ChatArchitect и не является реальным номером телефона пользователя.
Как распознать синтетическое число
Сначала определите код страны, затем проверьте первые цифры национальной части номера.
Если первые две цифры после кода страны равны 00, то это синтетический номер ChatArchitect.
Шаблон:
+<country_code> 00<identifier>
Перед проверкой номера убедитесь, что международный код страны правильно его расшифровал. Не следует предполагать, что код страны всегда состоит из одной, двух или трех цифр, не расшифровав его предварительно.
Рекомендуемая логика:
1. Определите международный код страны. 2. Отделите код страны от национальной части. 3. Проверьте, начинается ли национальная часть с 00. 4. Если да, то это синтетический номер ChatArchitect.
Синтетическое число:
- Это не настоящий номер телефона пользователя.
- Не предназначен для обычных телефонных звонков.
- Не использовать для SMS.
- Используется в ChatArchitect и связанных с ним интеграциях.
- Сохраняет устаревшие модели данных, в которых номер телефона является обязательным идентификатором.
- Может использоваться для отправки сообщений через API ChatArchitect.
4. Отправка сообщения на синтетический номер
Для отправки исходящего сообщения используйте стандартный параметр:
место назначения
Он принимает:
- Реальный номер телефона WhatsApp.
- Синтетический номер из ChatArchitect.
Пример:
destination=4210012345678
Интеграция не требует преобразования синтетического номера в BSUID. ChatArchitect определяет связанного пользователя и отправляет сообщение нужному получателю WhatsApp.
Это позволяет устаревшим интеграциям продолжать использовать тот же рабочий процесс:
контакт → номер телефона → отправить сообщение
Даже если WhatsApp не предоставляет реальный номер пользователя, интеграция все равно получает номера телефона , которое можно сохранить в CRM и использовать в качестве целевого адреса.
5. user_id в веб-хуке события выставления счетов
В веб-хуке для выставления счетов идентификатор BSUID находится по следующему адресу:
payload.references.user_id
Пример:
{ "version": 2, "type": "billing-event", "payload": { "references": { "destination": "4210012345678", "user_id": "SK.1009956278697109" } } }
В этом веб-хуке:
место назначения
Содержит число, использованное при интегрировании. Это может быть как действительное, так и синтетическое число.
Поле:
ID пользователя
Содержит BSUID пользователя WhatsApp.
Обратите внимание, что для событий выставления счетов используется:
ID пользователя
нет:
ID пользователя
6. Что означает parent_user_id
parent_user_id — это идентификатор родительского объекта (Parent BSUID).
Обычный BSUID идентифицирует пользователя в рамках конкретного бизнеса или бизнес-портфеля. Родительский BSUID предназначен для крупных организаций, управляемых предприятий и структур, использующих несколько связанных бизнес-менеджеров или бизнес-портфелей.
Идентификатор родительского бизнес-подразделения (Parent BSUID) позволяет идентифицировать одного и того же конечного пользователя в различных бизнес-портфелях, принадлежащих одной крупной организации.
В исходящем сообщении это поле находится по следующему адресу:
payload.sender.parent_user_id
Пример:
{ "payload": { "sender": { "phone": "4210012345678", "user_id": "SK.34661116580198991", "parent_user_id": "SK.PARENT_IDENTIFIER", "username": "customer_username" } } }
Параметр parent_user_id может быть пустым, если родительский BSUID не используется или недоступен для соответствующей бизнес-структуры.
Следовательно, интеграция должна рассматривать это как необязательный шаг.
Правильная логика:
phone — всегда присутствует; user_id — основной BSUID пользователя; parent_user_id — дополнительный идентификатор для подключенных бизнес-портфелей; username — текущее имя пользователя WhatsApp, если доступно.
7. Что означает имя пользователя
Имя пользователя — это имя пользователя, выбранное конечным пользователем в WhatsApp.
Имя пользователя необязательно. Пользователь может:
- Укажите имя пользователя.
- Измените это.
- Удалите его.
- Используйте это для общения, не раскрывая их настоящий номер телефона.
Изменение имени пользователя не означает, что пользователь изменился.
В частности, изменение имени пользователя:
- Это не обязательно изменяет BSUID.
- Не следует создавать новый контакт в CRM.
- Не следует рассматривать его как единственный постоянный идентификатор.
- Необходимо обновить отображаемое имя пользователя существующего контакта.
Входящий веб-хук содержит имя пользователя по следующему адресу:
payload.sender.username
Пример:
{ "payload": { "sender": { "phone": "4210012345678", "user_id": "SK.34661116580198991", "parent_user_id": "", "name": "Имя клиента", "username": "customer_username" } } }
В качестве имени пользователя можно использовать:
- В качестве отображаемого имени для агента.
- Для поиска контакта.
- Для персонализации интерфейса.
- В качестве дополнительного поля CRM.
- В истории сообщений.
- Для поддержания актуальности профиля пользователя.
Не используйте имя пользователя в качестве первичного ключа, поскольку пользователь может его изменить.
Для надежной идентификации используйте:
ID пользователя
или номер из:
телефон
В ChatArchitect номер телефона всегда доступен, даже если реальный номер пользователя скрыт.
8. Входящий веб-хук, когда реальный номер скрыт
Если реальный номер телефона пользователя недоступен, ChatArchitect не удаляет "Телефон" .
Вместо этого он содержит синтетическое число:
{ "version": 2, "type": "message", "payload": { "sender": { "phone": "4210012345678", "user_id": "SK.34661116580198991", "parent_user_id": "", "name": "", "username": "customer_username", "country_code": "421", "dial_code": "+421" } } }
В этом примере:
4210012345678
является синтетическим, потому что за кодом страны 421 сразу следует 00.
Интеграция может обрабатывать событие как обычное сообщение от пользователя с реальным числом:
- Найти контакт по
телефону. - Если контакта не существует, создайте его.
- Сохраните
user_id. - Если указан
parent_user_id, его следует сохранить - Сохранить или обновить
имя пользователя. - Добавить входящее сообщение в историю.
- Для последующих исходящих сообщений используйте
телефон
Это обеспечивает доступность обязательного поля для ввода номера телефона и предотвращает сбои в работе устаревших интеграций.
9. Поля в веб-хуке состояния
Вебхуки для проверки статуса исходящих сообщений используют следующие поля:
payload.destination payload.userId payload.parentUserId payload.profileUsername
Названия полей отличаются от названий полей во входящем веб-хуке.
| Ценить | Входящее сообщение | Веб-перехватчик статуса |
|---|---|---|
| Число | отправитель.телефон |
место назначения |
| БСУИД | sender.user_id |
ID пользователя |
| Родительский BSUID | sender.parent_user_id |
parentUserId |
| Имя пользователя | sender.username |
имя пользователя профиля |
Пример:
{ "version": 2, "type": "message-event", "payload": { "type": "delivered", "destination": "4210012345678", "userId": "SK.34661116580198991", "parentUserId": "", "profileUsername": "customer_username" } }
Поле "Назначение" всегда присутствует.
В его состав входит:
- Реальное число, если таковое имеется.
- Синтетический номер в ChatArchitect, когда реальный номер скрыт.
Таким образом, веб-хуки статуса можно связать с исходящими сообщениями через привычное назначения .
Также можно использовать userId для более точной привязки события к пользователю WhatsApp.
10. Отправка сообщения через userId
Помимо отправки сообщений по номеру телефона, API ChatArchitect позволяет отправлять сообщения по BSUID.
Используйте этот параметр:
ID пользователя
Он принимает:
- Степень бакалавра наук в области информационных технологий (BSUID).
- Родительский BSUID.
Пример:
userId=SK.35263896023254374
Это отправляет сообщение непосредственно идентификатору пользователя, относящемуся к его бизнес-процессам.
Однако для большинства существующих интеграций достаточно продолжать использовать:
место назначения
Поскольку ChatArchitect предоставляет синтетический номер, для интеграции не требуется переключаться на userId.
11. Отправка как идентификатора получателя , так и идентификатора пользователя.
Один запрос может включать в себя оба варианта:
пункт назначения=<number> userId=<BSUID or Parent BSUID>
Если присутствуют оба параметра, приоритет имеет это поле:
место назначения
Иными словами, номер, переданный в пункт назначения , рассматривается как основной получатель.
Это правило также распространяется на синтетические числа в ChatArchitect.
Пример:
destination=4210012345678 userId=SK.34661116580198991
Для упрощения интеграции выберите один основной метод адресации:
- Укажите
пункт назначения,если система построена на основе телефонных номеров. - Используйте
userId,если система уже поддерживает BSUID в качестве основного идентификатора.
12. Проверка BSUID
Идентификатор BSUID проверяется при отправке сообщения.
API может немедленно вернуть ошибку, если предоставленное значение является:
- Неизвестный BSUID.
- Деформированный BSUID.
- Идентификатор BSUID, не принадлежащий данной компании.
- Поврежденное или усеченное значение.
Хранить BSUID без преобразования.
Например, не следует хранить только числовую часть:
34661116580198991
Сохраните полное значение:
СК.34661116580198991
В отличие от BSUID, в стандартном параметре назначения используется синтетический номер , который ChatArchitect преобразует в номер пользователя.
13. Ограничения на отправку через BSUID
Не все типы сообщений WhatsApp обязательно поддерживают отправку по BSUID.
Для неподдерживаемого типа сообщений API может вернуть следующую ошибку:
131062 Получатели с идентификаторами пользователей, имеющими бизнес-сферу, не поддерживаются для этого сообщения
В частности, шаблоны аутентификации требуют указания реального номера телефона и не поддерживают отправку только по BSUID.
Синтетический номер ChatArchitect не преобразует скрытый номер пользователя в реальный номер телефона. Это внутренний идентификатор адреса, и его нельзя использовать там, где Meta требует указания реального номера телефона конечного пользователя.
Для шаблонов аутентификации сначала получите реальный номер телефона пользователя.
14. Запрос контактной информации и получение реального номера телефона
Если пользователь добровольно предоставляет свой номер телефона через функцию «Запросить контактную информацию», веб-хук содержит как идентификаторы пользователя, так и предоставленный контакт.
Объект отправителя по-прежнему содержит:
payload.sender.phone payload.sender.user_id payload.sender.parent_user_id payload.sender.username
Реальное число, предоставленное пользователем, находится внутри контактной информации:
payload.payload.contacts[].phones[].phone payload.payload.contacts[].phones[].wa_id
Пример:
{ "payload": { "sender": { "phone": "4210012345678", "user_id": "SK.34661116580198991", "parent_user_id": "", "username": "customer_username", "country_code": "421", "dial_code": "+421" }, "payload": { "contacts": [ { "phones": [ { "phone": "+421900123456", "wa_id": "421900123456" } ] } ] } } }
В этом сценарии:
отправитель.телефон
может содержать созданный ранее синтетический номер ChatArchitect, при этом:
контакты[].телефоны[].телефон
содержит реальное число, добровольно предоставленное пользователем.
Интеграция может связывать:
- Синтетическое число.
- BSUID.
- Имя пользователя.
- Реальное число.
Это позволяет обновлять контактную информацию без создания дубликата пользователя.
15. Как сохранить новые поля в CRM или базе данных?
Рекомендуемая структура контактов:
телефон is_synthetic_phone user_id parent_user_id username real_phone
Где:
телефон
Это основной номер, используемый при интегрировании. Он всегда присутствует и может быть действительным или синтетическим.
is_synthetic_phone
Это означает, что номер начинается с 00 сразу после кода страны.
ID пользователя
— это BSUID пользователя.
parent_user_id
— это родительский BSUID, если он доступен.
имя пользователя
— это текущее имя пользователя WhatsApp.
реальный_телефон
Это реальный номер пользователя, если он был изначально доступен или был предоставлен добровольно позже.
Пример:
{ "phone": "4210012345678", "is_synthetic_phone": true, "user_id": "SK.34661116580198991", "parent_user_id": null, "username": "customer_username", "real_phone": null }
После получения действительного числа:
{ "phone": "4210012345678", "is_synthetic_phone": true, "user_id": "SK.34661116580198991", "parent_user_id": null, "username": "customer_username", "real_phone": "421900123456" }
Точная модель хранения данных может различаться, но не следует создавать нового пользователя только потому, что появилось или изменилось имя пользователя.
16. Рекомендуемый порядок идентификации пользователей
Для новых интеграций используйте следующий порядок:
- Найдите пользователя по
user_id. - Если пользователя не удалось найти, выполните поиск по
телефону. - Также обратите внимание на
parent_user_id. - Не используйте
имя пользователяв качестве единственного постоянного идентификатора. - Когда появится реальный номер, свяжите его с существующим BSUID и синтетическим номером.
Устаревшие интеграции могут сохранить свою текущую логику:
- Найдите пользователя по
телефону. - Создайте контакт по
телефону, если он не существует. - Отправляйте сообщения через
пункт назначения. - Постепенно добавляйте хранилище для
user_id,parent_user_idиusername.
Использование синтетических чисел позволяет осуществить это обновление без срочной переработки существующей интеграции.
17. Краткое описание полевых исследований
| Поле | Расположение | Цель |
|---|---|---|
телефон |
payload.sender.phone |
Действительное или синтетическое число; всегда присутствует |
место назначения |
полезная нагрузка.назначение |
Число в веб-перехватчике состояния и параметр для отправки |
ID пользователя |
payload.sender.user_id |
BSUID во входящем сообщении |
ID пользователя |
payload.userId или параметр API |
BSUID в веб-хуке состояния и исходящем запросе |
parent_user_id |
payload.sender.parent_user_id |
Родительский BSUID во входящем сообщении |
parentUserId |
payload.parentUserId |
Родительский BSUID в веб-хуке состояния |
имя пользователя |
payload.sender.username |
Имя пользователя WhatsApp во входящем сообщении |
имя пользователя профиля |
payload.profileUsername |
Имя пользователя WhatsApp в веб-хуке статуса |
references.user_id |
payload.references.user_id |
BSUID в событии выставления счетов |
Ключевой момент для существующих интеграций
ChatArchitect сохраняет существующую модель, в которой требуется номер телефона.
Даже если WhatsApp не предоставляет реальный номер телефона пользователя:
sender.phoneпо-прежнему присутствует.Пункт назначенияприсутствует в веб-хуках состояния.- Сообщения можно отправлять через
пункт назначения. - Контакты можно хранить в CRM-системе по номеру.
- Синтетический номер можно идентифицировать по
цифре 00,следующей сразу за кодом страны. - Также доступны BSUID, родительский BSUID и имя пользователя.
Это обеспечивает поддержку новых функций имен пользователей WhatsApp и BSUID без нарушения совместимости с устаревшими CRM-системами, службами поддержки, чат-ботами и пользовательскими интеграциями.
Комментарии отсутствуют
Комментарии отсутствуют