The WhatsRay API follows RESTful architecture standards, offering clear and consistent resource-based endpoints. All requests and responses are transmitted in JSON format, leveraging standard HTTP verbs, status codes, and authentication protocols to enable secure, efficient, and scalable integrations.

API Base URL

Please note that WhatsRay does not provide a sandbox or test environment. All API requests are processed in the live environment, so ensure that all request data and parameters are accurate before making any calls.

https://wpp.raybeamdigital.com/external-api

All requests to the WhatsRay API require authentication. Each API request must include a valid client-id and client-secret to the request header, which can be obtained from your WhatsRay Dashboard under Developer Tools.

In addition to credentials, WhatsRay enforces IP-based security. You must register and enable your server’s public IP address in the IP Whitelist section of the dashboard. Requests originating from non-whitelisted IP addresses will be automatically rejected.

Both valid API credentials and an approved IP address are mandatory. Without completing these two steps, authentication will fail and API access will not be granted.

Your application sends requests to the WhatsRay External API. WhatsRay authenticates the request, selects your connected WhatsApp number, sends the request to Meta's WhatsApp Cloud API, and saves the resulting conversation and message in your WhatsRay inbox.

Your application
    → WhatsRay External API
    → Your connected WhatsApp Business number
    → Meta WhatsApp Cloud API
    → Recipient

Your application does not need direct access to the Meta access token stored by WhatsRay. Keep your WhatsRay client-id and client-secret on your server and never expose them in browser JavaScript, a mobile application, a public repository, or screenshots.

Complete all of the following before making your first request:

1. Activate a WhatsRay subscription that includes API access.
2. Connect and verify at least one WhatsApp Business number in WhatsRay.
3. Create or synchronize the required WhatsApp template and confirm that Meta has approved it.
4. Copy your client-id and client-secret from Developer Tools.
5. Add the public outbound IP address of the server running your application to API IP Address White List.
6. Call GET /external-api/whatsapp-account/list to obtain the sending account ID.
7. Call GET /external-api/inbox/template-list?whatsapp_account_id=ACCOUNT_ID&status=approved to obtain a usable template ID.

API requests use the live environment; there is currently no sandbox. Test with a controlled recipient and verified request values before using the integration in production.

The whitelist must contain the public outbound IP address of the server that calls this API. It is not the recipient's IP, the connected WhatsApp number, or a private network address such as 192.168.x.x, 10.x.x.x, or 172.16.x.x.

Application server public outbound IP: 203.0.113.50
IP saved in WhatsRay whitelist: 203.0.113.50

How to identify the correct IP

Make a test API request from the same server and network that will run the production integration. If the IP is not approved, the API error response displays the address detected by WhatsRay. Add that exact address in Dashboard → API IP Address White List, then retry.

When the API is reached through Cloudflare, WhatsRay accepts the forwarded client address only when the direct connection comes from Cloudflare's trusted network ranges. Forwarded IP headers sent directly by an untrusted caller are ignored, preventing them from impersonating a whitelisted address.

Changing or dynamic IP addresses

Whitelist entries are exact IP addresses. CIDR ranges and wildcard addresses are not supported. If your hosting provider rotates outbound IPs, requests will stop working when the address changes. Use a static public IP, static NAT gateway, or fixed-egress proxy. You may add multiple fixed server IPs when your integration legitimately sends requests from more than one server.

Do not solve a changing-IP problem by sharing API credentials or adding unrelated addresses. Rotate the client secret immediately if it is exposed.

1. Get the WhatsApp account ID

Call GET /external-api/whatsapp-account/list. Select an account whose connection_status is connected, and use its id as whatsapp_account_id.

curl --request GET 'https://wpp.raybeamdigital.com/external-api/whatsapp-account/list' \
  --header 'client-id: YOUR-CLIENT-ID' \
  --header 'client-secret: YOUR-CLIENT-SECRET'

2. Get the template ID

Call the template-list endpoint using your credentials. The id returned for a template is the WhatsRay template ID required by send-template-message. Do not substitute the Meta template name or another Meta identifier.

curl --request GET 'https://wpp.raybeamdigital.com/external-api/inbox/template-list?whatsapp_account_id=12&status=approved' \
  --header 'client-id: YOUR-CLIENT-ID' \
  --header 'client-secret: YOUR-CLIENT-SECRET'

3. Send the approved template

Supply the recipient, the returned template ID, and every required header/body variable. When more than one WhatsApp number is connected, always provide whatsapp_account_id so the sending number is explicit.

curl --request POST 'https://wpp.raybeamdigital.com/external-api/inbox/send-template-message' \
  --header 'client-id: YOUR-CLIENT-ID' \
  --header 'client-secret: YOUR-CLIENT-SECRET' \
  --form 'whatsapp_account_id=12' \
  --form 'mobile_code=94' \
  --form 'mobile=771234567' \
  --form 'template_id=45' \
  --form 'body_variables[name]=John' \
  --form 'body_variables[date]=2026-08-11'

The API finds or creates the contact and conversation, verifies that the template is approved for the selected WhatsApp account, sends it through Meta, records the outgoing message, and returns the conversation and message data.

All responses from the WhatsRay API are returned in JSON format. Each response follows a consistent structure and includes a status indicator, message, and relevant data payload when applicable. Standard HTTP status codes are used to represent the outcome of each request.

Example Response

{
  "status": "success",
  "data": {
    "whatsapp_accounts": [
      {
        "id": 12,
        "business_name": "Example Business",
        "phone_number": "+94 77 123 4567",
        "phone_number_id": "123456789012345",
        "is_default": true,
        "connection_status": "connected",
        "verification_status": "verified"
      }
    ]
  }
}

id is the WhatsRay WhatsApp account ID used as whatsapp_account_id.

phone_number_id is Meta's phone-number ID. It can also select a sending account where an endpoint supports it.

is_default identifies the account used when no sending-account selector is supplied.

No Meta access tokens or private account credentials are returned by this endpoint.

Query Parameters

URL Parameters

Request Body

URL Parameters

Request Body

Notes

At least one message type must be provided.

Interactive messages require an active plan.

Blocked contacts cannot send or receive messages.

Request Body

Notes

Only approved WhatsApp templates can be sent.

If your template has variables, every required header/body variable must be provided. Named placeholders such as {{date}} must be sent using the same name as the array key.

Template messages are typically used for business-initiated conversations.

Blocked contacts cannot receive template messages.

WhatsApp account must be connected before sending messages.

When multiple WhatsApp numbers are connected, provide whatsapp_account_id to explicitly select the sending number.

Query Parameters

For sending, use status=approved and pass the same whatsapp_account_id to the send-template request.