Send Location Message

Send a location pin to a WhatsApp recipient. You can attach a place name and address so the recipient sees more than just coordinates.

Endpoint

POST /whatsapp/send-location/:instance

• :instance: The name of your WhatsApp instance (e.g., my-bot).

Request Body

Parameter	Type	Required	Description
recipient	string	Yes	The recipient's WhatsApp number with country code (e.g., 254123456789) or the full sender address from a webhook (e.g., 123456789012345@lid or [email protected]). Send @lid addresses exactly as received; do not format them or remove the suffix.
latitude	number	Yes	The latitude of the location. Must be between -90 and 90.
longitude	number	Yes	The longitude of the location. Must be between -180 and 180.
name	string	No	A place name shown above the pin (max 100 characters).
address	string	No	An address shown with the pin (max 255 characters).

Example Payload

{
  "recipient": "254123456789",
  "latitude": -1.2921,
  "longitude": 36.8219,
  "name": "ChatBreez HQ",
  "address": "Westlands, Nairobi, Kenya"
}

Examples

cURL

curl -X POST https://api.chatbreez.com/whatsapp/send-location/{instance} \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "254123456789",
    "latitude": -1.2921,
    "longitude": 36.8219,
    "name": "ChatBreez HQ",
    "address": "Westlands, Nairobi, Kenya"
  }'

JavaScript

const axios = require('axios');

const sendLocation = async () => {
  try {
    const response = await axios.post('https://api.chatbreez.com/whatsapp/send-location/{instance}', {
      recipient: '254123456789',
      latitude: -1.2921,
      longitude: 36.8219,
      name: 'ChatBreez HQ',
      address: 'Westlands, Nairobi, Kenya'
    }, {
      headers: {
        'X-API-Key': 'your_api_key'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

sendLocation();

Python

import requests

url = "https://api.chatbreez.com/whatsapp/send-location/{instance}"

payload = {
    "recipient": "254123456789",
    "latitude": -1.2921,
    "longitude": 36.8219,
    "name": "ChatBreez HQ",
    "address": "Westlands, Nairobi, Kenya"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.chatbreez.com/whatsapp/send-location/{instance}"

	payload := map[string]interface{}{
		"recipient": "254123456789",
		"latitude":  -1.2921,
		"longitude": 36.8219,
		"name":      "ChatBreez HQ",
		"address":   "Westlands, Nairobi, Kenya",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", "your_api_key")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.chatbreez.com/whatsapp/send-location/{instance}";
        String json = """
            {
              "recipient": "254123456789",
              "latitude": -1.2921,
              "longitude": 36.8219,
              "name": "ChatBreez HQ",
              "address": "Westlands, Nairobi, Kenya"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("X-API-Key", "your_api_key")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php

$url = 'https://api.chatbreez.com/whatsapp/send-location/{instance}';

$payload = json_encode([
    'recipient' => '254123456789',
    'latitude' => -1.2921,
    'longitude' => 36.8219,
    'name' => 'ChatBreez HQ',
    'address' => 'Westlands, Nairobi, Kenya',
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key',
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Response

{
  "message": "Location message queued for delivery.",
  "messageId": "3EB0C767D097B7C7C030"
}

Keep the messageId if you need to reference the message later when investigating a delivery.

Common Errors

Errors are returned as JSON in this shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "latitude: Latitude must be between -90 and 90",
    "correlationId": "abc123-def456-ghi789"
  }
}

Status	Code	Meaning
400	VALIDATION_ERROR	The request body is invalid, the coordinates are out of range, or the recipient is not registered on WhatsApp.
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	Your account is deactivated. Contact support to reactivate it.
404	NOT_FOUND	The instance does not exist.
409	CONFLICT	The instance is not connected to WhatsApp. Reconnect it and try again.
502	UPSTREAM_ERROR	WhatsApp did not acknowledge the message. Try again shortly.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred on our side. Try again shortly.

Next Steps

• Send Text Messages
• Send Media Messages — images, videos, documents, and audio files
• Send Contact Messages — share contact cards
• Send Poll Messages — create polls with up to ten options
• Check Instance Status