Developer reference

BotLinkd REST API Documentation

Integrate supported WhatsApp messaging workflows with BotLinkd using server-side REST API requests. This reference documents authentication, text and media request fields, implementation examples, security controls and webhook next steps.

Start with authentication Read webhook guide

BotLinkd is an independent business messaging platform built on the official WhatsApp Business Platform Cloud API. Endpoint availability and account permissions depend on your active BotLinkd configuration.

Request overview

Base domain: https://botlinkd.com
Request method: POST
Request format: multipart/form-data
Response format: JSON

Server-side integration recommended

Quick start

Authenticate every request with protected account credentials

Obtain the applicable App Key and Auth Key from your authenticated BotLinkd account. Send them only from a trusted backend environment. Never publish live credentials in source code, browser JavaScript, mobile application bundles, logs or public repositories.

Use account-specific keys

The examples use placeholders only. Sign in to view credentials assigned to your BotLinkd platform or API configuration.

Keep secrets on the server

Store keys in environment variables or a managed secret store. Restrict access, rotate credentials when exposure is suspected and redact them from application logs.

Credential placeholders

Copy safe example values

Never paste live keys into public tools

App Key YOUR_APP_KEY

Auth Key YOUR_AUTH_KEY

Parameter names are endpoint-specific

The text endpoint uses appkey and authkey. The media endpoint shown below uses app_key and auth_key. These names are not interchangeable; send the exact fields documented for each request.

Endpoint 01

Send a text message

Send a supported text message through the connected BotLinkd WhatsApp platform. The request examples use multipart/form-data and must be executed from a protected server environment.

POST /api/whatsapp/message

Request parameters

Parameter	Type	Required	Purpose
`appkey`	String	Yes	App Key assigned to the applicable BotLinkd Cloud API configuration.
`authkey`	String	Yes	Auth Key used with the App Key to authenticate the request.
`to`	String	Yes	Recipient phone number in the format accepted by the connected account.
`message`	String	As applicable	Text content sent when the request is eligible under the active conversation and WhatsApp rules.

Before sending

Use an active BotLinkd account and connected WhatsApp platform.
Confirm that the recipient and message are eligible under current WhatsApp rules.
Use an approved template when required for business-initiated messaging.
Do not treat an accepted request as proof of final delivery or reading.

curl --location --request POST 'https://botlinkd.com/api/whatsapp/message' \
  --form 'appkey="YOUR_APP_KEY"' \
  --form 'authkey="YOUR_AUTH_KEY"' \
  --form 'to="447123456789"' \
  --form 'message="Hello from BotLinkd"'

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://botlinkd.com/api/whatsapp/message',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'appkey' => getenv('BOTLINKD_APP_KEY'),
        'authkey' => getenv('BOTLINKD_AUTH_KEY'),
        'to' => '447123456789',
        'message' => 'Hello from BotLinkd',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($curl);

if ($response === false) {
    throw new RuntimeException(curl_error($curl));
}

$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);

const form = new FormData();
form.append('appkey', process.env.BOTLINKD_APP_KEY);
form.append('authkey', process.env.BOTLINKD_AUTH_KEY);
form.append('to', '447123456789');
form.append('message', 'Hello from BotLinkd');

const response = await fetch(
  'https://botlinkd.com/api/whatsapp/message',
  {
    method: 'POST',
    body: form,
    signal: AbortSignal.timeout(30000)
  }
);

const data = await response.json();

if (!response.ok) {
  throw new Error(`BotLinkd API request failed: ${response.status}`);
}

import os
import requests

response = requests.post(
    'https://botlinkd.com/api/whatsapp/message',
    data={
        'appkey': os.environ['BOTLINKD_APP_KEY'],
        'authkey': os.environ['BOTLINKD_AUTH_KEY'],
        'to': '447123456789',
        'message': 'Hello from BotLinkd',
    },
    timeout=30,
)

response.raise_for_status()
data = response.json()

Response handling: Parse the JSON response, check the HTTP status and store only non-sensitive operational details. The exact fields returned can depend on the endpoint, account and processing result.

Endpoint 02

Send an image, audio file or document by URL

Use the documented BotLinkd media endpoint to send a supported public media URL. The remote file must be reachable by the platform and compatible with the selected media type and active account configuration.

POST /api/whatsapp-web/send-message

Request parameters

Parameter	Type	Required	Purpose
`app_key`	String	Yes	App Key used by the documented media endpoint.
`auth_key`	String	Yes	Auth Key paired with the applicable App Key.
`to`	String	Yes	Recipient phone number in the accepted international format.
`type`	String	Yes	Documented values: `image`, `audio` or `document`.
`url`	URL	Yes	Public HTTPS URL for the supported media file.

Media URL checklist

