python-voipms

*Added support for sending MMS messages

Python client for v1 of voip.ms REST API using requests >= 2.7.0.

Getting Started

Installation

This client is hosted at PyPi under the name voipms, to install it, simply run

pip install voipms

History

Version 0.2.6 from 03.03.2024
- Fill in all missing documented methods
- Fix bugs:
  - parameter collisions with keywords, eg. filter, from, range, type, zip given non-conflicting names, eg. filter_id, date_from, time_range, search_type, zip_code
Version 0.2.5 from 25.03.2022
- Restore billing_type param in dids.set.did_info since that is now required by the voip.ms REST API
Version 0.2.4 from 02.03.2022
- Add support for setting callerid_e164 and callerid_override when calling dids.set.sip_uri
- Fix bugs:
  - Fix voicemail commands
  - Fix dids.order commands
  - Tweak dids.set.did_info to longer require the billing_type param
Version 0.2.3 from 05.04.2017
- First alpha version of this API
- Up to date with features listed through 20.02.2017
TODO:
- Code cleanup
- Cleanup of inner references to functions
- Testing all functions
- More validations of input and streamlining how to input dids (only digits or also dids with seperators)

Initialization

Go to your the voip.ms customer portal go to the API config page (Main Menu > SOAP and REST/JSON API)

YOUR_USERNAME is your voip.ms username
Set YOUR_PASSWORD
Activate the API
Set the IP address of your development server

from voipms import VoipMs

client = VoipMs('YOUR_USERNAME', 'YOUR_PASSWORD')

Examples

# return allowed IPs
client.general.get.ip()

# returns a specific allowed codec
client.accounts.get.allowed_codecs(codec="ulaw")

API Structure

All endpoints follow the structure listed in the official voip.ms API v1 documentation. The structure will be listed below and then the individual methods available after.

VoipMs
+- General
|   +- Get
+- Accounts
|   +- Create
|   +- Delete
|   +- Get
|   +- Set
+- Calls
|   +- Get
+- Clients
|   +- Add
|   +- Get
|   +- Set
+- Dids
|   +- Back_order
|   +- Cancel
|   +- Connect
|   +- Delete
|   +- Get
|   +- Order
|   +- Search
|   +- Send
|   +- Set
|   +- Unconnect
+- Fax
|   +- Cancel
|   +- Delete
|   +- Get
|   +- Mail
|   +- Move
|   +- Order
|   +- Search
|   +- Send
|   +- Set
+- Voicemail
|   +- Create
|   +- Delete
|   +- Get
|   +- Mark
|   +- Move
|   +- Send
|   +- Set

General

Get

client.general.get.balance(advanced=False)
client.general.get.countries(country=None)
client.general.get.ip()
client.general.get.languages(language=None)
client.general.get.servers_info(server_pop=None)
client.general.get.transaction_history(date_from, date_to)

Accounts

Create

client.accounts.create.sub_account(username, password, protocol, auth_type, device_type,
                                   lock_international, international_route, music_on_hold,
                                   allowed_codecs, dtmf_mode, nat, **kwargs)

Delete

client.accounts.delete.sub_account(account_id)

Get

client.accounts.get.allowed_codecs(codec=None)
client.accounts.get.auth_types(auth_type=None)
client.accounts.get.device_types(device_type=None)
client.accounts.get.dtmf_modes(dtmf_mode=None)
client.accounts.get.lock_international(lock_international=None)
client.accounts.get.music_on_hold(music_on_hold=None)
client.accounts.get.nat(nat=None)
client.accounts.get.protocols(protocol=None)
client.accounts.get.registration_status(account)
client.accounts.get.report_estimated_hold_time(time_type=None)
client.accounts.get.routes(route=None)
client.accounts.get.sub_accounts(account=None)

Set

client.accounts.set.sub_account(account_id, password, auth_type, device_type,
                                lock_international, international_route, music_on_hold,
                                allowed_codecs, dtmf_mode, nat, **kwargs)

Calls

Get

client.calls.get.call_accounts(client=None)
client.calls.get.call_billing(self)
client.calls.get.call_types(client=None)
client.calls.get.cdr(date_from, date_to, timezone,
                     answered=False, noanswer=False, busy=False,
                     failed=False, **kwargs)
client.calls.get.rates(package, query)
client.calls.get.termination_rates(route, query)
client.calls.get.reseller_cdr(date_from, date_to, client, timezone,
                              answered=False, noanswer=False, busy=False,
                              failed=False, **kwargs)

Clients

Add

client.clients.add.charge(client, charge, description=None, test=False)
client.clients.add.client(firstname, lastname, address, city, state, country,
                          zip_code, phone_number, email, confirm_email, password,
                          confirm_password, **kwargs)
client.clients.add.payment(client, payment, description=None, test=False)

Get

