The library for interacting with Gatum REST API.
Requires Python 3.10 or later.
To use the library, first install it from PyPI using pip:
pip install gatum-rest-py
To get a REST API token, you need to go through the OAuth2.0 authorization procedure using your login and password from WEB account.
from gatum_rest_py import GatumRESTAPI
# base_url should be replaced with the URL of your vendor
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
response = client.access_token(username='your_login', password='your_password')
print(f'HTTP Status code: {response.status_code}')
print(f'JSON data: {response.json()}')The output:
HTTP Status code: 200
JSON data: {'status': True, 'data': {'access_token': 'gbBX8dB7kDvBeo0H-VN2CX0bAXXbyJ', 'expires_at': 2006432128}}
or
HTTP Status code: 400
JSON data: {'status': False, 'error_code': 400, 'errors': {'password': ['Incorrect username or password.']}}
from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = 'your_token'
response = client.account_info(access_token=access_token)
print(response.json()) # You will receive detailed information about your account in dictionary formatfrom gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
response = client.register_customer(login='restap141i', # required, login of a new account
password='restapirestapi', # required, password of a new account
name='John', # required, name of the person responsible for the new account
phone='1234567890', # required, contact phone number
email='john.doe@gmail.com', # required
company_name='John Doe LTD', # optional
skype='johndoe') # optional
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.send_sms(access_token=access_token,
numbers=["380957225759", "380661093766"], # required, list of destination phone numbers in MSISDN format
sender_id="Verify", # required, numeric SID length must be 3-15 symbols,
# alphanumeric SID length must be <= 11 symbols
text="Your OTP is 42488", # required
sms_type="sms", # optional, allowed types: 'sms', 'hlr', 'mnp', by default: 'sms'
lifetime='86400', # optional, how many seconds this SMS will live, by default: '86400'
begin_date='2023-03-19', # optional, the date when SMS should be sent,
# format: 'YYYY-MM-DD', by default: the current date
begin_time='19:16:00', # optional, the time when SMS should be sent in GMT+0 in selected beginDate,
# format: 'HH:MM:SS', by default: the current time
delivery=True) # optional, whether to return the DLR, True or False, by default: True
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.sms_full_data(access_token=access_token,
mcc=255, # optional, filter by MCC
mnc=0, # optional, filter by MNC
sender_id="Verify", # optional, filter by Sender ID
phone=["380957225759", "380661093766"], # optional, filter by phone numbers
id_base=[2, 4, 6, 22], # optional, filter by Group ID
limit=None, # optional, number of SMS about which to return data
time_period="2023-07-24 00:00:00 - 2023-07-24 23:59:59", # optional, filter by SMS sending period
type_sms='sms') # optional, filter by sms type, allowed types: 'sms', 'hlr', 'mnp'
print(response.json())
# All optional parameters can be omitted, such a function call will return data on all sms for the last few days:
response = client.sms_full_data(access_token=access_token)
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
# information about the first 10 groups will be obtained:
response = client.list_group(access_token=access_token, limit=10, offset=0)
print(response.json())
# to get information about the next 10 groups, you need to change the offset parameter:
response = client.list_group(access_token=access_token, limit=10, offset=1)
print(response.json())
# also you can get information about a particular group by its ID:
response = client.list_group(access_token=access_token, id_group=957)
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.create_group(access_token=access_token,
name_group='All clients', # required
time_birth='13:00', # optional, what time to send greetings
originator_birth='Greetings', # optional, sender ID with which the greeting will be sent
text_birth='Happy birthday, #first_name#!', # optional, greeting text,
# #first_name# will be replaced with the corresponding name from the database
on_birth=True) # whether to send a greeting
print(response.json())
# The parameters time_birth, originator_birth, text_birth, on_birth can be omitted if greetings are not needed.
# They will be set to False by default:
response = client.create_group(access_token=access_token, name_group='Clients for Promo')
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.delete_group(access_token=access_token, id_group=[957, 959])
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
# The format of the list of numbers should be as follows.
# Only the number parameter is required, other parameters can be omitted:
numbers = [{'number': 12345678901,
'name': 'Iogan',
'surname': 'Bah',
'patronymic': 'Sebastian',
'date_birth': '1992-12-31',
'male': 'm',
'note_1': 'tralivali',
'note_2': 'tralivali2',
'note_3': 'tralivali3',
'note_4': 'tralivali4',
'note_5': 'tralivali5',
'note_6': 'tralivali6',
'note_7': 'tralivali7',
'note_8': 'tralivali8',
'note_9': 'tralivali9',
'note_10': 'tralivali10'},
{'number': 12345678900,
'name': 'Liza',
'surname': 'Bah',
'patronymic': '',
'date_birth': '1992-12-31',
'male': 'f',
'note_1': 'tralivali',
'note_2': 'tralivali2',
'note_3': 'tralivali3',
'note_4': 'tralivali4',
'note_5': 'tralivali5',
'note_6': 'tralivali6',
'note_7': 'tralivali7',
'note_8': 'tralivali8',
'note_9': 'tralivali9',
'note_10': 'tralivali10'}]
response = client.group_number_add(access_token=access_token,
id_group=956, # required, Group ID to add numbers to
numbers=numbers) # required
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.group_number_search(access_token=access_token,
id_group=956,
numbers=[12345678900, 12345678901, 17133010164])
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.group_number_delete(access_token=access_token,
id_group=956,
numbers=[12345678900, 12345678901, 17133010164])
print(response.json())The id_group, id_group_excluded and phone parameters are used to designate the numbers to which you want to send.
If the id_group_excluded parameter is used, then all numbers contained in these groups will be excluded from the sending,
despite the fact that they may be in the groups specified by the id_group parameter or in the list specified by the phone parameter.
The id_group_excluded and phone parameters can be omitted if they are not required.
The date_start, time_start and time_stop parameters are used to schedule SMS sending.
If these parameters are set, then SMS will be sent gradually over the specified period of time.
If you need to send SMS immediately, then these parameters can be omitted.
from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.send_bulk(access_token=access_token,
sender_id='VShop', # required
text='Place an order today and get a discount', # required
id_group=[956, 959], # required, list of number group IDs for sending
id_group_excluded=[957], # optional
phone=['1234567890', '1234567891'], # optional
date_start='2023-08-02', # optional
time_start='10:00', # optional
time_stop='17:00') # optional
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.black_list_add(access_token=access_token,
numbers=[12345665777, 12345665772])
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.black_list_search(access_token=access_token,
numbers=[12345665777, 12345665772])
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.black_list_delete(access_token=access_token,
numbers=[12345665777, 12345665772])
print(response.json())from gatum_rest_py import GatumRESTAPI
client = GatumRESTAPI(base_url='https://restapi.gatum.io/')
access_token = "your_token"
response = client.logout(access_token=access_token)
print(response.json())To receive DLR, you need to go to the API > RESTAPI section in your WEB cabinet and in the DLR sending to webhook field, specify the webhook URL where Gatum should send them.
For example, you specified the URL of your webhook as https://yourdomain.com/restdlr, in this case, to send DLR Gatum will make a POST request to the URL https://yourdomain.com/apidlr with a JSON list of your DLRs data as payload.
To confirm that you received the DLRs, you need to return a list of id_state parameter values in response to this request.
An example of a simple listener written using the Python Flask framework:
from flask import Flask, request
app = Flask(__name__)
@app.route('/restdlr', methods=['POST'])
def receive_dlr():
rec_dlr = request.json
id_list = []
for item in rec_dlr:
id_list.append(str(item['id_state']))
print(f'DLRs data: {rec_dlr}')
print(f'List of IDs: {id_list}')
return id_list, 200
if __name__ == "__main__":
app.run(debug=False, port=5000)The output:
DLRs data: [{'id_state': 598933232, 'originator': 'SMS', 'phone': '380957225759', 'type_sms': 'sms', 'text_sms': 'Your OTP is 42432', 'num_parts': 1, 'part_no': 1, 'state': 'DELIVRD', 'time': '2023-07-24 12:03:48'}, {'id_state': 598933233, 'originator': 'SMS', 'phone': '380957225759', 'type_sms': 'sms', 'text_sms': 'Your OTP is 42432', 'num_parts': 1, 'part_no': 1, 'state': 'DELIVRD', 'time': '2023-07-24 12:03:48'}]
List of IDs: ['598933232', '598933233']