Use HTTPS and a URL that does not require an interactive browser login.
Return the correct file content type and avoid redirect chains where possible.
Do not expose private customer files through permanent public URLs.
Confirm current file-type and size support before production sending.

curl --location --request POST 'https://botlinkd.com/api/whatsapp-web/send-message' \
  --form 'app_key="YOUR_APP_KEY"' \
  --form 'auth_key="YOUR_AUTH_KEY"' \
  --form 'to="447123456789"' \
  --form 'type="image"' \
  --form 'url="https://example.com/media/product-image.jpg"'

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://botlinkd.com/api/whatsapp-web/send-message',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'app_key' => getenv('BOTLINKD_APP_KEY'),
        'auth_key' => getenv('BOTLINKD_AUTH_KEY'),
        'to' => '447123456789',
        'type' => 'document',
        'url' => 'https://example.com/media/invoice.pdf',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($curl);

if ($response === false) {
    throw new RuntimeException(curl_error($curl));
}

$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);

const form = new FormData();
form.append('app_key', process.env.BOTLINKD_APP_KEY);
form.append('auth_key', process.env.BOTLINKD_AUTH_KEY);
form.append('to', '447123456789');
form.append('type', 'image');
form.append('url', 'https://example.com/media/product-image.jpg');

const response = await fetch(
  'https://botlinkd.com/api/whatsapp-web/send-message',
  {
    method: 'POST',
    body: form,
    signal: AbortSignal.timeout(30000)
  }
);

const data = await response.json();

if (!response.ok) {
  throw new Error(`BotLinkd API request failed: ${response.status}`);
}

import os
import requests

response = requests.post(
    'https://botlinkd.com/api/whatsapp-web/send-message',
    data={
        'app_key': os.environ['BOTLINKD_APP_KEY'],
        'auth_key': os.environ['BOTLINKD_AUTH_KEY'],
        'to': '447123456789',
        'type': 'document',
        'url': 'https://example.com/media/invoice.pdf',
    },
    timeout=30,
)

response.raise_for_status()
data = response.json()

Privacy note: Use short-lived or access-controlled media URLs where your implementation supports them. Do not publish confidential customer documents at permanent, guessable locations.

Production guidance

Build a secure and reliable messaging integration

Production systems should protect credentials, prevent duplicate processing, handle temporary failures and retain enough operational context to diagnose problems without logging private message content unnecessarily.

Secret management

Use environment variables or a managed secret store. Restrict access and rotate exposed credentials.

Timeouts and retries

Set bounded timeouts. Retry only transient failures with backoff and avoid uncontrolled retry loops.

Duplicate protection

Use your own idempotency controls so application retries do not create unintended duplicate messages.

Response validation

Check the HTTP status, safely parse JSON and handle missing or unexpected fields without crashing the workflow.

Webhook processing

Acknowledge events quickly, deduplicate repeated deliveries and queue slower downstream operations.

Observability

Track request IDs, timestamps, endpoint, status and safe error categories without recording credentials.

Webhook implementation guide Receive supported replies and message-status events.

Available integrations Review supported e-commerce, billing and business-system connections.

Official WhatsApp Cloud API Understand onboarding, messaging, templates, automation and teams.

Developer FAQ

Common BotLinkd API integration questions

Direct answers for authentication, request format, phone numbers, webhooks and delivery expectations.

Where do I find my BotLinkd API credentials?

Sign in to your BotLinkd account and open the applicable API or platform settings area. Use the App Key and Auth Key assigned to the connected account. Keep both credentials private and never expose them in browser-side JavaScript, public repositories or screenshots.

What request format do the documented endpoints use?

The request examples on this page use HTTP POST with multipart/form-data fields. Parameter names differ between the documented text and media endpoints, so copy the field names exactly as shown for the endpoint you are calling.

How should recipient phone numbers be formatted?

Use the international phone number format accepted by your BotLinkd account and connected WhatsApp configuration. The examples use country code followed by the subscriber number without spaces. Validate the final format in your account before production sending.

Can I call the BotLinkd API directly from a website browser?

Do not expose App Keys or Auth Keys in frontend JavaScript. Send requests from a protected server, backend application, worker or trusted integration layer where credentials can be stored securely.

How do I receive incoming messages and delivery events?

Use BotLinkd webhooks for supported inbound messages, replies and message-status events. Your webhook handler should authenticate requests where supported, respond quickly, process events idempotently and move slower work to a queue.

Does an accepted API request guarantee delivery or reading?

No. An accepted request means the platform accepted it for processing. Final delivery, reading or failure depends on WhatsApp, the recipient, message eligibility, account configuration, policy requirements and network conditions. Use webhook status events where available.

Build with BotLinkd

Connect business messaging to your application

Create a BotLinkd account to configure the applicable platform, obtain protected credentials and connect supported WhatsApp messaging workflows.

Create an account Contact BotLinkd