API Documentations

Authentication

Introduction

This API is authenticated by using Bearer Token authentication for each endpoint request. The HTTP client must send this token in the Authorization header when making requests to protected resources:

Authorization: Bearer [API_TOKEN]

For example, your authentication header will look something like this:

Authorization: Bearer 8d162cc813ce4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Obtaining API token

API token is set per device. You can get your token by the steps:

Log into your account.
Navigate to the device page by clicking on "Devices" on the sidebar.
In the actions column, click "View" button to view device.
The token is shown under the "Token" column.

Rate Limits

There are 2 types of rate limits:

Per minute 60 calls.
Per day Based on the user's subscribed package.

Monitoring Rate Limits

You can monitor your current rate limit usage by checking the following headers in the API response:

X-RateLimit-Limit : The maximum number of requests allowed per time window
X-RateLimit-Remaining : The number of requests remaining in the current time window

When a rate limit is exceeded, the API will return a 429 Too Many Requests response with a message indicating which limit was exceeded.

Example of checking rate limits using cURL:

curl -i "Authorization: Bearer YOUR_API_TOKEN" https://onsend.io/api/status"

Status

This endpoint is to retrieve the status of the device. It provides information about whether your WhatsApp device is connected, not connected, or connecting.

`GET https://onsend.io/api/v1/status`

Response Description

Field	Description
name	The name of the device.
phone_number	The phone number associated with the device.
status	The current status of the device `(connected, not_connected, connecting, disabled, disconnected, logged_out).`

Code Samples

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://onsend.io/api/v1/status',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_POSTFIELDS => '',
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer [API_TOKEN]',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

<?php

$response = \Illuminate\Support\Facades\Http::accept('application/json')
    ->withToken('[API_TOKEN]')
    ->get('https://onsend.io/api/v1/status');

dump($response->body());

curl --header "Accept: application/json" \
    --header "Authorization: Bearer [API_TOKEN]" \
    https://onsend.io/api/v1/status

Response Samples

{
    "name": "Samsung A32",
    "phone_number": "60123456789",
    "status": "connected"
}

{
    "name": "iphone 12",
    "phone_number": null,
    "status": "not_connected"
}

{
    "name": "huawei",
    "phone_number": "60133106490",
    "status": "connecting"
}

{
    "name": "xiaomi",
    "phone_number": null,
    "status": "disabled"
}

{
    "name": "huawei",
    "phone_number": "60123456789",
    "status": "disconnected"
}

{
    "name": "Samsung S22",
    "phone_number": "60123456789",
    "status": "logged_out"
}

{
    "message": "Too Many Attempts."
}

Send

Send a message to specified receiver.

`POST https://onsend.io/api/v1/send`

Parameters

Attribute	Description
phone_number	string required Intended phone number of the message receiver with country code. Example: 60123456789
message	string required IF user wants to send text message only Text message to be sent. Sent as caption if an image or video is sent. Example: Hello world
type	string required Type of message to send. Can be either `text, image, video,` or `document` . Example: image
url	string required IF user wants to send media `[image, video, document]` The media URL. Currently only suppot URL from live servers. Example: https://example.com/logo.png
mimetype	string required IF user wants to send document MIME type or media type of the document to be sent. Example: application/pdf
filename	string optional The file name of document to be sent. Example: invoice.pdf

Response Description

Field	Description
success	Boolean indicating if the request was successful. `true` if the message was sent successfully, `false` otherwise.
message	A message describing the result of the operation. Contains success confirmation or error details.
message_id	Unique ID of the message. This can be used to track the message status or for reference in future API calls.

Common Error Responses

Scenario	Description
Device Not Connected	This error occurs when your WhatsApp device is not connected. Go to the Devices section in your dashboard and scan the QR code to connect your device.
Invalid Parameters	This error occurs when required parameters are missing or invalid. Check that all required fields are provided and in the correct format. Common validation errors include: Missing or invalid phone number Missing message Missing URL for media types Missing mimetype for document
No Active Subscription	This error occurs when your device doesn't have an active subscription package. Check your subscription status in the dashboard and renew if necessary.

Data Samples

{
    "phone_number": "60123456789",
    "message": "Hello world"
}

{
    "phone_number": "60123456789",
    "message": "Logo",
    "type": "image",
    "url": "https://example.com/logo.png"
}

{
    "phone_number": "60123456789",
    "message": "My video",
    "type": "video",
    "url": "https://example.com/myvideo.mp4"
}

{
    "phone_number": "60123456789",
    "type": "document",
    "url": "https://example.com/invoice.pdf",
    "mimetype": "application/pdf",
    "filename": "invoice.pdf"
}

Code Samples

<?php

$curl = curl_init();

$data = [
    'phone_number' => '60123456789',
    'message' => 'Hello world',
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://onsend.io/api/v1/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer [API_TOKEN]',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

<?php

$data = [
    'phone_number' => '60123456789',
    'message' => 'Hello world',
];

$response = \Illuminate\Support\Facades\Http::accept('application/json')
    ->withToken('[API_TOKEN]')
    ->post('https://onsend.io/api/v1/send', $data);

dump($response->body());

curl --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer [API_TOKEN]" \
    --request POST \
    --data '{"phone_number":"60123456789","message":"Hello world"}' \
    https://onsend.io/api/v1/send

Response Samples

{
    "success": true,
    "message": "The message has been sent successfully.",
    "message_id": 38
}

{
    "success": false,
    "message": "Failed to send the message.",
    "message_id": 39
}

{
    "message": "This device is not connected."
}

{
    "message": "The phone number field must be a valid phone number. (and 3 more errors)",
    "errors": {
        "phone_number": [
            "The phone number field must be a valid phone number."
        ],
        "message": [
            "The message field must be a string."
        ],
        "url": [
            "The url field is required when type is image."
        ],
        "mimetype": [
            "The mimetype field must be a string."
        ]
    }
}

{
    "message": "This device does not have an active subscription."
}

{
    "message": "Too Many Attempts."
}