Package: gatum-rest-py
Python library for Gatum REST APIThe library for interacting withGatum REST API.Requires Python 3.10 or later.Getting StartedTo use the library, first install it from PyPI usingpip:pip install gatum-rest-pyUsage for Gatum REST APIGetting a REST API tokenTo get a REST API token, you need to go through the OAuth2.0 authorization procedure using your login and password from WEB account.fromgatum_rest_pyimportGatumRESTAPI# base_url should be replaced with the URL of your vendorclient=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}}orHTTP Status code: 400
JSON data: {'status': False, 'error_code': 400, 'errors': {'password': ['Incorrect username or password.']}}Account Informationfromgatum_rest_pyimportGatumRESTAPIclient=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 formatRegister a new customerfromgatum_rest_pyimportGatumRESTAPIclient=GatumRESTAPI(base_url='https://restapi.gatum.io/')response=client.register_customer(login='restap141i',# required, login of a new accountpassword='restapirestapi',# required, password of a new accountname='John',# required, name of the person responsible for the new accountphone='1234567890',# required, contact phone numberemail='john.doe@gmail.com',# requiredcompany_name='John Doe LTD',# optionalskype='johndoe')# optionalprint(response.json())Send SMSfromgatum_rest_pyimportGatumRESTAPIclient=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 formatsender_id="Verify",# required, numeric SID length must be 3-15 symbols,# alphanumeric SID length must be <= 11 symbolstext="Your OTP is 42488",# requiredsms_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 datebegin_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 timedelivery=True)# optional, whether to return the DLR, True or False, by default: Trueprint(response.json())Get info about sent SMSfromgatum_rest_pyimportGatumRESTAPIclient=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 MCCmnc=0,# optional, filter by MNCsender_id="Verify",# optional, filter by Sender IDphone=["380957225759","380661093766"],# optional, filter by phone numbersid_base=[2,4,6,22],# optional, filter by Group IDlimit=None,# optional, number of SMS about which to return datatime_period="2023-07-24 00:00:00 - 2023-07-24 23:59:59",# optional, filter by SMS sending periodtype_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())Working with Group of numbersView the list of Groups:fromgatum_rest_pyimportGatumRESTAPIclient=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())Create a new Group:fromgatum_rest_pyimportGatumRESTAPIclient=GatumRESTAPI(base_url='https://restapi.gatum.io/')access_token="your_token"response=client.create_group(access_token=access_token,name_group='All clients',# requiredtime_birth='13:00',# optional, what time to send greetingsoriginator_birth='Greetings',# optional, sender ID with which the greeting will be senttext_birth='Happy birthday, #first_name#!',# optional, greeting text,# #first_name# will be replaced with the corresponding name from the databaseon_birth=True)# whether to send a greetingprint(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())Delete list of groups by IDs:fromgatum_rest_pyimportGatumRESTAPIclient=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())Working with numbers in GroupAdd phone numbers to a Group:fromgatum_rest_pyimportGatumRESTAPIclient=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 tonumbers=numbers)# requiredprint(response.json())Search for phone numbers in the Group:fromgatum_rest_pyimportGatumRESTAPIclient=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())Delete phone numbers from the Group:fromgatum_rest_pyimportGatumRESTAPIclient=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())Make SMS sending to numbers from Groups:Theid_group,id_group_excludedandphoneparameters are used to designate the numbers to which you want to send.If theid_group_excludedparameter 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 theid_groupparameter or in the list specified by thephoneparameter.Theid_group_excludedandphoneparameters can be omitted if they are not required.Thedate_start,time_startandtime_stopparameters 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.fromgatum_rest_pyimportGatumRESTAPIclient=GatumRESTAPI(base_url='https://restapi.gatum.io/')access_token="your_token"response=client.send_bulk(access_token=access_token,sender_id='VShop',# requiredtext='Place an order today and get a discount',# requiredid_group=[956,959],# required, list of number group IDs for sendingid_group_excluded=[957],# optionalphone=['1234567890','1234567891'],# optionaldate_start='2023-08-02',# optionaltime_start='10:00',# optionaltime_stop='17:00')# optionalprint(response.json())Working with Personal Black ListAdd a list of numbers to the Black List:fromgatum_rest_pyimportGatumRESTAPIclient=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())Search the list of numbers in the Black list:fromgatum_rest_pyimportGatumRESTAPIclient=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())Delete the list of numbers from the Black list:fromgatum_rest_pyimportGatumRESTAPIclient=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())Logout (token destroy)fromgatum_rest_pyimportGatumRESTAPIclient=GatumRESTAPI(base_url='https://restapi.gatum.io/')access_token="your_token"response=client.logout(access_token=access_token)print(response.json())Receive DLRTo receive DLR, you need to go to theAPI>RESTAPIsection in your WEB cabinet and in theDLR sending to webhookfield, specify the webhook URL where Gatum should send them.For example, you specified the URL of your webhook ashttps://yourdomain.com/restdlr, in this case, to send DLR Gatum will make a POST request to the URLhttps://yourdomain.com/apidlrwith a JSON list of your DLRs data as payload.To confirm that you received the DLRs, you need to return a list ofid_stateparameter values in response to this request.An example of a simple listener written using the Python Flask framework:fromflaskimportFlask,requestapp=Flask(__name__)@app.route('/restdlr',methods=['POST'])defreceive_dlr():rec_dlr=request.jsonid_list=[]foriteminrec_dlr:id_list.append(str(item['id_state']))print(f'DLRs data:{rec_dlr}')print(f'List of IDs:{id_list}')returnid_list,200if__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']