API GENERAL OVERVIEW

API - based on HTTP protocol. Communication implemented on client–server basis.

The platform accepts GET/POST requests. It returns GET request with DLR (message status).

GET requests from the user must be URL encoded.

SECURITY AND CONFIDENTIALITY

  1. The platform uses HTTPS protocol
  2. There is an IP restriction for every user.
  3. When passing each request, username and password are validated.
  4. Option for a VPN connection.

In case some of the above-mentioned verifications are not passed successfully – request for SMS will be denied and the client notified. In case of a malicious attack, IP of the sender will be blocked.

SMS
Swagger

  1. Please contact Mobica support (support@mobica.bg) in order to receive username and password. They will be your identifier when sending a short text message.
  2. Your account starts with a small amount of money for testing. After money’s depletion, it is necessary to top-up your account in order to use the service.
  3. You must configure IP addresses that you will be sending requests from.

PARAMETERS

Parameter Description Obligatory
user Your username yes
pass Your password yes
phone Receiver’s number must contain country code (for example: 359 888888888). One request can contain more than one mobile phone number using a comma (,) to separate the numbers. yes
message Message text. The length of the text with Latin symbols is up to 160 characters. When the text is in Cyrillic (Unicode), the limit is up to 67 characters. If the symbols exceed this number,they are paid with an additional short text message. yes
from Message sender (Sender ID). There is a limit up to 11 symbols, if your route allows an alpha sender. If not provided, a default will be used. Your client is set by an administrator. no
route Number of package.The message will be sent from (integer). If you have more than one package. If not provided, it will go via the package that is configured by default. no
idd Unique identification number of your short text message. It serves to receive a dynamic status (string). NO
(YES for DLR)
smartCut When text length exceeds one short text message, the network processes it as two or more text messages Smart cut attempts not to cut words in the text. Activation occurs with random monetary value. no
priority INT default value (0) - default priority ,The hightest priority is 255. no
toDate Future date format (YYYY-mm-dd h:min) on which the SMS will be delivered. If not provided, SMS is instant. no
Table 1

RESPONSE CODES

# Description Status
1 Successfully accepted request 1004
2 Rejected request 1005
3 Invalid Phone Number 1006
4 Invalid schedule data 1007
5 Invalid Request Format 1008
6 Invalid username or password 1115
7 Money in your account have ran out 1117
8 No value for obligatory field is set 1120
9 Request sent from unauthorized IP address 1121
10 Account is not active 1122
Table 2

JSON POST REQUEST

REQUEST URL

https://gate.mobica.bg/v2/multi/json/sms.php

REQUIRED HEADERS

Accept: application/json

Content-Type: application/json

MULTIPLE MESSAGE

{ "user": "username", "pass": "password", "sms": [ { "idd": "test_idd_1", "phone": "359XXXXXXXXX", "message": "Message 1" }, { "idd": "test_idd_2", "phone": "359XXXXXXXXX" "message": "Message 2" } ] }

RESPONSE

{ "code": "1004", "description": "Message accepted" }

EXAMPLE PHP

<?php /** * @param $url * @param $request * @return mixed */ function send($url, $request) { $ch = curl_init(); $headers = [ 'Accept: application/json', 'Content-Type: application/json', ]; $options = [ CURLOPT_URL => $url, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $request, CURLOPT_FOLLOWLOCATION => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => true, CURLOPT_HTTPHEADER => $headers, ]; curl_setopt_array($ch, $options); $response = curl_exec($ch); curl_close($ch); return $response; } //API URL. $url = 'https://gate.mobica.bg/v2/multi/json/sms.php'; //API data array. $data = [ 'user' => 'username', 'pass' => 'password', 'sms' => [ [ 'idd' => 'test_idd_1', 'phone' => '359XXXXXXXXX', 'message' => 'Message 1', ], [ 'idd' => 'test_idd_2', 'phone' => '359XXXXXXXXX', 'message' => 'Message 2', ], ], ]; echo send($url, json_encode($data));

VIBER
Swagger

  1. Please contact Mobica support (support@mobica.bg) in order to receive username and password.They will be your identifier when sending a short text message.
  2. Your account starts with a small amount of money for testing. After money’s depletion, it is necessary to top-up your account in order to use the service.
  3. You must configure IP addresses that you will be sending requests from.
  4. If you wish to have a sender id, please contact our support: support@mobica.bg
    Note: To be eligible you need to have at least 200,000 messages sent per month, of which 60,000 to be delivered. If this minimum is not reached, you can still have your channel by paying minimum monthly fee 300 EUR
    Viber safe its right to cancel the channel.

