Location Messages

Convers8 allows you to send location messages to your WhatsApp contacts. This guide covers how to use the location messaging API.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://waba-v1.convers8.africa

Sending Location Messages

Endpoint

POST /whatsapp/message/location

Request Body

The request body should be a JSON object with the following properties:

Property	Type	Description
to	string	The recipient's phone number in international format (e.g., +1234567890)
contact	string	The recipient's name
content	object	An object containing the location details
content.latitude	string	The latitude coordinate of the location
content.longitude	string	The longitude coordinate of the location
content.name	string	The name of the location
content.address	string	The address of the location

Example Request

{
  "to": "+1234567890",
  "contact": "Customer Name",
  "content": {
    "latitude": "19.082502",
    "longitude": "72.7163737",
    "name": "Mumbai",
    "address": "Mumbai, Maharashtra, India"
  }
}

cURL Example

curl --request POST \
     --url https://waba-v1.convers8.africa/whatsapp/message/location \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+1234567890",
       "contact": "Customer Name",
       "content": {
         "latitude": "19.082502",
         "longitude": "72.7163737",
         "name": "Mumbai",
         "address": "Mumbai, Maharashtra, India"
       }
     }'

Response

A successful response will have a 200 status code and a JSON body with the following structure:

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "messageId": "wamid.abcdefghijklmnopqrstuvwxyz"
  }
}

Error Handling

In case of an error, the API will return a JSON response with an error message:

{
  "success": false,
  "message": "Error message",
  "error": {
    "code": "error_code",
    "details": "Error details"
  }
}

Common error codes include:

• invalid_parameter: One or more parameters in the request are invalid
• unauthorized: Invalid or missing API key
• rate_limit_exceeded: Too many requests in a short period
• recipient_not_found: The recipient's phone number is not registered on WhatsApp

Best Practices

1. Coordinate Accuracy: Ensure that latitude and longitude coordinates are accurate and in the correct format.
2. Location Details: Provide clear and descriptive location names and addresses to help recipients identify the location.
3. Rate Limiting: Be mindful of WhatsApp's rate limits to avoid being blocked.
4. Error Handling: Implement proper error handling in your application to manage API errors gracefully.
5. Phone Number Format: Always use the international format for phone numbers (e.g., +1234567890).