Location Template API

1. Overview

The location header lets a WhatsApp template render a pinned map location above the message body, used for pickup points, delivery destinations, store locators, and rideshare pickups. Two APIs are involved: template creation (registers the template with Meta via RML's template management API) and message send (dispatches the template with runtime coordinates via the unified messaging API). This document covers both, plus validation rules and test coverage for each.

2. Template Creation API

Endpoint: POST https://apis.rmlconnect.net/wba/template/create

2.1 Payload — Happy Path (UTILITY)

POST https://apis.rmlconnect.net/wba/template/create

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "template_name": "delivery_pickup_location1111",
  "language": ["en"],
  "template_category": "UTILITY",
  "components": {
    "header": {
      "type": "location"
    },
    "body": {
      "text": "Your order {{1}} is ready for pickup at the location shown above.",
      "example": ["ORD-12345"]
    }
  }
}

Note: The source material identifies this exact case as “Created But Rejected” against the expected 200 OK response. Template creation returned a success response, but the template was subsequently rejected, likely during Meta's review. Treat this as a known discrepancy pending clarification, rather than a confirmed pass.

2.2 Payload — Footer Variant

Location header supports an optional footer component alongside body:

{
  "template_name": "rideshare_pickup",
  "language": ["en"],
  "template_category": "UTILITY",
  "components": {
    "header": { "type": "location" },
    "body": {
      "text": "Your driver {{1}} is arriving at the pickup point shown above.",
      "example": ["Rahul"]
    },
    "footer": {
      "text": "Tap the pin for directions"
    }
  }
}

2.3 Field Reference

Field	Type	Required	Constraints
template_name	string	Yes	Unique template identifier
language	array	Yes	e.g. ["en"]
template_category	string	Yes	UTILITY or MARKETING supported for location header; AUTHENTICATION rejected (TC-4)
components.header.type	string	Yes	Must be "location"; no text or example field permitted (TC-5, TC-6)
components.body.text	string	Conditional	Required for UTILITY/MARKETING; template creation fails without it (TC-7)
components.body.example	array	Recommended	Sample values for {{n}} placeholders in body text
components.footer.text	string	No	Optional static footer line
message_send_ttl_seconds	integer	No	For UTILITY: 30–43200 inclusive (TC-8)

2.4 Test Cases — Template Creation

ID	Scenario	Expected
TC-1	Location header, UTILITY category, body + example	200 OK (flagged: created but rejected downstream)
TC-2	Location header, MARKETING category	200 OK
TC-3	Location header with footer, UTILITY category	200 OK
TC-4	Location header with AUTHENTICATION category	422 — location header not supported for AUTHENTICATION category templates
TC-5	Location header includes text field	422 — text field is not supported for location header type
TC-6	Location header includes example field	422 — example field is not supported for location header type
TC-7	Location header with no body component	422 — please provide body element in components
TC-8	message_send_ttl_seconds = 50000 (UTILITY)	422 — message_send_ttl_seconds should have value in range from 30 to 43200 for utility templates

3. Message Send API

Endpoint: POST https://apis.rmlconnect.net/wba-testing/v1/messages

3.1 Payload — Full Location Params

POST https://apis.rmlconnect.net/wba-testing/v1/messages

Authorization: <YOUR_TOKEN>
Content-Type: application/json

{
  "phone": "<MOBILE NUMBER>",
  "media": {
    "type": "media_template",
    "template_name": "delivery_pickup_location1111",
    "lang_code": "en",
    "body": [{ "text": "ORD-12345" }],
    "header": [
      {
        "location": {
          "latitude": 19.0760,
          "longitude": 72.8777,
          "name": "RML Connect Office",
          "address": "123 Business Park, BKC, Mumbai"
        }
      }
    ]
  }
}

3.2 Field Reference

Field	Type	Required	Constraints
phone	string	Yes	Recipient mobile number
media.type	string	Yes	Must be "media_template"
media.template_name	string	Yes	Must match a previously created, approved location template
media.lang_code	string	Yes	e.g. "en"
media.body	array	Yes	Runtime values for body {{n}} placeholders
header[].location.latitude	number	Yes	Numeric only (TC-10); range ‒90 to 90 inclusive (TC-7, TC-12, TC-14)
header[].location.longitude	number	Yes	Numeric only (TC-11); range −180 to 180 inclusive (TC-8, TC-13, TC-14)
header[].location.name	string	Yes	Required (TC-4)
header[].location.address	string	Yes	Required (TC-5)

3.3 Test Cases — Message Send

ID	Scenario	Expected
TC-1	Full valid location payload (Mumbai)	200 OK
TC-2	Full valid location payload (Delhi)	200 OK
TC-3	Negative coordinates, valid range (Sydney)	200 OK
TC-4	Missing name	400/422 — name is required in location header
TC-5	Missing address	400/422 — address is required in location header
TC-6	Missing latitude and longitude	400/422 — latitude and longitude are required in location header
TC-7	Latitude > 90 (95.0)	400/422 — latitude must be a number between -90 and 90
TC-8	Longitude > 180 (200.0)	400/422 — longitude must be a number between -180 and 180
TC-9	Empty location object	400/422 — location value cannot be empty object
TC-10	Latitude as string ("nineteen")	400/422 — expected numeric type (result not documented in source — see note below)
TC-11	Longitude as string ("seventy")	422 — longitude must be a number between -180 and 180
TC-12	Latitude < -90 (-95.0)	422 — latitude must be a number between -90 and 90
TC-13	Longitude < -180 (-200.0)	422 — longitude must be a number between -180 and 180
TC-14	Boundary values: lat 90.0, long 180.0	200 OK — boundary values accepted, inclusive

Note on TC-10: The source material identifies this as a NOT WORKING / should-fail case but does not specify the expected error message, unlike TC-11, which covers the equivalent longitude-as-string case. This is documented as an open gap rather than assuming that the error message matches the wording used in TC-11.