REQUEST PARAMETERS

Parameter Description Obligatory
user Your username yes
pass Your password yes
viber (object) Parameters text, buttonCaption + buttonAction and image make Viber Service Message content. There are 4 possible combinations of Viber Service Message content:
  • text only
  • image only
  • text + button
  • text + button + image
 yes
viber.phone (array of object) The list of phone numbers. With one message request the customer can send up to 1000 phone numbers yes
viber.tag Free text, reports can be generated based on tags. (e.g. "campaign_name") Tags are used in analytics GUI to filter out specific traffic based on tag. no
viber.text The Viber Service Message text. Text length can be up to 1000 characters. VIBER text can be sent alone, without button or image no
viber.validity_period_sec TTL value in seconds (range - 15 to 86400). If the Viber Service message can’t be delivered within given seconds, we will send an SMS message as a fallback. no
viber. button_text A textual writing on the button. Maximum length is 20 characters.The VIBER button can be sent only if Viber Service Message contains text no
viber. button_url The link of button action. no
viber. image_url The URL address of image sent to end user. The VIBER image can be sent alone or together with text and button. no
viber. is_promotional Indicates if content is of promotional character no
viber.sms_text This text will be received via SMS if Viber message is not delivered. no
viber.idd Unique identification number of your Viber message. It serves to receive a dynamic status (string). no
(YES for DLR)
Table 3

RESPONSE CODES

# Description STATUS
1 Message accepted 1004
2 Rejected request 1005
3 Invalid Phone Number 1006
4 Invalid schedule data 1007
5 Invalid Request Format 1008
6 This messenger can not support image 1012
7 This messenger can not support button 1013
8 This messenger can not support button 1018
9 User not active 1105
10 Inactive user 1106
11 You don't have HLR permission 1107
12 Invalid username or password 1115
13 No money 1117
14 Flood 1118
15 IP not allowed 1121
Table 4

STATUS IN CALLBACK URL REQUEST

# Description STATUS
1 Waiting for transmit 1003
2 Successfully accepted request 1004
3 Rejected 1005
4 Invalid Phone Number 1006
5 Invalid Request Format 1008
6 Messenger text is empty 1010
7 Messenger text must be under 1000 and over 3 symbols 1011
8 Button text length is large 1014
9 SMS text must be under 160 and over 3 symbols 1015
10 Invalid image source 1016
11 Button url is invalid 1017
12 Flood 1018
13 Cannot support button without text 1019
14 SMS text is required 1020
15 Invalid username or password 1115
16 Money in your account have ran out 1117
17 Messenger not allowed 1119
18 No value for obligatory field is set 1120
19 Request sent from unauthorized IP address 1121
20 Account is not active 1122
21 Phone number is in blacklist 1209
Table 5

JSON POST REQUEST

REQUEST URL

https://gate.mobica.bg/v2/multi/json/viber.php

REQUIRED HEADERS

Accept: application/json

Content-Type: application/json

MULTIPLE MESSAGE

{ "user": "username", "pass": "password", "viber": [ { "idd": "test_idd_1", "tag": "Mobica", "phone": "359XXXXXXXXX", "text": "Message 1", "image_url": "", "button_url": "", "button_text": "", "is_promotional": 0, "validity_period_sec": 600, "sms_text": "SMS message" }, { "idd": "test_idd_2", "tag": "Mobica", "phone": "359XXXXXXXXX", "text": "Message 2", "image_url": "", "button_url": "", "button_text": "", "is_promotional": 0, "validity_period_sec": 600, "sms_text": "SMS message" } ] }

RESPONSE

{ "code": "1004", "description": "Message accepted" }

EXAMPLE PHP

<?php /** * @param $url * @param $request * @return mixed */ function send($url, $request) { $ch = curl_init(); $headers = [ 'Accept: application/json', 'Content-Type: application/json', ]; $options = [ CURLOPT_URL => $url, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $request, CURLOPT_FOLLOWLOCATION => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => true, CURLOPT_HTTPHEADER => $headers, ]; curl_setopt_array($ch, $options); $response = curl_exec($ch); curl_close($ch); return $response; } //API URL. $url = 'https://gate.mobica.bg/v2/multi/json/viber.php'; //API data array. $data = [ 'user' => 'username', 'pass' => 'password', 'viber' => [ [ 'idd' => 'test_idd_1', 'tag' => 'Mobica', 'phone' => '359XXXXXXXXX', 'text' => 'Message 1', 'image_url' => '', 'button_url' => '', 'button_text' => '', 'is_promotional' => 0, 'validity_period_sec' => 600, 'sms_text' => 'SMS message', ], [ 'idd' => 'test_idd_2', 'tag' => 'Mobica', 'phone' => '359XXXXXXXXX', 'text' => 'Message 2', 'image_url' => '', 'button_url' => '', 'button_text' => '', 'is_promotional' => 0, 'validity_period_sec' => 600, 'sms_text' => 'SMS message', ], ], ]; echo send($url, json_encode($data));

