NAV
shell

Introduction

Welcome to the sidobe.com WhatsApp API v1 documentation. Before using the API service, make sure you have successfully registered your WhatsApp Devices on the dashboard and have obtained the Secret Key for authentication.

Production URL: https://api.sidobe.com/wa/v1

Rate Limit

Response body JSON if reach limit rate limitting:

{
    "message": "rate limit exceeded"
}

To provide a stable and reliable API service, we have introduced a rate limiter for our services that restricts the number of requests that can be made within a specific time frame.

If you exceed this limit, you will receive a http status code 429 indicating that you have exceeded the rate limit. To avoid this, we strongly recommend that you implement batch processing.

Please be aware that the rate limit is subject to change based on system load and performance, and we reserve the right to adjust the limit as necessary to maintain the stability of our API service.

Asynchronous (Async)

We provide asynchronous (async) processing in several features such as Send Message, Send Message Image, Send Message Doc, etc.

Processing as async means handing over the process (ex: sending messages) to the Sidobe queue system, this will provide a faster API response, because your request is only registered in the Sidobe queue system, and waits for your request to be processed (as soon as possible ).

In contrast, if you request as synchronous (sync) or is_async = false or do not include the is_async payload, your request will be processed immediately but usually the API response will be slower, because there is some logic that must be carried out (ex : device verification, sending messages to WhatsApp, waiting for WhatsApp response, etc.). However, the advantage of this method is that you can immediately see the results of your request (ex: WhatsApp messages are sent immediately)

Authentication

curl --location 'https://api.sidobe.com/wa/v1' \
  --header 'X-Secret-Key: 1234567' \
  --header 'Content-Type: application/json'  

Make sure to replace 1234567 with your Secret key.

For API authentication, we use a header to place the secret key with the header key X-Secret-Key and all API requests must be included, for example:

X-Secret-Key: 1234567

You can get the Secret Key via the Developer Tools -> Credential menu on the dashboard

WhatsApp Messages

Send Message

curl --location 'https://api.sidobe.com/wa/v1/send-message' \
  --header 'X-Secret-Key: 123123' \
  --header 'Content-Type: application/json' \
  --data '{
      "phone": "+628123123123",
      "message": "example message"
  }'

The above command returns JSON structured like this:

{
  "is_success": true,
  "data": {
      "id": "1"
  }
}

This endpoint is used to send WhatsApp messages to your destination/customer number.

HTTP Request

POST https://api.sidobe.com/wa/v1/send-message

Body params

Parameter Type Description
phone * string required The destination W.A number is in the format e164 (ex. +628xxxxxx)
message * string required Messages WhatsApp
is_async boolean optional Process send message asynchronous or synchronous. Read full about async in the Asynchronous section.

Response Body

Key Type Description
is_success boolean true if request successfully and false if request failed
data.id string message ID

Send Message Image

curl --location 'https://api.sidobe.com/wa/v1/send-message-image' \
  --header 'X-Secret-Key: 123123' \
  --header 'Content-Type: application/json' \
  --data '{
      "phone": "+628123123123",
      "message": "example message",
      "image_url": "https://sidobe.com/wp-content/uploads/2023/09/logo-2.png"
  }'

The above command returns JSON structured like this:

{
  "is_success": true,
  "data": {
      "id": "1"
  }
}

This endpoint is used to send WhatsApp messages with image to your destination/customer number.

HTTP Request

POST https://api.sidobe.com/wa/v1/send-message-image

Body params

Parameter Type Description
phone * string required The destination W.A number is in the format e164 (ex. +628xxxxxx)
message string optional Messages or caption for the image
image_url * string required URL of image, only image type jpg/jpeg & png are allowed, maximum size is 10 MB.
is_async boolean optional Process send message asynchronous or synchronous. Read full about async in the Asynchronous section.

Response Body

Key Type Description
is_success boolean true if request successfully and false if request failed
data.id string message ID

Send Message Document

curl --location 'https://api.sidobe.com/wa/v1/send-message-doc' \
  --header 'X-Secret-Key: 123123' \
  --header 'Content-Type: application/json' \
  --data '{
      "phone": "+628123123123",
      "message": "example message",
      "document_url": "https://sidobe.com/example.pdf",
      "document_name": "Document Name Example"
  }'

The above command returns JSON structured like this:

{
  "is_success": true,
  "data": {
      "id": "1"
  }
}

This endpoint is used to send WhatsApp messages with document to your destination/customer number.

HTTP Request

POST https://api.sidobe.com/wa/v1/send-message-doc

Body params

Parameter Type Description
phone * string required The destination W.A number is in the format e164 (ex. +628xxxxxx)
message string optional Messages or caption for the document
document_url * string required URL of document, only docs type PDF, DOC, DOCX, PPT, PPTX, XLS and XLSX are allowed, maximum size is 10 MB.
document_name * string required Name for the document to be sent, the name of this document will appear in the chat and as the file name when saved. There is no need to write the file extension, just the name.
is_async boolean optional Process send message asynchronous or synchronous. Read full about async in the Asynchronous section.

Response Body

Key Type Description
is_success boolean true if request successfully and false if request failed
data.id string message ID

WhatsApp Utilities

Check Phone Number

curl --location 'https://api.sidobe.com/wa/v1/utilities/check-number' \
  --header 'X-Secret-Key: 123123' \
  --header 'Content-Type: application/json' \
  --data '{
      "phone": "+628123123123"
  }'

The above command returns JSON structured like this:

{
  "is_success": true,
  "data": {
      "is_registered": true
  }
}

This endpoint is used to check phone number is registered or used WhatsApp or not.

HTTP Request

POST https://api.sidobe.com/wa/v1/utilities/check-number

Body params

Parameter Type Description
phone * string required The phone number you want to check is whether it is registered on WhatsApp or not, format e164 (ex. +628xxxxxx)

Response Body

Key Type Description
is_success boolean true if request successfully and false if request failed
data.is_registered boolean true if phone number registered using WhatsApp and false if phone number not registered

Errors

HTTP Status Code

Sidobe.com uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, invalid secret key, etc). Codes in the 5xx range indicate an error with servers.

Status Code Description
2xx Everything worked as expected
400 Bad Request -- Your request is invalid, please read Error Code section.
401 Unauthorized -- Your Secret Key is wrong.
404 Not Found -- The specified resource could not be found.
429 You have exceeded the rate limit.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Error Code

Example failed request with error code:

{
    "is_success": false,
    "message": "The API key provided is invalid. Please make sure to use the secret/public API key that you can obtain from the Dashboard.",
    "error_code": "INVALID_API_KEY"
}

Explanation of the error code in the API response:

Error Code Meaning
API_VALIDATION_ERROR Invalid request errors arise when your request has invalid parameters.
INVALID_API_KEY Unauthorized -- Your API key is wrong or issue.
INVALID_REQUEST Invalid request you can retry your request, If the request still fails, contact us to get a solution.
INVALID_DEVICE_WHATSAPP There is a problem with the WhatsApp device/account that you registered on the dashboard, please check whether your WhatsApp account has a problem, if there is no problem, please delete it and re-register it on the dashboard.