Skip to main content

WhatsApp Geolocation Request - Feature documentation

Ioana Nicolae
Updated

Overview

This guide explains how to configure the WhatsApp Geolocation Request feature in Urbantz. This feature allows the system to automatically request a recipient's precise location via WhatsApp when the task's delivery address cannot be geocoded accurately enough.

When Does This Feature Trigger?

Important: The geolocation request is not sent for every task. It is only triggered when the system detects that the task's delivery address is not geocoded with sufficient accuracy.

When this condition is met, the system automatically initiates a WhatsApp conversation with the recipient to collect their precise location.

WhatsApp Only, No Fallback

Unlike standard recipient notifications (see WhatsApp Feature Documentation), the geolocation request does not support SMS fallback. The system will attempt to reach the recipient exclusively via WhatsApp. If the recipient does not have WhatsApp on the phone number associated with the task, the request will simply not be delivered.

This limitation exists because the feature relies on WhatsApp's interactive location sharing capability, which is not available on SMS.

A 3-Step Conversation. Why?

Meta's WhatsApp API does not allow businesses to send interactive location requests directly to recipients without an active conversation. You cannot send a template message with a "Share your location" button out of the blue.

To work around this, the feature uses a 3-step conversation:

  1. Initiate the conversation by sending a template message with a "Continue" button
  2. Once the recipient clicks the button, a 24-hour conversation window opens, allowing us to send an interactive location request. When the recipient shares their location, the task address is updated with the received coordinates.
  3. Send a thank-you message to confirm that the location was received
Step System Action Recipient Action Result
1. Initiation Sends a template message explaining the situation, with a "Continue" button Taps "Continue" Opens 24h conversation window
2. Location Request Sends an interactive location request message Taps "Share Location", selects or adjusts the pin, confirms Location received, task address updated
3. Thank You Sends a confirmation/thank-you message — Conversation closed

Cost

Only Step 1 (the template message) is billed as a business-initiated conversation. Steps 2 and 3 are sent within the 24-hour window opened by the recipient's button click, making them free of charge.

Prerequisites

Before configuring geolocation requests, make sure:

  1. WhatsApp integration is already set up on the platform 
  2. You are familiar with creating message templates in Meta Business Suite

Step 1: Create Templates in Meta Business Suite

You need to create 3 message templates in your WhatsApp Business Account. Each template serves a specific step of the conversation.

Reminder: For multi-language support, always use the exact same template name for all language versions. Only the language setting and the content should differ. Urbantz automatically selects the correct language based on the recipient's preferred language.

Template 1: Conversation Initiation

This is the first message the recipient will receive. It introduces the context (the delivery) and invites them to interact by clicking a button.

Configuration in Meta Business Suite:

Setting Value
Category Utility
Name e.g., confirm_delivery_location_init
Language(s) One version per language you support
Body A short, friendly message explaining that you need help confirming the delivery address
Buttons Add a Quick Reply button labeled "Continue" (or localized equivalent)

Example body text:

Hello {{recipient}} !

We are preparing your delivery from {{sender}}.

To ensure everything goes smoothly, could you please confirm a few details with us?

Template 2: Location Request

This template provides the body text for the location request message. You only need to write the text asking the recipient to share their location. The "Share Location" button is added automatically by Urbantz when this message is sent. You do not need to define this button in the Meta template editor, and you do not need to configure it in Urbantz either. It is fully automatic when using the TASK_LOCATION_REQUEST_ASK trigger.

Configuration in Meta Business Suite:

Setting Value
Category Utility
Name e.g., confirm_delivery_location_ask
Language(s) One version per language you support
Body A message asking the recipient to share their delivery location
Buttons None (the "Share Location" button is added automatically later on by Urbantz)

Example body text:

Please share the location where you would like your delivery to arrive. Tap the button below to send your location.

Template 3: Confirmation / Thank You

This message is sent after the recipient shares their location. It confirms that the location has been received and the delivery address has been updated.

Configuration in Meta Business Suite:

Setting Value
Category Utility
Name e.g., confirm_delivery_location_thanks
Language(s) One version per language you support
Body A short confirmation and thank-you message
Buttons None

Example body text:

Thank you! We have updated your delivery address with the location you shared. Your package will be delivered to the right place.

Step 2: Configure Notifications in Urbantz

Once your templates are approved in Meta, you need to create 3 notification configurations in Urbantz, one for each step of the conversation.

  1. From your platform, go to Administration > Platform > Messaging
  2. Create the following 3 notifications:

Notification 1: Conversation Initiation