HLR (NUMBER LOOKUP)
Swagger

HLR (Home Location Register) is an online service that provides information about home country and network of a mobile subscriber, validity verification, current location, ported number identification.

  1. Please contact Mobica support (support@mobica.bg) for username and password. They will be your identifier when sending HLR.
  2. Your account will be loaded with a small amount of money for testing. After its depletion, it is necessary to topup your account, in order to use the service.
  3. You must configure IP addresses that you will be sending requests from.

REQUEST PARAMETERS

Parameter Description Obligatory
user Your username yes
pass Your password yes
number Receiver’s number must contain country code (for example: 359 888888888). One request can contain more than one mobile phone number using a comma (,) to separate the numbers. yes
url A valid URL address must be indicated, that will be used for accepting the requests' statuses. Example: http(s)://www.yourdomain.com/callback no
reference Unique identification number of your HLR. It serves to receive a dynamic status (integer). no
email Number of package through which the message will be sent (integer). no
Table 6

RESPONSE CODES

# Description Status
1 Successfully accepted request 1004
2 Rejected request 1005
3 Invalid Phone Number 1006
4 Invalid schedule data 1007
5 Invalid Request Format 1008
6 Invalid username or password 1115
7 Money in your account have ran out 1117
8 No value for obligatory field is set 1120
9 Request sent from an unauthorized IP address 1121
10 Account is not active 1122
Table 7

STATUS IN CALLBACK URL REQUEST

Parameter Description Obligatory
NUMBER Requested number in the HLR request yes
REFERENCE Reference parameter from the sent request for HLR yes
STATUS One of the statuses in Table 9 yes
REASON When the status is not „Delivered“, the reason will be specified (Table 12). yes
TIMESTAMP Indication of the time when the server operator has received the request. The format isYYYYMMDDHHMMSS. Example: 20120501083055 yes
IMSI IMSI of the number. no
NETWORKCODE Operator’s network code. The Network code contains MCC (the country code is the first three digits) and MNC (code of the operator is the last 2 digits). Example: 20404 no
OPERATOR Country and operator. Example: (BULGARIA)GLOBUL no
COUNTRYCODE Literal index of the operator's country. Example: bg no
MSC MSC (Commutation center) to which the number is registered at the time of the verification. It starts with the country's code and operator’s code, where the subscriber's latest registration is. If it is roaming, the first digits show where he/she is located (country and mobile operator are identified). no
Table 8

STATUS IN CALLBACK URL REQUEST

# Description RESPONSE
1 The number is valid. 1000
2 The number is invalid. 1205
3 The request is rejected. 1207
4 The time of the request has run out. 1204
5 Unknown status. 1206
Table 9

REASON STATUS TABLE

