API Documentation

Accounts

class vivialconnect.resources.account.Account(attributes=None, prefix_options=None)

The Account resource is used for managing accounts in the API.

Account properties

Field	Description
id	Unique identifier of the account object.
date_created	Creation date (UTC) of the account in ISO 8601 format.
date_modified	Last modification date (UTC) of the account in ISO 8601 format.
account_id	Unique identifier of the parent account. (Null if the account is primary.)
company_name	Primary account name as it is displayed to users (for example, the name of your company).

Example request to retrieve a billing status for account id 12345:

from vivialconnect import Resource, Account

Resource.api_key = ""
Resource.api_secret = ""
Resource.api_account_id = "12345"

def billing_status(account_id=None):
    status = Account.billing_status(account_id=account_id)
    print(status)

billing_status(12345)

classmethod billing_status(account_id=None)

Get current account status for free trial.

Parameters:account_id (int.) – An account id. Returns:A free trial status.

Users

class vivialconnect.resources.user.User(attributes=None, prefix_options=None)

Use the User resource to manage users and user passwords in the API.

User properties

Field	Description
id	Unique identifier of the user object.
date_created	Creation date (UTC) of the user in ISO 8601 format.
date_modified	Last modification date (UTC) of the user in ISO 8601 format.
account_id	Unique identifier of the account that this user is part of.
username	User’s username for logging in to the account. Max. length: 128 characters.
first_name	User’s first name. Max. length: 128 characters.
last_name	User’s last name. Max. length: 128 characters.
email	User’s email address. Max. length: 128 characters.

Example request to retrieve a list of users accociated with the account id 12345:

from vivialconnect import Resource, User

Resource.api_key = ""
Resource.api_secret = ""
Resource.api_account_id = "12345"

def list_users():
    users = User.find()
    for user in users:
        print(user.id, user.first_name, user.last_name)

list_users()

Message and Attachment

class vivialconnect.resources.message.Attachment(attributes=None, prefix_options=None)

Use the Attachment resource to list, count, and view information about media attachments for individual text messages in your account.

Attachment properties

Field	Description
id	Unique identifier of the media attachment object.
date_created	Creation date (UTC) of the media attachment in ISO 8601 format.
date_modified	Last modification date (UTC) of the media attachment in ISO 8601 format.
account_id	Unique identifier of your account.
message_id	Unique identifier of the text message for the media attachment.
content_type	Mime-type of the media attachment.
size	Size of the media attachment in bytes.
file_name	File name of the media attachment.

class vivialconnect.resources.message.Message(attributes=None, prefix_options=None)

Use the Message resource to manage API activity related to text message entities.

Message properties

Field	Description
id	Unique identifier of the text message object.
date_created	Creation date (UTC) of the text message in ISO 8601 format.
date_modified	Last modification date (UTC) of the text message in ISO 8601 format.
account_id	Unique identifier of the account with the text message.
message_type	String identifying the type of inbound or outbound text message. Possible values: local_sms, tollfree_sms, or local_mms.
direction	Inbound/outbound direction of the text message, and if outbound, the nature of the text message initiation.
to_number	Phone number that received the text message. Uses E.164 format (+country code +phone number). For US, the format will be +1xxxyyyzzzz.
from_number	For inbound messages, the external phone number that sent the text message. For outbound messages, the associated phone number in your account that sent the text message.
sent	For inbound messages, the UTC timestamp the text message was received. For outbound messages, the UTC timestamp the text message was sent.
body	Text body of the text message. Max. length: 1,600 characters.
num_media	Number of media attachments for the text message.
num_segments	Number of segments that make up the message. Note: Does not affect pricing.
status	Status of the message (for example, sent).
error_code	Error code, if any, for the message. Default value: null (message was delivered successfully).
error_message	Error code message for error_code as it is displayed to users.
price	Amount billed for the message, in the currency associated with the account.
price_currency	Currency in which price is measured in ISO 4127 format. For US, the currency will be USD.
sms_configuration_id	Unique identifier of the message status callback configuration to be used to handle message status callbacks.

Example request to retreive a list of messages from your account, sorted by most recent:

from vivialconnect import Resource, Message

Resource.api_key = ""
Resource.api_secret = ""
Resource.api_account_id = "12345"

def list_messages():
    count = Message.count()
    messages = Message.find(order="id desc")
    for message in messages:
        print(message.id, message.to_number,
              message.from_number, message.body)

list_messages()

