gatum-rest-py 1.0.0

Python library for interacting with Gatum REST API

Python library for Gatum REST API

The library for interacting with Gatum REST API.

Requires Python 3.10 or later.

Getting Started

To use the library, first install it from PyPI using pip:

pip install gatum-rest-py

Usage for Gatum REST API

Getting a REST API token

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.']}}

Account Information

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 format

Register a new customer

from 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='[e-mail]', # required
                                    company_name='John Doe LTD', # optional
                                    skype='johndoe') # optional
print(response.json())

Send SMS

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())

Get info about sent SMS

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())

Working with Group of numbers

View the list of Groups:

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())

Create a new Group:

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())

Delete list of groups by IDs:

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())

Working with numbers in Group

Add phone numbers to a Group:

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())

Search for phone numbers in the Group:

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())

Delete phone numbers from the Group:

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())

Make SMS sending to numbers from Groups:

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())

Working with Personal Black List

Add a list of numbers to the Black List:

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())

Search the list of numbers in the Black list:

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())

Delete the list of numbers from the Black list:

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())

Logout (token destroy)

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())

Receive DLR

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']