Description RESPONSE
Absent subscriber (network cannot contact subscriber) 1
Handset memory exceeded 2
Equipment protocol error 3
Equipment not equipped with short-message capability 4
Unknown service centre (destination MSC) 5
Service centre congestion (Too much inbound traffic at the destination network) 6
Invalid SME address 7
Subscriber is not a SC subscriber (Number belongs to a different destination network, but HLR is not updated) 8
Unknown subscriber (IMSI is unknown in the HLR) 9
Illegal subscriber (The mobile station failed authentication) 10
Teleservice not provisioned (Mobile subscription identified by the MSISDN number does not include the short message service. Might happen, because the number/subscriber has been blocked) 11
Illegal equipment (IMEI check failed, blacklisted or not whitelisted) 12
Call barred (Operator barred the MSISDN number) 13
Facility not supported (VLR in the PLMN does not support MT short message service) 14
Subscriber busy for MT short messages 15
System failure 16
Message waiting list at HLR is full 17
Data missing 18
Unexpected data value 19
Resource limitation at peer / destination network 20
TCAP error (Duplicate invoke ID) 21
TCAP error (Service not supported) 22
TCAP error (Mistyped parameter) 23
TCP error (Resource Limit) 24
TCAP error (TCAP initiating release) 25
TCAP error (Unexpected response from peer) 26
TCAP error (Service completion failure) 27
TCAP error (No response from peer. No response from the end user, might be because user is out of coverage, or there is some issue with his/her phone) 28
TCAP error (Invalid response received) 29
Unidentified subscriber. Unable to indentify the subscriber. Might be due to invalid number 30
Service temporary not available 31
Illegal error code 32
Network timeout 33
Operation Barred (From the MNO) 34
Delivery failure 35
cError in MSHLR 36
PLMN system failure 37
HLR system failure 38
VLR system failure 39
Controlling MSC failure (Error in the MSC where the user is located) 40
Visited MSC failure (Error in the visited MSC) 41
MNP other operator not allowed (MSISDN is ported, delivery via this SMSC is not permitted) 42
Subscriber temporarily unreachable (While roaming) 43
Message store busy 44
SME Interface busy 45
Closed user group rejection 46
Network failure 47
Deferred Delivery (Message has not been delivered and is part of a deferred delivery schedule) 48
Error getting route 49
Rejected Destination 51
Rejected - Unknown Reason 52
Rejected due to a routing issue 53
Rejected due to a blocking issue 54
Rejected - no price 55
Rejected - not enough credit 56
Rejected due to spam filter 57
Rejected due to flooding 58
UNKNOWN TCType,SMS 59
UNKNOWN TCType,SRI 60
UNKNOWN 61
Failure due to submission towards AA19 destination 62
Sent to SME, but unable to confirm 63
Replaced at the SMSC 64
Quality service not available 65
Error in SMSC 66
Rejected by operator due to validity period expiration 67
Intermediate state notification; message has not been delivered yet, due to a phone-related problem, but is being retried 68
Cannot determine whether this message has been delivered, or it has failed, due to a lack of final delivery state information from the operator. 69
Specific content is not permitted on the network / shortcode 70
Subscriber cannot receive adult content because of a parental lock 71
Failure due to ported combinations being unreachable. 72
Roaming subscriber. 73
Failure due to ported combinations being blocked for client (Client has been blacklisted from the ported destination). 74
Abort from HLR 75
Source address is blacklisted or not supported 76
Operation barred 77
Facility not provided 78
Invalid absolute validity period 79
SMS center received 80
Invalid PDU format 81
Local Cancel (Temporary problem / Lost reach) 82
Rejected due to duplication 83
Maximum connection reached 84
Information not available 85
Message waiting list is full 86
Short term denial 87
Message replaced by SMSC 89
Congestion at subscriber 90
Service rejected 91
Error in SME 92
Remote procedure error 93
Connection rejected by SME 94
SM deleted by sender 95
SM deleted by SMSC Admin 96
Absent subscriber IMSI detached 97
SMS malformed 98
DCS inconsistency 99
Maximum submission attempt reached 100
Maximum time to live for message reached 101
No response from SME 102
Maximum submission attempt reached (finalised before validity period expiration) 103
Max TTL for message reached (finalised when validity period expired) 104
Portability error 105
Canceled at SMSC 106
Table 10

MULTIPLE MESSAGE

{ "user": "username", "pass": "password", "hlr": [ { "reference": "test_idd_1", "number": "359XXXXXXXXX", "url": "", "email": "" }, { "reference": "test_idd_2", "number": "359XXXXXXXXX", "url": "", "email": "" }, ] }

RESPONSE

{ "code": "1004", "description": "Message accepted" }

EXAMPLE PHP

<?php /** * @param $url * @param $request * @return mixed */ function send($url, $request) { $ch = curl_init(); $headers = [ 'Accept: application/json', 'Content-Type: application/json', ]; $options = [ CURLOPT_URL => $url, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $request, CURLOPT_FOLLOWLOCATION => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => true, CURLOPT_HTTPHEADER => $headers, ]; curl_setopt_array($ch, $options); $response = curl_exec($ch); curl_close($ch); return $response; } //API URL. $url = 'https://gate.mobica.bg/v2/multi/json/hlr.php'; //API data array. $data = [ 'user' => 'username', 'pass' => 'password', 'hlr' => [ [ 'reference' => 'test_idd_1', 'number' => '359XXXXXXXXX', 'url' => '', 'email' => '', ], [ 'reference' => 'test_idd_2', 'number' => '359XXXXXXXXX', 'url' => '', 'email' => '', ], ], ]; echo send($url, json_encode($data));