attachment(id, **kwargs)

Use this method to view information about a single media attachment for a message in your account.

Parameters:id (int.) – Message id. Returns:Resource – a Resource object.

attachments(**kwargs)

Use this method to view the list of attachments for a message in your account.

Parameters:**kwargs – Any keyword arguments used for forming a query. Returns:list – a list of Resource objects.

attachments_count(opts=None, **kwargs)

Use this method to view the total number of media attachments for a message in your account.

classmethod bulk_messages(bulk_id)

Returns a list of Messages that are members of the the bulk send job identified by bulk_id

classmethod bulks()

Returns a list of all bulk send jobs.

send()

Sends a new message.

send_bulk()

Sends a message to multiples recipients.

This method uses to_numbers property instead of to_number for sending to multiples recipients. The values must be a list of numbers in E.164 format (+(country code)(phone number)).

If to_numbers is not provided a ValueError exception will be raised.

Number

class vivialconnect.resources.number.Number(attributes=None, prefix_options=None)

The Number resource provides functionality to work with account associated and available phone numbers.

Purchasing a Phone Number

Before you can send or receive text messages using Vivial Connect, you must purchase at least one phone number and associate it with your account. The API lets you choose from a list of available US local or toll-free numbers. When you query this list to find an available number that meets your needs, you can tailor your search to target specific criteria, including:

• the city, US state, area code, or ZIP code where the number is located
• a number pattern you specify containing wildcards for individual digits
• an alphanumeric pattern you specify (for choosing numbers that spell a word)

Available numbers properties

Field	Description
name	Associated phone number as it is displayed to users. Default format: Friendly national format: (xxx) yyy-zzzz.
phone_number	Available phone number in E.164 format (+country code +phone number). For US numbers, the format will be +1xxxyyyzzzz.
phone_number_type	Type of available phone number. Possible values: ‘local’ or ‘tollfree’.
city	City where the available phone number is located.
region	Two-letter US state abbreviation where the available phone number is located.
lata	Local address and transport area (LATA) where the available phone number is located.
rate_center	LATA rate center where the available phone number is located. Usually the same as city.

Associated numbers properties

Field	Description
id	Unique identifier of the phone number object.
date_created	Creation date (UTC) of the phone number in ISO 8601 format.
date_modified	Last modification date (UTC) of the phone number in ISO 8601 format.
account_id	Unique identifier of the account with the phone number.
name	Associated phone number as it is displayed to users. Default format: Friendly national format: (xxx) yyy-zzzz.
phone_number	Associated phone number in E.164 format (+country code +phone number). For US numbers, the format will be +1xxxyyyzzzz.
phone_number_type	Type of associated phone number. Possible values: ‘local’ or ‘tollfree’.
status_text_url	URL to receive status requests for messages sent via the API using this associated phone number. Max. length: 256 characters.
sms_configuration_id	Unique identifier of the message status callback configuration to be used to handle SMS messages sent to the associated number.
incoming_text_url	URL for receiving SMS messages to the associated phone number. Max. length: 256 characters.
incoming_text_method	HTTP method used for the incoming_text_url requests. Max. length: 8 characters. Possible values: GET or POST. Default value: POST.
incoming_text_fallback_url	URL for receiving SMS messages if incoming_text_url fails. Only valid if you provide a value for the incoming_text_url parameter. Max. length: 256 characters.
incoming_text_fallback_method	HTTP method used for incoming_text_fallback_url requests. Max. length: 8 characters. Possible values: GET or POST. Default value: POST.
capabilities	Set of boolean flags indicating the capabilities supported by the associated phone number.
city	City where the available phone number is located.
region	Two-letter US state abbreviation where the available phone number is located.
lata	Local address and transport area (LATA) where the available phone number is located.
rate_center	LATA rate center where the available phone number is located. Usually the same as city.

Example request to retrieve a list of associated numbers:

from vivialconnect import Resource, Number

Resource.api_key = ""
Resource.api_secret = ""
Resource.api_account_id = "12345"

def list_associated_numbers():
    numbers = Number.find()
    for number in numbers:
        print(number.id, number.name,
              number.phone_number_type,
              number.phone_number)

list_associated_numbers()

Example request to retrieve a list of available numbers:

from vivialconnect import Resource, Number

Resource.api_key = ""
Resource.api_secret = ""
Resource.api_account_id = "12345"

