Адресные сообщения | Документация для разработчиков
Адресные сообщения
Обновлено: 7 ноября 2025 г
Эта функция доступна только для компаний, расположенных в Индии, и их клиентов в Индии.
Сообщения с адресом позволяют пользователям проще делиться адресом доставки с компанией через WhatsApp.
Адресные сообщения — это интерактивные сообщения, состоящие из 4 основных частей:
заголовка , тела , нижнего колонтитула и действия . Внутри компонента действия бизнес-логика задаёт имя «address_message» и соответствующие параметры.В таблице ниже перечислены поля, поддерживаемые адресным сообщением.
| Название поля | Наклейка на дисплей | Тип ввода | Поддерживаемые страны | Ограничения |
|---|---|---|---|---|
имя | Имя | текст | Индия | Никто |
номер телефона | Номер телефона | тел | Индия | Только действительные номера телефонов |
in_pin_code | Пин-код | текст | Индия | Максимальная длина: 6 |
номер дома | Номер квартиры/дома | текст | Индия | Никто |
номер_этажа | Номер этажа | текст | Индия | Никто |
номер_башни | Номер башни | текст | Индия | Никто |
название_здания | Название здания/квартиры | текст | Индия | Никто |
адрес | Адрес | текст | Индия | Никто |
достопримечательность_район | Достопримечательность/Район | текст | Индия | Никто |
город | Город | текст | Индия | Никто |
состояние | Состояние | текст | Индия | Никто |
Пример вызова API
Это пример вызова API для отправки адресного сообщения.
«страна» является обязательным полем в параметрах действия. Если он не указан, возникнет ошибка проверки.curl -X POST \ 'https://graph.facebook.com/<API_VERSION> /<FROM_PHONE_NUMBER_ID> /messages' \ -H 'Авторизация: Bearer'<ACCESS_TOKEN> ' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<PHONE_NUMBER> ", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Спасибо за ваш заказ! Укажите адрес, по которому вы хотите получить этот заказ." }, "action": { "name": "address_message", "parameters": { "country": "<COUNTRY_ISO_CODE> " } } } }'Обработка ошибок
Если код города телефонного номера для указанной страны неверен, компании не смогут запросить адресное сообщение у получателя. Например, компании не смогут запросить адресное сообщение у получателя, у которого страна указана как «Индия», но телефонный номер имеет код города «65».
После отправки адресного сообщения компания ожидает, пока пользователь введёт адрес и отправит его обратно. Введённый пользователем адрес передаётся через веб-хук, зарегистрированный в процессе настройки .
Шаги обработки адресного сообщения
Процесс отправки адресного сообщения включает следующие этапы:
address_message.Пользователь взаимодействует с сообщением, нажав на кнопку призыва к действию (CTA), после чего открывается экран ввода адреса. Пользователь заполняет свой адрес и отправляет формуПосле отправки пользователем формы с адресом партнер получает уведомление через веб-хук, содержащее подробную информацию об адресе, предоставленном пользователемПример сообщения с адресом в Индии
На следующей диаграмме показана типичная последовательность обработки адресного сообщения.
Дополнительные параметры действия
Компания может передавать дополнительные атрибуты, такие как
значения , ошибки проверки или сохраненные адреса, в качестве параметров интерактивного действия. Информацию об использовании каждого из них вы найдете ниже.| Параметр действия | Использование |
|---|---|
ценности | Компании автоматически заполняют эти поля адреса (например, поле «Город» заполняется значением «Индия») |
сохраненные_адреса | Для бизнеса это означает возможность передачи сохраненных адресов, ранее связанных с пользователем. Пользователям предоставляется возможность выбрать сохраненный адрес вместо того, чтобы вводить его вручную |
validation_errors | Компании могут выдавать ошибки в полях адреса, и WhatsApp не позволит пользователю отправить адрес до тех пор, пока проблема (проблемы) не будут решены. |
Отправить адресное сообщение пользователю
Выполните
POST -запрос к / Используя API WhatsApp, отправить пользователю сообщение с сквозным шифрованием адреса:curl -X POST \ 'https://graph.facebook.com/<API_VERSION> /<FROM_PHONE_NUMBER_ID> /messages' \ -H 'Авторизация: Bearer'<ACCESS_TOKEN> ' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<PHONE_NUMBER> ", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Спасибо за ваш заказ! Укажите адрес, по которому вы хотите получить доставку." }, "action": { "name": "address_message", "parameters": "JSON Payload" } } }'Чтобы отправить сообщение с адресом, не имея сохраненных адресов, WhatsApp предложит пользователю или компании заполнить форму для ввода нового адреса.
curl -X POST \ 'https://graph.facebook.com/<API_VERSION> /<FROM_PHONE_NUMBER_ID> /messages' \ -H 'Авторизация: Bearer'<ACCESS_TOKEN> ' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "+91xxxxxxxxxx", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Спасибо за ваш заказ! Укажите адрес доставки." }, "action": { "name": "address_message", "parameters": { "country": "IN", "values": { "name": "<CUSTOMER_NAME> ", "номер_телефона": "+91xxxxxxxxxxxx" } } } } }'Чтобы отправить сообщение с сохраненными адресами, WhatsApp предложит пользователю или компании выбрать один из сохраненных адресов или добавить свой собственный. Пользователи могут проигнорировать сохраненный адрес и ввести новый.
curl -X POST \ 'https://graph.facebook.com/<API_VERSION> /<FROM_PHONE_NUMBER_ID> /messages' \ -H 'Авторизация: Bearer'<ACCESS_TOKEN> ' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "91xxxxxxxxxx", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Спасибо за ваш заказ! Укажите адрес, по которому вы хотите получить доставку." }, "action": { "name": "address_message", "parameters": { "country": "IN", "saved_addresses": [ { "id": "address1", "value": { "name": "<CUSTOMER_NAME> ", "номер_телефона": "+91xxxxxxxxxx", "почтовый_код": "400063", "номер_этажа": "8", "название_здания": "", "адрес": "крыло A, Cello Triumph, IB Patel Rd", "ориентир_район": "Горегаон", "город": "Мумбаи" } } ] } } } }'Проверьте свой ответ
В случае успешного ответа предоставляется
messages с идентификатором для вновь созданного сообщения.{ "messaging_product": "whatsapp", "contacts": [ { "input": "<PHONE_NUMBER> ", "wa_id": "<WHATSAPP_ID> " } ], "messages": [ { "id": "wamid.ID" } ] }Неудачный ответ содержит сообщение об ошибке. Дополнительную информацию разделах «Коды ошибок» и «Коды состояния»
Отправить адресное сообщение с ошибками проверки
В случае ошибки проверки на сервере компании пользователю следует повторно отправить адресное сообщение. Компания должна отправить обратно набор значений, ранее введенных пользователем, вместе с соответствующими ошибками проверки для каждого недопустимого поля, как показано в примерах полезной нагрузки ниже.
curl -X POST \ 'https://graph.facebook.com/<API_VERSION> /<FROM_PHONE_NUMBER_ID> /messages' \ -H 'Авторизация: Bearer'<ACCESS_TOKEN> ' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "91xxxxxxxxxx", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Спасибо за ваш заказ! Укажите адрес доставки." }, "action": { "name": "address_message", "parameters": { "country": "IN", "values": { "name": "CUSTOMER_NAME", "phone_number": "+91xxxxxxxxxx", "in_pin_code": "666666", "address": "Другое местоположение", "city": "Дели" }, "validation_errors": { "in_pin_code": "Нам не удалось определить этот почтовый индекс." } } } } }'Получайте уведомления о предоставлении адресных данных
Компании будут получать уведомления о предоставлении адресов через веб-хуки , подобные показанному ниже.
{ "messages": [ { "id": "gBGGFlAwCWFvAgmrzrKijase8yA", "from": "<PHONE_NUMBER> ", "interactive": { "type": "interactive", "action": "address_message", "nfm_reply": { "name": "address_message", "response_json": "<response_json from client> ", "тело": "<body text from client> " }, "timestamp": "1670394125" } } ] }Уведомление веб-перехватчика имеет следующие значения.
| Название поля | Тип | Описание |
|---|---|---|
интерактивный | Объект | Содержит ответ от клиента |
тип | Нить | nfm_reply будет указывать на то, что это ответ Native Flow Response (NFM) от клиента. |
nfm_reply | Объект | Содержит данные, полученные от клиента |
response_json | Нить | Значения полей адреса, заполненных пользователем в формате JSON, которые всегда присутствуют |
тело (необязательно) | Нить | Основной текст от клиента, то, что видит пользователь |
имя (необязательно) | Нить | address_message будет указывать тип ответа NFM-действия от клиента. |
Ниже показан ответ в виде адресного сообщения, представленный в формате NFM-ответа на запрос с адресом из Индии.
{ "messages": [ { "context": { "from": "FROM_PHONE_NUMBER_ID", "id": "wamid.HBgLMTIwNjU1NTAxMDcVAgARGBI3NjNFN0U5QzMzNDlCQjY0M0QA" }, "from": "<PHONE_NUMBER> ", "id": "wamid.HBgLMTIwNjU1NTAxMDcVAgASGCA5RDhBNENEMEQ3RENEOEEzMEI0RUExRDczN0I1NThFQwA=", "timestamp": "1671498855", "type": "interactive", "interactive": { "type": "nfm_reply", "nfm_reply": { "response_json": "{\"saved_address_id\":\"address1\",\"values\":{\"in_pin_code\":\"400063\",\"building_name\":\"\",\"landmark_area\":\"Goregaon\",\"address\":\"Wing A, Cello Triumph, IB Patel Rd\",\"city\":\"Мумбаи\",\"name\":\"ИМЯ_ПОЛЬЗОВАТЕЛЯ\",\"номер_телефона\":\"+91xxxxxxxxxx\",\"номер_этажа\":\"8\"}}", "body": "ИМЯ_ПОЛЬЗОВАТЕЛЯ\n +91xxxxxxxxxx\n 400063, Горегаон, крыло A, Cello Triumph, IB Patel Rd, Мумбаи, 8", "name": "адрес_сообщение" } } } ] }Функция не поддерживается
В случае, если клиент не поддерживает
address_message , сообщения молча отбрасываются, и в веб-перехватчик отправляется сообщение об ошибке. Ниже показано уведомление веб-перехватчика, которое будет отправлено обратно:{ "statuses": [ { "errors": [ { "code": 1026, "href": "/docs/whatsapp/api/errors", "title": "Receiver Incapable" } ], "id": "gBGGFlAwCWFvAgkyHMGKnRu4JeA", "message": { "recipient_id": "+91xxxxxxxxxx" }, "recipient_id": "91xxxxxxxxxx", "status": "failed", "timestamp": "1670394125", "type": "message" } ] }
Комментарии отсутствуют
Комментарии отсутствуют