client.clients.get.balance_management(balance_management=None)
client.clients.get.charges(client)
client.clients.get.client_packages(client)
client.clients.get.clients(client=None)
client.clients.get.client_threshold(client)
client.clients.get.deposits(client)
client.clients.get.packages(package=None)
client.clients.get.reseller_balance(client)

Set

client.clients.set.client(client, email, password, firstname,
                          lastname, phone_number, **kwargs)
client.clients.set.client_threshold(client, threshold, email=None)

Dids

Back_order

client.dids.back_order.did_can(quantity, province, ratecenter, routing, 
                               pop, dialtime, cnam, billing_type, **kwargs)
client.dids.back_order.did_usa(quantity, state, ratecenter, routing, pop, 
                               dialtime, cnam, billing_type, **kwargs)

Cancel

client.dids.cancel.did(did, **kwargs)

Connect

client.dids.connect.did(did, account, monthly, setup, minute, **kwargs)

Delete

client.dids.delete.callback(callback)
client.dids.delete.caller_id_filtering(filtering)
client.dids.delete.client(client)
client.dids.delete.disa(disa)
client.dids.delete_sms(sms_id)
client.dids.delete.forwarding(forwarding)
client.dids.delete.ivr(ivr)
client.dids.delete.phonebook(phonebook)
client.dids.delete.queue(queue)
client.dids.delete.recording(recording)
client.dids.delete.ring_group(ringgroup)
client.dids.delete.sip_uri(sipuri)
client.dids.delete.static_member(member, queue)
client.dids.delete.time_condition(timecondition)

Get

client.dids.get.callbacks(callback=None)
client.dids.get.caller_id_filtering(filtering=None)
client.dids.get.did_countries(international_type, country_id=None)
client.dids.get.carriers(carrier=None)
client.dids.get.dids_can(province, ratecenter=None)
client.dids.get.dids_info(client=None, did=None)
client.dids.get.dids_international_geographic(country_id)
client.dids.get.dids_international_national(country_id)
client.dids.get.dids_international_toll_free(country_id)
client.dids.get.dids_usa(state, ratecenter=None)
client.dids.get.disas(disa=None)
client.dids.get.forwardings(forwarding=None)
client.dids.get.international_types(international_type=None)
client.dids.get.ivrs(ivr=None)
client.dids.get.join_when_empty_types(join_type=None)
client.dids.get.phonebook(phonebook=None, name=None)
client.dids.get.portability(did)
client.dids.get.provinces()
client.dids.get.queues(queue=None)
client.dids.get.rate_centers_can(province)
client.dids.get.rate_centers_usa(state)
client.dids.get.recordings(recording=None)
client.dids.get.recording_file(recording)
client.dids.get.ring_groups(ringgroup=None)
client.dids.get.ring_strategies(strategy=None)
client.dids.get.sip_uris(sipuri=None)
client.dids.get.sms(**kwargs)
client.dids.get.states()
client.dids.get.static_members(queue, member=None)
client.dids.get.time_conditions(timecondition=None)
client.dids.get.voicemail_setups(voicemailsetup=None)
client.dids.get.voicemail_attachment_formats(email_attachment_format=None)

Order

client.dids.order.did(did, routing, pop, dialtime, cnam, billing_type, **kwargs)
client.dids.order.did_international_geographic(location_id, quantity, routing,
                                               pop, dialtime, cnam, billing_type, **kwargs)
client.dids.order.did_international_national(location_id, quantity, routing,
                                             pop, dialtime, cnam, billing_type, **kwargs)
client.dids.order.did_international_toll_free(location_id, quantity, routing, pop,
                                              dialtime, cnam, billing_type, **kwargs)
client.dids.order.did_virtual(digits, routing, pop, dialtime, cnam, billing_type, **kwargs)
client.dids.order.toll_free(did, routing, pop, dialtime, cnam, billing_type, **kwargs)
client.dids.order.vanity(did, routing, pop, dialtime, cnam, billing_type, carrier, **kwargs)

Search

client.dids.search.dids_can(search_type, query, province=None)
client.dids.search.dids_usa(search_type, query, state=None)
client.dids.search.toll_free_can_us(search_type=None, query=None)
client.dids.search.toll_free_usa(search_type=None, query=None)
client.dids.search.vanity(search_type, query)

Send

client.dids.send.sms(did, dst, message)
client.dids.send.mms(did, dst, message)

Set

client.dids.set.callback(description, number, delay_before, response_timeout, digit_timeout, **kwargs)
client.dids.set.caller_id_filtering(callerid, did, routing, **kwargs)
client.dids.set.did_billing_type(did, billing_type)
client.dids.set.did_info(did, routing, pop, dialtime, cnam, billing_type, **kwargs)
client.dids.set.did_pop(did, pop)
client.dids.set.did_routing(did, routing)
client.dids.set.did_voicemail(did, voicemail=None)
client.dids.set.disa(name, pin, digit_timeout, **kwargs)
client.dids.set.forwarding(phone_number, **kwargs)
client.dids.set.ivr(name, recording, timeout, language, voicemailsetup, choices, ivr=None)
client.dids.set.phonebook(name, number, **kwargs)
client.dids.set.queue(queue_name, queue_number, queue_language, priority_weight, report_hold_time_agent,
                      join_when_empty, leave_when_empty, ring_strategy, ring_inuse, **kwargs)