def list_available_numbers(country_code='US',
                           number_type='local',
                           area_code='913',
                           in_postal_code=None,
                           in_region=None,
                           limit=5):
    numbers = Number.available(
        country_code=country_code,
        number_type=number_type,
        area_code=area_code,
        in_postal_code=in_postal_code,
        in_region=in_region,
        limit=limit)
    for number in numbers:
        print(number.name,
              number.phone_number_type,
              number.phone_number)

list_available_numbers()

Example request to buy a new phone number:

from vivialconnect import Resource, Number

Resource.api_key = ""
Resource.api_secret = ""
Resource.api_account_id = "12345"

def buy_number(name=None,
               phone_number=None,
               area_code=None,
               phone_number_type='local'):
    number = Number()
    number.name = name
    number.phone_number = phone_number
    number.area_code = area_code
    number.phone_number_type = phone_number_type
    number.buy()

buy_number(name='(913) 259-7591',
           phone_number='+19132597591',
           area_code='913',
           phone_number_type='local')

classmethod available(opts=None, **kwargs)

Lists available phone numbers.

Parameters:

• opts (dict.) – Additional query params.
• **kwargs – You must specify exactly one of the following three keys: in_region, area_code, in_postal_code.

Returns:

Number – a list of available US local or toll-free phone numbers.

buy()

Purchases a new phone number.

buy_local()

Purchases a new local phone number.

Logs

class vivialconnect.resources.log.Log(attributes=None, prefix_options=None)

Returns the list of logs in your account.

Required Query Parameters

Field	Description
start_time	Start date and time. Format used is ISO 8601 as YYYYMMDDThhmmssZ , ISO 8601 format without - and :
end_time	End date and time. Format used is ISO 8601 as YYYYMMDDThhmmssZ , ISO 8601 format without - and :

Optional Query Parameters

Field	Description
log_type	The log type, as a string. log-types are typically of the form ITEM_TYPE.ACTION, where ITEM_TYPE is the type of item that was affected and ACTION is what happened to it. For example, message.queued. |
item_id	Unique id of item that was affected.
operator_id	Unique id of operator that caused this log.
limit	Used for pagination, number of log records to return.
start_key	Used for pagination, value of last_key from previous response.

classmethod get_aggregated_logs(start_time, end_time, aggregator_type='minutes', optional_query_parameters=None)

Returns the list of aggregated logs in your account.

Required Query Parameters

Field	Description
start_time	Start date and time. Format used is ISO 8601 as YYYYMMDDThhmmssZ , ISO 8601 format without - and :
end_time	End date and time. Format used is ISO 8601 as YYYYMMDDThhmmssZ , ISO 8601 format without - and :
aggregator_type	Default value: “minutes”. Valid values are: minutes, hours, days, months, years

Optional Query Parameters

Field	Description
log_type	The log type, as a string. log-types are typically of the form ITEM_TYPE.ACTION, where ITEM_TYPE is the type of item that was affected and ACTION is what happened to it. A valid list of log_ytpes: message.queued, message.undelivered, message.failed, message.received, webhook.error, number.purchased, number.released, user.login, user.login_success
operator_id	Unique id of operator that caused this log.
limit	Used for pagination, number of log records to return.
start_key	Used for pagination, value of last_key from previous response.

Resource

class vivialconnect.resources.resource.Resource(attributes=None, prefix_options=None)

This class represents a base Resource object.

classmethod create(attributes)

Creates and saves a resource with the given attributes.

Parameters:attributes (dict.) – A dictionary of attributes which represent this object. Returns:Resource – a newly created Resource object.

destroy()

Deletes Resource object from the server.

Raises:RequestorError: On any communications errors. ResourceError: On any other errors.

classmethod find(id_=None, path=None, **kwargs)

Find resources.

Parameters:

• id (int.) – A specific resource to retrieve.
• path (str.) – The path that resources will be fetched from.
• **kwargs – Any keyword arguments used for forming a query.

Returns:

Resource – a Resource object.

Raises:

RequestorError: On any communications errors. ResourceError: On any other errors.

classmethod find_first(path=None, **kwargs)

Find first available resource from the list.

Parameters:

• path (str.) – The path that resources will be fetched from.
• **kwargs – Any keyword arguments used for forming a query. Valid query keywords include: search, order, limit, page

Returns:

The first found resource from the list of returned resources, otherwise None.

Raises:

RequestorError: On any communications errors. ResourceError: On any other errors.

id

Value stored in the primary key

is_new()

Returns True if resource is new and have not been saved.

