When to Use
- Delivery driver location sharing: A last-mile logistics workflow sends the driver's current GPS location to the customer when the delivery is 10 minutes away, enabling the customer to meet the driver outside.
- Branch or store directions: A customer service workflow sends the nearest branch location pin in response to a "Where are you located?" query, with the branch name and address in the label fields.
- Event venue navigation: An event management workflow sends the event venue pin to all registered attendees 2 hours before start time, with the venue name and parking entrance address.
- Field service dispatch: A field service workflow sends the technician's current location to the customer when the technician departs for the job, giving an accurate arrival estimate.
- Property visit directions: A real estate workflow sends the exact property pin to a prospective buyer confirmed for a viewing appointment, ensuring they arrive at the correct entrance.
Configuration
Connection
| Field | Required | Description |
|---|
accessToken | Required | Permanent System User access token. Store in BizFirst Credentials Manager. |
phoneNumberId | Required | Numeric string ID of the sending WhatsApp Business phone number. |
apiVersion | Optional | Meta Graph API version. Defaults to v18.0. |
Operation
| Field | Required | Description |
|---|
to | Required | Recipient's phone number with country code, no + prefix (e.g. 14155552671). |
latitude | Required | Latitude as a decimal number (e.g. 37.4847). Range: -90 to 90. |
longitude | Required | Longitude as a decimal number (e.g. -122.1477). Range: -180 to 180. |
name | Optional | Location name displayed as the pin title (e.g. BizFirst HQ). Displayed in bold above the address. |
address | Optional | Formatted address displayed below the location name (e.g. 123 Main St, San Francisco, CA 94105). |
Coordinate precision: Use at least 4 decimal places of precision for accurate pin placement (e.g. 37.4847, not 37.48). Insufficient precision may place the pin in the wrong building or street.
Sample Configuration
{
"resource": "message",
"operation": "sendLocation",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"to": "{{ $input.customerPhone }}",
"latitude": "{{ $input.branchLatitude }}",
"longitude": "{{ $input.branchLongitude }}",
"name": "{{ $input.branchName }}",
"address": "{{ $input.branchAddress }}"
}
Validation Errors
| Error | Cause |
|---|
accessToken is required | The accessToken field is empty. |
phoneNumberId is required | The phoneNumberId field is empty. |
to is required | The to field is empty. |
131026 (Meta) | Recipient is not a valid WhatsApp account. |
131047 (Meta) | 24-hour customer service window has expired. |
| Invalid coordinates (Meta) | Latitude or longitude is outside valid range. Validate in a Function node before calling this operation. |
Output
Success Port
| Field | Type | Description |
|---|
messageId | string | Unique WhatsApp message ID (wamid). |
phoneNumberId | string | The sending phone number ID. |
to | string | The recipient phone number. |
status | string | "sent" on success. |
errorCode | string | Empty on success. |
errorMessage | string | Empty on success. |
rawResponse | string | Full raw JSON from the Meta API. |
Error Port
| Field | Type | Description |
|---|
status | string | "failed" or "error". |
errorCode | string | Meta error code or BizFirst validation code. |
errorMessage | string | Human-readable error description. |
rawResponse | string | Raw API error response. |
Sample Output
{
"messageId": "wamid.HBgLMTQxNTU1NTI2NzEVAgARGBIzQzM4NjhGQTExMjQ3RBMAA",
"phoneNumberId": "123456789012345",
"to": "14155552671",
"status": "sent",
"errorCode": null,
"errorMessage": null,
"rawResponse": "{\"messaging_product\":\"whatsapp\",\"contacts\":[{\"input\":\"14155552671\",\"wa_id\":\"14155552671\"}],\"messages\":[{\"id\":\"wamid.HBgLMTQxNTU1NTI2NzEVAgARGBIzQzM4NjhGQTExMjQ3RBMAA\"}]}"
}
Expression Reference
| Value | Expression | Notes |
|---|
| Message ID | {{ $output.sendLoc.messageId }} | Retain for audit trail or deletion. |
| Recipient | {{ $output.sendLoc.to }} | For delivery confirmation logging. |
| Status | {{ $output.sendLoc.status }} | Branch on outcome in IfCondition. |
| Error detail | {{ $output.sendLoc.errorMessage }} | Log on the error port for diagnostics. |
Node Policies & GuardRails
| Policy Area | Recommendation |
|---|
| Credential storage | Store the access token in BizFirst Credentials Manager. Never inline. |
| Coordinate validation | Validate that latitude is within -90 to 90 and longitude is within -180 to 180 in a Function node before calling this operation. Invalid values cause a Meta API error that is not easily actionable without pre-validation. |
| Name and address fields | Always provide the name and address fields for business-sent locations. A pin with no label is confusing for recipients and looks unprofessional. |
| Live location privacy | Do not send real-time GPS locations of employees or delivery drivers without their explicit consent and a disclosed privacy policy. Static business locations do not require special consent. |
| 24-hour window | Location messages are free-form. Outside the customer service window, use a template with a location body (text with coordinates) as an alternative. |
| Error port | Connect the error port. Invalid recipient numbers and expired conversation windows are the most common failure modes for location messages. |
Examples
Branch Location on Customer Enquiry
{
"resource": "message",
"operation": "sendLocation",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"to": "{{ $input.customerPhone }}",
"latitude": "37.48472",
"longitude": "-122.14778",
"name": "BizFirst Palo Alto Branch",
"address": "123 University Ave, Palo Alto, CA 94301\nHours: Mon-Fri 9AM-5PM"
}
A customer asks "Where is your nearest branch?" via WhatsApp. The workflow uses the customer's postcode to select the nearest branch from a CRM lookup, then sends that branch's stored coordinates and address.
Delivery Driver Eta Location
{
"resource": "message",
"operation": "sendLocation",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"to": "{{ $input.customerPhone }}",
"latitude": "{{ $input.driverLat }}",
"longitude": "{{ $input.driverLon }}",
"name": "Your delivery driver",
"address": "Estimated arrival: {{ $input.etaMinutes }} minutes"
}
A delivery tracking webhook triggers this workflow when the driver enters a 2km geofence around the delivery address. The driver's GPS coordinates are passed as input, and the address field is repurposed to show the ETA.
Event Venue for Registered Attendees
{
"resource": "message",
"operation": "sendLocation",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"to": "{{ $input.attendeePhone }}",
"latitude": "{{ $config.eventLatitude }}",
"longitude": "{{ $config.eventLongitude }}",
"name": "{{ $config.eventName }}",
"address": "{{ $config.venueName }}, {{ $config.venueAddress }}\nEntrance: Main lobby on {{ $config.entranceStreet }}"
}
A Loop node iterates over registered attendees 2 hours before event start. Each attendee receives the venue pin with the specific entrance instructions in the address field. The address field is flexible text — use it for any contextual information the recipient needs.
