1 of 10

V2

Getting Started

OCA SMS Gateway provide solution to send SMS. In order to hit the OCA SMS Gateway, we provide Endpoint url, so client can hit and use the API.

OCA Endpoint URL : https://webapigw.ocatelkom.co.id

Before you start

You will need :

OCA API Dashboard account username and password

Response Code

The OCA SMS API Gateway attempts to return the appropriate HTTP Status Codes for every request

Code

Text

Description

200

Success

401

Unauthorized

Missing or Incorrect authentication details

404

Not Found

There is no data available, like user setting etc

406

Not Acceptable

Response when there is invalid format in request

429

To Many Request

Returned when a request cannot be served due to the system's rate limit having been exhausted for the resource

500

Internal Server Error

Something is broken. This is usually a temporary error in server

Error Message

OCA SMS API error messages are returned in JSON Format. Each HTTP Status Code will be accompanied by descriptive error text and code. For example, an error might occur.

{"errors": [{"message": "Invalid Authentication Credentials", "code": 17}]}

Error Codes

This error codes is additional information to explain what happened when some errors occured. The following table describe the code which may appear when working with OCA SMS API Gateway. If an error is not listed in the table, going back to HTTP status codes above in order to determine the best way to address the issues.

Code

Text

Description

low-balance

Indicationg that your account has no enough balance left

Too Many Request Code

Due to the api rate limit, you have to wait until the currently window wxpires, the default api rate limit is in 25 request per seconds. You can check http headers reaponse in order to know the remaining limit of your request. - X-RateLimit-limit : the rate limit of endpoint - X-RateLmit-Remaining : the number of request left - X-RateLimit-Reset : the remaining window before the rate limit resets

Internal Error

Corresponds with HTTP 500. An unknown internal error occured

Missing Authorization Header

Corresponds with HTTP 401. It indicates Authorization header is not set properly

Data doesn't exist

Corresponds with HTTP 404. The certain data is not found

[object]

Corresponds with HTTP 406. There are incorrects or missing parameter in request body, it is like the message_value is not same as the template message

Auth token is not supplied

Corresponds with HTTP 401. It indicates Authorization header is not set properly

Auth token is not valid

Corresponds with HTTP 401. It indicates Authorization token is not valid

SMS Template doesn't exist Code

Corresponds with HTTP 406. Your message template doesn't exist

Authorization

OCA SMS API provides an authorization method for you to access our resources, which we primarily use Access Token JSON Web Token (JWT). You can get the Access Token by generating it on our API dashboard.

Generate Access Token

This is the initial display for users who have never generated an access token

Select the channel you want to generate an access token, then click the red button that says "Generate". then access token will be downloaded to your computer in the form of a .txt file.

endpoint

Sending Message

HTTP Method : POST

Endpoint URL : https://webapigw.ocatelkom.co.id/sms/v2/sms

Requesst Body:

Property

Type

phone

String (Destination phone number)

message

String (Message body)

{
    "phone": "6281xxxxxxxx",
    "message": "Hi Galih"
}

Response:

Property

Type

status

String

msg_uid

String

{
    "status": "sent",
    "msg_uid": "df82xxxx-a5xx-44xx-86xx-57f4e7e8xxxx"
}

Get History Send Message

HTTP Method : GET

Endpoint URL : https://webapigw.ocatelkom.co.id/sms/v2/sms/history

Response List (Array)

Property

Type

phone_number

String (Destination phone number)

message_body

String

created_at

ISO Date

status

String

msg_id

String

total_sms

Number (total sms per 160 characters)