Returns:True if resource is new, False otherwise.

reload()

Reloads Resource object from the server.

Raises:RequestorError: On any communications errors. ResourceError: On any other errors.

save()

Saves Resource object to the server.

Returns:True on success, or throws an error. Raises:RequestorError: On any communications errors. ResourceError: On any other errors.

class vivialconnect.resources.resource.ResourceMeta

A metaclass for Resource objects.

This class provides a way for configuration of API properties (user, password, account_id, etc).

api_account_id

An API account id

api_base_url

An API base_url used for HMAC authentication

api_key

An API key used for HMAC authentication

api_secret

An API secret used for HMAC authentication

api_verify_request

Verify SSL certs

plural

The plural name of this object type

primary_key

Name of attribute that uniquely identies the resource

request_timeout

Request Timeout

singular

The singular name of this object type

Utility

class vivialconnect.common.util.Util

Various utility functions shipped with Vivial Connect Python API.

static camelize(word)

Convert a word from lower_with_underscores to CamelCase.

Parameters:word (str.) – The string to convert. Returns:str – the modified string.

static json_to_dict(jsonstr)

Parse the json into a dictionary of attributes.

Parameters:jsonstr (str.) – A JSON formatted string. Returns:str – the deserialized object.

static pluralize(singular)

Convert singular word to its plural form.

Parameters:singular (str.) – A word in its singular form. Returns:str – the word in its plural form.

static remove_root(data)

Removes root key from dictionary.

Parameters:data (dict.) – A dict to remove root key from. Returns:dict – a new dictionary without root key.

static singularize(plural)

Convert plural word to its singular form.

Parameters:plural (str.) – A word in its plural form. Returns:str – the word in its singular form.

static to_json(obj, root='object')

Convert a dictionary or list to an JSON string.

Parameters:obj – The object to serialize. Returns:str – a JSON string.

static to_query(query_params)

Convert a dictionary to url query parameters.

Parameters:query_params (dict.) – A dictionary of arguments. Returns:str – a string of query parameters.

static underscore(word)

Convert a word from CamelCase to lower_with_underscores.

Parameters:word (str.) – The string to convert. Returns:str – the modified string.

Errors

exception vivialconnect.common.error.BadRequest(message=None, http_status=None, http_body=None)

400 Bad Request

Raised if the client receives something and cannot handle it.

exception vivialconnect.common.error.ClientError(message=None, http_status=None, http_body=None)

4xx Base HTTP Error (401..499)

Baseclass for all 4xx exceptions.

exception vivialconnect.common.error.ConnectionError(message=None, http_status=None, http_body=None)

Network Connection Error

This error is raised if Vivial Connect API client detects a connection error.

exception vivialconnect.common.error.ForbiddenAccess(message=None, http_status=None, http_body=None)

403 Forbidden

Raised if the user doesn’t have the permission for the requested resource.

exception vivialconnect.common.error.MethodNotAllowed(message=None, http_status=None, http_body=None)

405 Method Not Allowed

Raised if the server does not handle method used to access resource. For example POST if the resource is view only.

exception vivialconnect.common.error.RateLimit(message=None, http_status=None, http_body=None)

429 Rate Limit

Raised if rate limit reached.

exception vivialconnect.common.error.Redirection(message=None, http_status=None, http_body=None, url=None, headers=None)

3xx Redirection Error

Raised for all HTTP redirects.

exception vivialconnect.common.error.RequestorError(message=None, http_status=None, http_body=None)

Base Requestor Error

exception vivialconnect.common.error.ResourceConflict(message=None, http_status=None, http_body=None)

409 Resource Conflict

Raised if there is resource conflict.

exception vivialconnect.common.error.ResourceError(message=None)

Generic Resource Error

Raised if there is an error while processing response JSON data.

exception vivialconnect.common.error.ResourceInvalid(message=None, http_status=None, http_body=None)

422 Resource Invalid

Raised if a resource is invalid.

exception vivialconnect.common.error.ResourceNotFound(message=None, http_status=None, http_body=None)

404 Resource Not Found

Raised if a resource does not exist.

exception vivialconnect.common.error.ServerError(message=None, http_status=None, http_body=None)

Any 5xx HTTP Error 5xx (500..599)

Raised if an internal server error occurred.

exception vivialconnect.common.error.UnauthorizedAccess(message=None, http_status=None, http_body=None)

401 Unauthorized

Raised if the user is not authorized to access remote resource.