Sending location messages

Send a location

Send finite latitude and longitude values for the point the recipient should see. name and address are optional display context and do not change the coordinates.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const accepted = await yanola.messages.sendLocation({
  from: "+15557654321",
  to: "+15551234567",
  latitude: 25.204849,
  longitude: 55.270783,
  name: "Downtown pickup",
  address: "Dubai, United Arab Emirates",
})

console.log(accepted.id)

Request fields

Customer Service Window

In Live Mode, a text, media, location, or contact-card send is allowed only when Yanola has evidence that the recipient sent an inbound message to the same Sender during the previous 24 hours. Activity with another Sender does not open this window.

When no active window is known, Yanola returns 422 service_window_required before queueing the message or making a provider call. The error is not retryable: repeating the same non-template request cannot create a window.

1. Send an approved template that is appropriate for the business intent.
2. After the customer replies, use non-template messages during the new 24-hour window.
3. Do not catch the error and silently substitute unrelated template content.

{
  "error": {
    "type": "business_state_error",
    "code": "service_window_required",
    "message": "A text, media, location, or contact-card message requires an active Customer Service Window. Send an approved template instead.",
    "requestId": "req_...",
    "retryable": false,
    "details": {
      "from": "+15557654321",
      "to": "+15551234567"
    }
  }
}

Location data safety

Treat precise coordinates as potentially sensitive customer data. Send only locations the recipient needs and apply appropriate retention and access controls in your own application.

Yanola validates ranges but cannot determine whether coordinates point to the intended real-world place. Confirm coordinate order and source before sending.

Asynchronous acceptance

Every send method returns a queued response after Yanola accepts the operation. A 202 response is not proof of provider delivery.

Live message IDs start with msg_; Test Mode IDs start with msg_test_. Keep the returned ID and request ID so you can correlate message retrieval, webhook events, logs, failures, and support requests.

{
  "id": "msg_...",
  "environment": "live",
  "status": "queued",
  "from": "+15557654321",
  "to": "+15551234567",
  "requestId": "req_...",
  "createdAt": "2026-07-29T10:00:00.000Z"
}

Safe retries and idempotency

The SDK generates a unique Idempotency-Key for every send call and preserves it across automatic transport retries. If your job system owns retry identity, pass a stable idempotencyKey as the second argument.

The same key and request body return the original accepted response. Reusing the key with a different body returns 409 idempotency_key_reused. Yanola retains send idempotency records for at least 24 hours.

const accepted = await yanola.messages.sendLocation(
  {
    from: "+15557654321",
    to: "+15551234567",
    latitude: 25.204849,
    longitude: 55.270783,
    name: "Downtown pickup",
  },
  {
    idempotencyKey: "order-123-pickup-location",
  }
)