[
    {
        "phone_number": "+6281xxxxxxx",
        "message_body": "test message",
        "status": "send",
        "operator_cell": "TELKOMSEL",
        "status_description": "",
        "aditional_data": null,
        "country": "ID",
        "source": "api",
        "uuid": "xxxx961fc19f4aefi54fxxxx",
        "total_sms": 1,
        "created_at":"2024-03-01T03:22:58.073Z", 
        "updated_at": "2024-03-01T03:22:58.073Z",
        "history_status": [],
        "msgid": "xxxx961fc19f4aefi54fxxxx"
    },
    {
        "phone_number": "+6281xxxxxxx",
        "message_body": "test message",
        "status": "send",
        "operator_cell": "TELKOMSEL",
        "status_description": "",
        "aditional_data": null,
        "country": "ID",
        "source": "api",
        "uuid": "xxxxd31fc19f4aefi54fxxxx",
        "total_sms": 1,
        "created_at":"2024-03-01T03:22:58.073Z", 
        "updated_at": "2024-03-01T03:22:58.073Z",
        "history_status": [],
        "msgid": "xxxxd31fc19f4aefi54fxxxx"
    }
]

Get Detail / Status Send Message

HTTP Method : GET

Endpoint URL : https://webapigw.ocatelkom.co.id/sms/v2/sms/status/{{fill_with_msg_uid}}

Response:

Property

Type

phone_number

String (Destination phone numbers)

message_body

String

created_at

ISO Date

status

String

msg_id

String

total_sms

Number (total sms per 160 characters)

{
    "status": true,
    "data": {
        "application": "xxx7088756827000297dxxxx",
        "phone_number": "+62813xxxxxxx",
        "message_body": "test message",
        "status": "sent",
        "operator_cell": "TELKOMSEL",
        "status_description": "",
        "country": "ID",
        "source": "api",
        "total_sms": 1,
        "created_at":"2024-03-01T03:22:58.073Z", 
        "updated_at": "2024-03-01T03:22:58.073Z",
        "msgid": "xxx961fc19f4aefi54fxxxx"
    }
}

Error Codes

Code

Text

Description

low-balance

Indicationg that your account has no enough balance left

Too Many Request Code

Internal Error

Corresponds with HTTP 500. An unknown internal error occured

Missing Authorization Header

Corresponds with HTTP 401. It indicates Authorization header is not set properly

Data doesn't exist

Corresponds with HTTP 404. The certain data is not found

[object]

Corresponds with HTTP 406. There are incorrects or missing parameter in request body, it is like the message_value is not same as the template message

Auth token is not supplied

Corresponds with HTTP 401. It indicates Authorization header is not set properly

Auth token is not valid

Corresponds with HTTP 401. It indicates Authorization token is not valid

SMS Template doesn't exist Code

Corresponds with HTTP 406. Your message template doesn't exist

Get History Send Message

HTTP Method : GET

Endpoint URL : https://webapigw.ocatelkom.co.id/sms/v2/sms/history

Response List (Array)

Property

Type

phone_number

String (Destination phone number)

message_body

String

created_at

ISO Date

status

String

msg_id

String

total_sms

Number (total sms per 160 characters)

[
    {
        "phone_number": "+6281xxxxxxx",
        "message_body": "test message",
        "status": "send",
        "operator_cell": "TELKOMSEL",
        "status_description": "",
        "aditional_data": null,
        "country": "ID",
        "source": "api",
        "uuid": "xxxx961fc19f4aefi54fxxxx",
        "total_sms": 1,
        "created_at":"2024-03-01T03:22:58.073Z", 
        "updated_at": "2024-03-01T03:22:58.073Z",
        "history_status": [],
        "msgid": "xxxx961fc19f4aefi54fxxxx"
    },
    {
        "phone_number": "+6281xxxxxxx",
        "message_body": "test message",
        "status": "send",
        "operator_cell": "TELKOMSEL",
        "status_description": "",
        "aditional_data": null,
        "country": "ID",
        "source": "api",
        "uuid": "xxxxd31fc19f4aefi54fxxxx",
        "total_sms": 1,
        "created_at":"2024-03-01T03:22:58.073Z", 
        "updated_at": "2024-03-01T03:22:58.073Z",
        "history_status": [],
        "msgid": "xxxxd31fc19f4aefi54fxxxx"
    }
]