Send SMS to OnlineSIM

POSThttps://{ourserver.com}/v1/PUSH_SMS

This is a webhook for sending messages to the OnlineSIM server. Send it automatically when your number with an active operation receives a message.

Send a JSON body in UTF-8 (Content-Type: application/json). The operation is found by phone; the SMS goes to the operation on that number whose ordered service matches the sender and text.

If you get {"status": "SUCCESS"}, the SMS can be marked in your database as delivered (don't send it again).

Business errors are answered with HTTP 200 and {"status": "ERROR", "error": "<code>"}; they are final, do not repeat such requests. If the request fails at the network level or is answered with HTTP 500 (INTERNAL_ERROR), repeat it after a pause (for example, 10 seconds).

Possible errors (the set depends on the integration):

  • NO_OP - there is no active operation on the number, or none of its operations was ordered for the service the SMS came from;
  • BAD_SERVICE - the SMS comes from a blocked sender (banks, payment systems, etc.);
  • IGNORED - the SMS comes from a service different from the one the client ordered;
  • SERVICE_BAN / BANNED - the sender is blocked for your integration;
  • BAD_REQUEST - phone, phoneFrom or text is missing or empty (listed in missing);
  • INTERNAL_ERROR (HTTP 500) - the request could not be processed.

Request Body

PUSH_SMS webhook: your server must send this request once an event is triggered (when the ordered number has received a message).

Content-Typeapplication/json
Schema
schemaobject
smsIdinteger
Operation ID (the activationId you returned in GET_NUMBER); some integrations use it to find the operation≥ 1Example:355
phoneFromstringRequired
Name or phone number of the sender (anything after @ is cut off)Example:Instagram
phonestringRequired
Phone number with an active operation that has received the SMS, in international format with the country code, digits only (as returned in GET_NUMBER)Example:79088081050
textstringRequired
Message textExample:Your verification code is 800142
actionstring
Method name, in this case PUSH_SMSEnum:PUSH_SMSExample:PUSH_SMS
keystring
API key of your OnlineSIM partner profile. The integration is identified by the webhook URL; whether the key is checked depends on the integrationExample:apikey

Examples

request

PUSH_SMS request from your server

{
  "smsId": 124971,
  "phoneFrom": "vk",
  "phone": "79104041216",
  "text": "Your OTP 46875",
  "action": "PUSH_SMS",
  "key": "apikey"
}

Responses

200OnlineSIM server response: the SMS is accepted or rejected with an error code
Content-Typeapplication/json
Schema
schemaobject
statusstringRequired
Response statusEnum:SUCCESSERRORExample:SUCCESS
errorstring
Error code (with status: ERROR)Enum:NO_OPBAD_SERVICEIGNOREDSERVICE_BANBANNEDBAD_REQUESTExample:NO_OP
missingstring[]With BAD_REQUEST: the missing or empty fieldsExample:[ "text" ]
messagestring
With BAD_REQUEST: a human-readable descriptionExample:Missing or empty fields: text

Examples

success

The SMS is accepted

{
  "status": "SUCCESS"
}
NO_OP

No active operation for this number and service

{
  "status": "ERROR",
  "error": "NO_OP"
}
BAD_SERVICE

The sender is blocked (banks, payment systems, etc.)

{
  "status": "ERROR",
  "error": "BAD_SERVICE"
}
IGNORED

The SMS comes from a service other than the ordered one

{
  "status": "ERROR",
  "error": "IGNORED"
}
SERVICE_BAN

The sender is blocked for your integration

{
  "status": "ERROR",
  "error": "SERVICE_BAN"
}
BAD_REQUEST

A required field is missing or empty

{
  "status": "ERROR",
  "error": "BAD_REQUEST",
  "missing": [
    "text"
  ],
  "message": "Missing or empty fields: text"
}
500The request could not be processed: repeat it later
Content-Typeapplication/json
Schema
schemaobject
statusstring
Enum:ERRORExample:ERROR
errorstring
Enum:INTERNAL_ERRORExample:INTERNAL_ERROR

Examples

INTERNAL_ERROR

Internal error

{
  "status": "ERROR",
  "error": "INTERNAL_ERROR"
}

Code Samples

Generating examples...