Перейти к основному содержимому

Адресные сообщения | Документация для разработчиков

Адресные сообщения

Обновлено: 7 ноября 2025 г
Эта функция доступна только для компаний, расположенных в Индии, и их клиентов в Индии.
Сообщения с адресом позволяют пользователям проще делиться адресом доставки с компанией через WhatsApp.
Адресные сообщения — это интерактивные сообщения, состоящие из 4 основных частей: заголовка , тела , нижнего колонтитула и действия . Внутри компонента действия бизнес-логика задаёт имя «address_message» и соответствующие параметры.
В таблице ниже перечислены поля, поддерживаемые адресным сообщением.
Название поля Наклейка на дисплей Тип ввода Поддерживаемые страны Ограничения
имя
Имя
текст
Индия
Никто
номер телефона
Номер телефона
тел
Индия
Только действительные номера телефонов
in_pin_code
Пин-код
текст
Индия
Максимальная длина: 6
номер дома
Номер квартиры/дома
текст
Индия
Никто
номер_этажа
Номер этажа
текст
Индия
Никто
номер_башни
Номер башни
текст
Индия
Никто
название_здания
Название здания/квартиры
текст
Индия
Никто
адрес
Адрес
текст
Индия
Никто
достопримечательность_район
Достопримечательность/Район
текст
Индия
Никто
город
Город
текст
Индия
Никто
состояние
Состояние
текст
Индия
Никто

Образец API call

This is a sample API call for the address message. The страна attribute is a mandatory field in the action parameters. If it is not included, there will be a validation error.
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), после чего открывается экран ввода адреса. Пользователь заполняет свой адрес и отправляет формуПосле отправки пользователем формы с адресом партнер получает уведомление через веб-хук, содержащее подробную информацию об адресе, предоставленном пользователем

    

    Пример сообщения с адресом в Индии 
    

    

    ИзображениеИзображениеИзображениеИзображение
    

    На следующей диаграмме показана типичная последовательность обработки адресного сообщения.
    

    

    Изображение
    

    

    

    Additional
Action Parameters
    The business can pass additional attributes such as ценности, validation_errors, или сохраненные_адреса as part of the interactive action parameters. You can find information on each of their usage below.
    
Параметр действия

Использование

    ценности
    Компании автоматически заполняют эти поля адреса (например, поле «Город» заполняется значением «Индия»)
    сохраненные_адреса
    Для бизнеса это означает возможность передачи сохраненных адресов, ранее связанных с пользователем.
    Пользователям предоставляется возможность выбрать сохраненный адрес вместо того, чтобы вводить его вручную
    validation_errors
    Компании могут выдавать ошибки в полях адреса, и WhatsApp не позволит пользователю отправить адрес до тех пор, пока проблема (проблемы) не будут решены.
    Отправить адресное сообщение пользователю
    Make a ПОЧТА призыв к /<PHONE_NUMBER_ID/messages using the WhatsApp API to send an end-to-end encrypted address message to the user:
    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" } ] }
    Неудачный ответ содержит сообщение об ошибке. Дополнительную информацию  разделах «Коды ошибок» и «Коды состояния» 
    

    

    

    Отправлять
an Address Message with Validation Errors
    В случае ошибки проверки на сервере компании пользователю следует повторно отправить адресное сообщение. Компания должна отправить обратно набор значений, ранее введенных пользователем, вместе с соответствующими ошибками проверки для каждого недопустимого поля, как показано в примерах полезной нагрузки ниже.
    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": "Нам не удалось определить этот почтовый индекс." } } } } }'
    Получайте уведомления о предоставлении адресных данных
    Businesses will receive address submission notifications through вебхуки, such as the one shown below.
    { "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" } } ] }
    Уведомление веб-перехватчика имеет следующие значения.
    
Название поля

Тип

Описание

    интерактивный
    Объект
    Содержит ответ от клиента
    тип
    Нить
    Would be nfm_reply indicating it is a Native Flow Response (NFM) from the client
    nfm_reply
    Объект
    Содержит данные, полученные от клиента
    response_json
    Нить
    Значения полей адреса, заполненных пользователем в формате JSON, которые всегда присутствуют
    тело (Optional)
    Нить
    Основной текст от клиента, то, что видит пользователь
    имя (Optional)
    Нить
    Would be address_message indicating the type of NFM action response from the client
    Ниже показан ответ в виде адресного сообщения, представленный в формате 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" } ] }
    
    
            
    
    
    

            
    
        
    
    
    

    
    

    
    
    
        
    
             Вернуться наверх