Enviar ubicación con WhatsApp API (sendLocation)

Este escenario envía una ubicación en mapa con sendLocation durante la ventana de servicio al cliente de 24 horas.

Descripción del caso de uso

Este escenario envía una ubicación en mapa con sendLocation durante la ventana de servicio al cliente de 24 horas. Coordenadas, nombre del lugar y dirección ayudan al comprador a navegar sin copiar texto.

Ejemplo de plantilla

Tu punto de retiro está listo. Toca el pin del mapa de abajo para navegar.

WhatsApp Business API for delivery update — share pickup location

Cuándo usarlo

Úsalo cuando un pedido pasa a listo para retiro y el comprador aún necesita el punto exacto de recogida mientras la sesión de WhatsApp sigue abierta. Encaja en ecommerce click-and-collect, donde escribir direcciones a mano provoca rutas equivocadas y consultas repetidas a soporte.

Menos rutas de retiro equivocadas

sendLocation entrega latitud, longitud, nombre del punto de retiro y dirección como pin en el mapa, así el comprador navega a las coordenadas exactas en lugar de copiar una dirección mal escrita del chat.

Menos mensajes de "¿dónde retiro?"

El envío se dispara cuando el estado del pedido cambia a listo para retiro durante una sesión abierta de 24 horas, así el pin llega en el mismo hilo donde el comprador ya preguntó por la entrega.

Mapas con un toque desde el chat

La tarjeta de ubicación compartida abre navegación en la app de mapas del comprador; el texto de sesión le indica tocar el pin del mapa abajo en lugar de buscar la dirección en otro lado.

Sin reescribir direcciones a mano

Tu backend carga coordenadas, nombre del lugar y dirección cuando se dispara el evento del pedido, así soporte no repite los datos de retiro en texto libre.

Flujo de trabajo

Estado registrado
Un cambio de estado del pedido indica que el paquete está listo para retiro.
status: "read"
Capturar evento
Tu backend carga coordenadas, nombre del lugar y dirección.
phone: "+…"
Construir y enviar
sendLocation entrega el pin al cliente en la sesión activa.
POST /send_location
Entregado
El cliente abre navegación en mapas desde la tarjeta de ubicación compartida.
entregado

Implementación técnica

Requisitos previos

Clave API de 1MSG · Cómo obtener la clave API
Cuenta de WhatsApp Business · Cómo conectar WABA
Ventana de sesión de 24 horas abierta · Cómo funciona la ventana de 24 horas
Opt-in del cliente · Cómo gestionar el consentimiento
Endpoint de webhook · Cómo configurar webhooks

Ejemplos de código

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===
API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)



# === Test data ===
TEST_PHONE="___"                 # client phone in international format

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"
URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendLocation"

read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "lat": "41.40338",
  "lng": "2.17403",
  "name": "Pickup point",
  "address": "Example street 1"
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
  *'"sent":true'*) ok=1 ;;
  *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
  echo "Message sent to client."
else
  echo "$BODY" >&2
  exit 1
fi

Respuesta y estado de entrega

HTTP 2xx y JSON "sent": true significan que 1MSG aceptó el mensaje para envío — no que ya llegó al teléfono del cliente. Guarda el campo id (tipo wamid.…) para correlacionar los callbacks de entrega.

200 OKRespuesta

{
  "sent": true,
  "message": "Sent to [email protected]",
  "description": "Message has been sent to the provider",
  "id": "wamid.HBgLMzgwNjM5..."
}

sent
Aceptado para envío — aún no en el teléfono del cliente
id
Guárdalo; los callbacks de entrega y hookInfo se basan en él

Estados de entrega y webhooks →

Errores frecuentes

Estado	Respuesta de la API	Causa	Solución
200	Message was not sent: provide chatId, phone, bsuid, or username	Ningún destinatario que el canal pudiera resolver.	Envía un solo destinatario: phone (código de país y número, solo dígitos), chatId (por ejemplo [email protected]) o bsuid.
401	token is required	La petición no incluye el token.	Agrega el token del canal como parámetro token en la URL: https://api.1msg.io/{channelId}/{method}?token=…
429	too many requests. please try later	El canal superó su límite de envío.	Encola los mensajes de tu lado y reintenta con backoff exponencial.