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:
Initiate the conversation by sending a template message with a "Continue" button
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.
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:
WhatsApp integration is already set up on the platform
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.
From your platform, go to Administration > Platform > Messaging
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)
"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
Open the Tasks menu on your platform
Select the relevant task
Open the Notifications Tab to see the notification attempts for each step of the conversation (up to 3 entries)
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"
"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.