Pindrop Location Requests

The Pindrop module allows helpdesk operators to send a caller an SMS containing a secure one-time link. The caller opens the link on their phone, shares their location by dropping a pin on a map, and optionally provides their contact details and photos. The submitted information flows back into the call log automatically.

Overview

When a member of the public phones in about an injured or distressed animal, the exact location can be difficult to capture verbally. Pindrop solves this by putting a map directly in the caller's hands:

• Operator sends an SMS with a branded, secure link during or after the call
• Caller opens the link on their mobile device — no app download required
• Caller drops a pin on a Google Map showing where the animal was spotted
• Caller provides details including their name, email, phone number, and optional photos
• Data appears on the call log in real time with an embedded map view

The link is one-time-use and tied to a cryptographic access token. Once the caller submits, the link cannot be reused.

How It Works

1. Operator Logs the Call

From the Call Log module, the operator creates a new call log and enters at least the caller's phone number. After saving, the operator opens the call log detail view.

2. Send Location Request

On the call log detail page, the Location Request card appears at the bottom. The operator clicks Send Location Request SMS, which:

• Creates a secure pindrop session linked to the call log
• Sends an SMS to the caller's phone number via AWS SNS
• The SMS contains a branded link like https://yourorg.wildtrack360.com.au/pin/abc123?t=...

3. Caller Fills In the Form

The caller taps the link and sees a mobile-friendly, WildTrack360-branded form with:

Section	Description
Your Details	Name, email, and phone number fields
Location	An interactive Google Map where the caller drops a pin, or uses their device GPS via the "My Location" button. The address is reverse-geocoded automatically.
Photos	Upload up to 5 photos of the animal or location (JPEG, PNG, WebP, HEIC, max 10MB each)
Additional Notes	Free-text field for any extra detail about the animal's condition or behaviour

The caller taps Submit Location & Details when done. They see a thank-you confirmation and can close the page.

4. Data Flows Back to the Call Log

Once submitted, the call log detail page displays:

• The caller's name, email, and phone (if provided)
• The pinned location displayed on an embedded Google Map
• The reverse-geocoded address
• Any notes or photos the caller attached
• A timestamp of when the submission was received

The operator can then use this information to dispatch a carer to the exact location.

Polling for Updates

While the pindrop session is pending, the call log detail page polls every 5 seconds for updates. Once the caller submits, the data appears automatically without the operator needing to refresh.

Security

Aspect	Detail
Access token	Each pindrop link contains a 32-character cryptographic token generated with nanoid. The token is verified using timing-safe comparison to prevent timing attacks.
One-time use	Once a session is submitted, the link returns a "Already Submitted" message. The form cannot be reused.
Public route	The /pin/... pages and /api/pin/... endpoints are intentionally excluded from Clerk authentication so the caller (who is not a system user) can access them.
Input validation	All submitted strings are length-capped. Photo URLs are validated against the expected S3 key prefix for the session to prevent injection. File extensions are sanitised to alphanumeric characters only.
Org scoping	Pindrop sessions are scoped to the operator's organisation. The SMS link URL is constructed from the org's subdomain stored in Clerk metadata.

Requirements

• The caller must have an SMS-capable phone
• The organisation must have an SMS plan enabled (see SMS Billing)
• The organisation must have org_url configured in Clerk public metadata for subdomain URL construction
• Google Maps API key (NEXT_PUBLIC_GOOGLE_MAPS_KEY) must be configured for the map to appear (falls back to manual coordinate entry if not set)

Integration with Other Modules

Module	Integration
Call Logs	Pindrop sessions are linked to call logs via a foreign key. The pindrop panel appears on the call log detail page.
SMS Billing	Every pindrop SMS is gated by the org's SMS subscription tier and counts toward monthly usage limits.
Audit Logging	Pindrop session creation is recorded in the audit log with the linked call log ID.