client.dids.set.recording(file, name, recording=None)
client.dids.set.ring_group(name, members, voicemail, **kwargs)
client.dids.set.sip_uri(uri, **kwargs)
client.dids.set.sms(did, enable, **kwargs)
client.dids.set.static_member(queue, member_name, priority, **kwargs)
client.dids.set.time_condition(name, routing_match, routing_nomatch, starthour, startminute,
                               endhour, endminute, weekdaystart, weekdayend, timecondition=None)

Unconnect

client.dids.unconnect.did(did)

Fax

Cancel

client.fax.cancel.fax_number(fax_id, test=None)

Delete

client.fax.delete.fax_message(fax_id, test=None)
client.fax.delete.email_to_fax(fax_id, test=None)
client.fax.delete.fax_folder(folder_id, test=None)

Get

client.fax.get.fax_provinces(province=None)
client.fax.get.fax_states(state=None)
client.fax.get.fax_rate_centers_can(province)
client.fax.get.fax_rate_centers_usa(state)
client.fax.get.fax_numbers_info(did=None)
client.fax.get.fax_numbers_portability(did)
client.fax.get.fax_messages(**kwargs)
client.fax.get.fax_message_pdf(fax_id)
client.fax.get.fax_folders()
client.fax.get.email_to_fax(fax_id=None)

Mail

client.fax.mail.fax_message_pdf(fax_id, email)

Move

client.fax.move_fax_message(fax_id, folder_id, test=None)

Order

client.fax.order.fax_number(location, quantity, **kwargs)

Set

client.fax.search.fax_area_code_can(area_code)
client.fax.search.fax_area_code_usa(area_code)

Send

client.fax.send.fax_message(to_number, from_name, from_number, file, **kwargs)

Set

client.fax.set.fax_folder(name, **kwargs)
client.fax.set.email_to_fax(auth_email, from_number_id, security_code, **kwargs)
client.fax.set.fax_number_info(did, **kwargs)
client.fax.set.fax_number_email(did, **kwargs)
client.fax.set.fax_number_url_callback(did, **kwargs)

Voicemail

Create

client.voicemail.create.voicemail(digits, name, password, skip_password, attach_message, delete_message,
                                  say_time, timezone, say_callerid, play_instructions, language, **kwargs)

Delete

client.voicemail.delete.messages(mailbox, **kwargs)
client.voicemail.delete.voicemail(mailbox)

Get

client.voicemail.get.play_instructions(play_instructions=None)
client.voicemail.get.timezones(timezone=None)
client.voicemail.get.voicemails(mailbox=None)
client.voicemail.get.voicemail_folders(folder=None)
client.voicemail.get.voicemail_message_file(mailbox, folder, message_num)
client.voicemail.get.voicemail_messages(mailbox, **kwargs)

Mark

client.voicemail.mark.listened_voicemail_message(mailbox, folder, message_num, listened)
client.voicemail.mark.urgent_voicemail_message(mailbox, folder, message_num, urgent)

Move

client.voicemail.move.folder_voicemail_message(mailbox, folder, message_num, new_folder)

Send

client.voicemail.send.voicemail_email(mailbox, folder, message_num, email_address)

Set

client.voicemail.set.voicemail(mailbox, name, password, skip_password, attach_message, delete_message,
                               say_time, timezone, say_callerid, play_instructions, language, **kwargs)

Contributing

To run tests:
- Install Python 3.7 via pyenv
- Set up pipenv
- Create a .env file in the root with credentials for a VoIP.ms account:
```
VOIPMS_USERNAME=
VOIPMS_PASSWORD=
```
- Run make init and make test
To deploy a new version:
- Add release notes to README.md
- Increment version
- Commit
- Tag
- Push with tags
- make clean
- make build
- make deploy

Support

If you are having issues, please let us know or submit a pull request.

License

The project is licensed under the MIT License.

Special Thanks

I was highly inspired by the mailchim3 API at https://github.com/charlesthk/python-mailchimp/. Thanks for your nice code layout!

4doom4 / python-voipms

readme

python-voipms

Getting Started

Installation

History

Initialization

Examples

API Structure

General

Get

Accounts

Create

Delete

Get

Set

Calls

Get

Clients

Add

Get

Set

Dids

Back_order

Cancel

Connect

Delete

Get

Order

Search

Send

Set

Unconnect

Fax

Cancel

Delete

Get

Mail

Move

Order

Set

Send

Set

Voicemail

Create

Delete

Get

Mark

Move

Send

Set

Contributing

Support

License

Special Thanks