DLR (Delivery Report)
Swagger
Check delivery report status within 24 hours from today.

  1. The best option for handling statuses is to use Webhooks. This is automatic filling of information about delivery statuses. Provide us with a web address to receive a GET request from us with a delivery report status of your message.

PARAMETERS

Parameter Description Obligatory
user Your username yes
pass Your password yes
reference_id Unique identification number of your short text message. It serves to receive a dynamic status (string). yes
Table 1

RESPONSE CODES

# Description Status
1 Rejected request 1005
2 Invalid Phone Number 1006
3 Invalid schedule data 1007
4 Invalid Request Format 1008
5 Invalid username or password 1115
6 Money in your account have ran out 1117
7 No value for obligatory field is set 1120
8 Request sent from unauthorized IP address 1121
9 Account is not active 1122
Table 2

JSON POST REQUEST

REQUEST URL

https://gate.mobica.bg/v2/multi/json/dlr_reference_id.php

REQUIRED HEADERS

Accept: application/json

Content-Type: application/json

MULTIPLE MESSAGE

{ "user": "username", "pass": "password", "dlr": [ { "reference_id": "test_id_1" }, { "reference_id": "test_id_2" } ] }

RESPONSE

{ "test_id_1": [ { "channel": "viber", "id": "test_id_1", "msisdn": 359000000000, "code": 1205, "description": "Undelivered", "date_submit": "2020-02-02 10:02:02", "date_report": "2020-02-02 10:02:20", "reply": [] }, { "channel": "sms", "id": "test_id_1", "msisdn": 359000000000, "code": 1000, "description": "Delivered", "date_submit": "2020-02-02 10:02:02", "date_report": "2020-02-02 10:02:20", "reply": [], "udh": "050003950201" }, { "channel": "sms", "id": "test_id_1", "msisdn": 359000000000, "code": 1000, "description": "Delivered", "date_submit": "2020-02-02 10:02:02", "date_report": "2020-02-02 10:02:20", "reply": [], "udh": "050003950202" } ], "test_id_2": [ { "channel": "sms", "id": "test_id_2", "msisdn": 359000000000, "code": 1000, "description": "Delivered", "date_submit": "2020-02-02 10:02:02", "date_report": "2020-02-02 10:02:20", "reply": [], "udh": "" ] }

EXAMPLE PHP

<?php /** * @param $url * @param $request * @return mixed */ function send($url, $request) { $ch = curl_init(); $headers = [ 'Accept: application/json', 'Content-Type: application/json', ]; $options = [ CURLOPT_URL => $url, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $request, CURLOPT_FOLLOWLOCATION => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => true, CURLOPT_HTTPHEADER => $headers, ]; curl_setopt_array($ch, $options); $response = curl_exec($ch); curl_close($ch); return $response; } //API URL. $url = 'https://gate.mobica.bg/v2/multi/json/dlr_reference_id.php'; //API data array. $data = [ 'user' => 'username', 'pass' => 'password', 'dlr' => [ [ 'reference_id' => 'test_idd_1', ], [ 'reference_id' => 'test_idd_2', ], ], ]; echo send($url, json_encode($data));

USER (Account Balance)
Swagger
Money are checked and updated in your account every 10 min

PARAMETERS

PARAMETER Description OBLIGATORY
user Your username YES
pass Your password YES
Table 11

JSON POST REQUEST

REQUEST URL

https://gate.mobica.bg/v2/user/account_balance.php

REQUIRED HEADERS

Accept: application/json

Content-Type: application/json

REQUEST

{ "user": "username", "pass": "password" }

RESPONSE

{ "username": "support@mobica.bg", "amount": "1000.0000", "currency": "BGN" }

EXAMPLE PHP

<?php /** * @param $url * @param $request * @return mixed */ function send($url, $request) { $ch = curl_init(); $headers = [ 'Accept: application/json', 'Content-Type: application/json', ]; $options = [ CURLOPT_URL => $url, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $request, CURLOPT_FOLLOWLOCATION => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => true, CURLOPT_HTTPHEADER => $headers, ]; curl_setopt_array($ch, $options); $response = curl_exec($ch); curl_close($ch); return $response; } //API URL. $url = 'https://gate.mobica.bg/v2/user/account_balance.php'; //API data array. $data = [ 'user' => 'username', 'pass' => 'password', ]; echo send($url, json_encode($data));
Choose how to contact us.