Setting Value
Name e.g., "Geo - Location Request Init"
Trigger "Ask consumer to start a conversation regarding the task delivery location"
Delivery Mode WhatsApp

In the Content tab:

Setting Value
Template Select your confirm_delivery_location_init template 
(or the name you chose previously)
Default Language Select your default language
Variable Mapping Map template variables to Urbantz fields (e.g., {{address}} → task address)

Notification 2: Location Request

Setting Value
Name e.g., "Geo - Location Request Ask"
Trigger "Ask consumer for the delivery location of the task"
Delivery Mode WhatsApp

In the Content tab:

Setting Value
Template Select your confirm_delivery_location_ask template
(or the name you chose previously)
Default Language Select your default language

Note: You do not need to configure the "Share Location" button. It is added automatically by Urbantz when this trigger is used.

Notification 3: Thank You

Setting Value
Name e.g., "Geo - Location Request Thanks"
Trigger "Notify consumer when the task location request is completed"
Delivery Mode WhatsApp

In the Content tab:

Setting Value
Template Select your confirm_delivery_location_thanks template
(or the name you chose previously)
Default Language Select your default language

Important: Do NOT Configure Fallback Notifications

Do NOT create SMS or email fallback notifications for these triggers.

Unlike standard WhatsApp notifications, where you can set up SMS fallback, the geolocation request is WhatsApp-exclusive.

If the recipient does not have WhatsApp:

  • The initial message will fail to deliver
  • No fallback will be attempted
  • The task address will remain as-is (manual intervention may be needed)

Monitoring

Task-level Monitoring

  1. Open the Tasks menu on your platform
  2. Select the relevant task
  3. Open the Notifications Tab to see the notification attempts for each step of the conversation (up to 3 entries)
  4. Open the History Tab to see the task's activity log, including the address/GPS update resulting from the recipient's location sharing

Platform-level Monitoring

Go to Administration > System Monitor and select the Notifications Tab. This view shows failed deliveries across the platform, which is useful for identifying recipients who could not be reached (e.g., because they don't have WhatsApp).

 

Recipient Experience

Step 1: Initial Message

The recipient receives a WhatsApp message explaining that their delivery address needs confirmation. The message includes a "Continue" button.

Step 2: Location Sharing

After tapping "Continue", the recipient receives a message asking them to share their location. A "Share Location" button appears automatically (added by Urbantz when sending the message, not configured in Meta or in the Urbantz notification settings).

When the recipient taps "Share Location", WhatsApp opens its built-in location picker:

  • The recipient can share their current location

  • or choose a different location on the map

    • On Android: the pin can be dragged freely to any location. Public venues appear as markers on the map

       

     

    • On iOS: the default view shows the current location. To adjust, the recipient must swipe down the bottom panel to reveal the map and drag the pin. This gesture is not visually indicated, which can be confusing

       

Once the recipient shares their location, the task's delivery address is immediately updated with the received coordinates.

Step 3: Thank You

After the task address has been updated, the recipient receives a thank-you message confirming that the location was received.

 

Reference: Notification Triggers

Trigger (UI label) Step Description
"Ask consumer to start a conversation regarding the task delivery location" 1 Template message with "Continue" button
"Ask consumer for the delivery location of the task" 2 Interactive location request message (with automatic "Share Location" button)
"Notify consumer when the task location request is completed" 3 Thank-you / confirmation message

FAQ

What happens if the recipient doesn't click "Continue"?

The conversation stays open but no further messages are sent. The recipient can click the button at any time. If they never respond, the task address remains unchanged.

Can the recipient share a location different from their current position?

Yes, on both Android and iOS. However, the experience is significantly better on Android where the pin can be freely dragged. On iOS, discovering how to adjust the location is not intuitive (requires swiping down a panel with no visual hint).

What if the recipient doesn't have WhatsApp?

The geolocation request will not be delivered. No fallback to SMS or email is attempted. The task address remains unchanged and may require manual correction.

Is the 24-hour window a concern?

Not in practice. The 24-hour window starts when the recipient clicks "Continue". Every subsequent interaction from the recipient (such as sharing their location) resets the window for another 24 hours. Since Urbantz responds immediately after each recipient action, the system is always within the active window. Even if the recipient takes some time between steps, each interaction extends the window.

Can I use variables in the template body?

Yes, for Template 1 (initiation) you can use named variables (e.g., {{address}} for the task address, {{reference}} for a reference number) and map them in Urbantz. Note that Urbantz requires named variables (not numbered ones like {{1}}). Templates 2 and 3 typically don't need dynamic variables but can include them if desired.

Comments

0 comments

Please sign in to leave a comment.