Client for Vumi Go’s JSON-RPC based account, conversations, channel and routing API.

campaigns()¶

Return a list of campaigns accessible by the account.

Note: The server-side implementation of this API method is a stub. It always returns a single campaign whose name is ‘Your Campaign’ and whose key is the account key.

channels(campaign_id)¶

Return a list of channels for the campaign.

Parameters:	campaign_id (str) – The campaign or account id.

conversations(campaign_id)¶

Return a list of conversations for the campaign.

Parameters:	campaign_id (str) – The campaign or account id.

routers(campaign_id)¶

Return a list of routers for the campaign.

Parameters:	campaign_id (str) – The campaign or account id.

routing_entries(campaign_id)¶

Return a list of routing entries for the campaign.

Parameters:	campaign_id (str) – The campaign or account id.

routing_table(campaign_id)¶

Return the complete routing table for the campaign.

Parameters:	campaign_id (str) – The campaign or account id.

update_routing_table(campaign_id, routing_table)¶

Update the routing table for the campaign.

Parameters:	campaign_id (str) – The campaign or account id. routing_table (dict) – The complete new routing table.

Client for Vumi Go’s contacts API.

contacts(start_cursor=None)¶

Retrieve all contacts.

This uses the API’s paginated contact download.

Parameters:	start_cursor – An optional parameter that declares the cursor to start fetching the contacts from.
Returns:	An iterator over all contacts.

create_contact(contact_data)¶

Create a contact.

Parameters:	contact_data (dict) – Data for new contact.

create_group(group_data)¶

Create a group.

Parameters:	group_data (dict) – Data for new group.

delete_contact(contact_key)¶

Delete a contact.

Parameters:	contact_key (str) – Key for the contact to delete.

delete_group(group_key)¶

Delete a group.

Parameters:	group_key (str) – Key for the group to delete.

get_contact(*args, **kw)¶

Get a contact. May either be called as .get_contact(contact_key) to get a contact from its key, or .get_contact(field=value), to get the contact from an address field field having a value value.

Contact key example:

contact = api.get_contact(‘abcdef123456’)

Field/value example:

contact = api.get_contact(msisdn=’+12345’)

Parameters:	contact_key (str) – Key for the contact to get. field (str) – field is the address field that is searched on (e.g. msisdn , twitter_handle). The value of field is the value to search for (e.g. +12345, @foobar`).

get_group(group_key)¶

Get a group

Parameters:	group_key (str) – Key for the group to get

group_contacts(group_key, start_cursor=None)¶

Retrieve all group contacts.

This uses the API’s paginated contact download.

Parameters:	group_key (str) – Key for the group to query. start_cursor – An optional parameter that declares the cursor to start fetching the contacts from.
Returns:	An iterator over all group contacts.

update_contact(contact_key, update_data)¶

Update a contact.

Parameters:	contact_key (str) – Key for the contact to update. update_data (dict) – Fields to modify.

update_group(group_key, update_data)¶

Update a group.

Parameters:	group_key (str) – Key for the group to update. update_data (str) – Fields to modify.

A helper for sending text messages and firing metrics via Vumi Go’s HTTP API.

fire_metric(metric, value, agg='last')¶

Fire a value for a metric.

Parameters:	metric (str) – Name of the metric to fire. value (float) – Value for the metric. agg (str) – Aggregation type. Defaults to 'last'. Other allowed values are 'sum', 'avg', 'max' and 'min'.

Note that metrics can also be fired via the metrics API. See go_http.metrics.MetricsApiClient.fire().

send_text(to_addr, content, session_event=None)¶

Send a text message to an address.

Parameters:	to_addr (str) – Address to send to. content (str) – Text to send. session_event (str) – The session event for session-based messaging channels (e.g. USSD). May be one of ‘new’, ‘resume’ or ‘close’. Optional.

send_voice(to_addr, content, speech_url=None, wait_for=None, session_event=None)¶

Send a voice message to an address.

Parameters:

to_addr (str) – Address to send to. content (str) – Text to send. If speech_url is not provided, a text-to-speech engine is used to generate a voice message from this text. If speech_url is provided, this text is ignored by voice messaging channels, but may still be used by non-voice channels that process the message. speech_url (str) – A URL to a voice file containing the voice message to sent. If not given, a voice message is generated from content using a text-to-speech engine. Optional. wait_for (str) – By default the Vumi voice connections send a response to a message as soon as a key is pressed by the person the call is with. The wait_for option allows specifying a character to wait for before a response is returned. For example, without wait_for pressing ‘123#’ on the phone would result in four response messages containing ‘1’, ‘2’, ‘3’ and ‘#’ respectively. If wait_for='#' was set, pressing ‘123#’ would result in a single response message containing ‘123’. Optional. session_event (str) – The session event. May be one of ‘new’, ‘resume’ or ‘close’. ‘new’ initiates a new call. ‘resume’ continues an existing call. ‘close’ ends an existing call. The default of None is equivalent to ‘resume’.

Client for Vumi Go’s metrics API.

fire(metrics)¶

Fire metrics.

Parameters:	metrics (dict) – A mapping of metric names to floating point metric values.

When metrics are fired they must specify an aggregator. The aggregation method is determined by the suffix of the metric name. For example, foo.last fires a metric that uses the last aggregation method.

If a metric name does not end in a valid aggregator name, firing the set of metrics will fail.

The available aggregators are:

Average:	avg. Aggregates by averaging the values in each time period.
Sum:	sum. Aggregates by summing all the values in each time period.
Maximum:	max. Aggregates by choosing the maximum value in each time period.
Minimum:	min. Aggregates by choosing the minimum value in each time period.
Last:	last. Aggregates by choosing the last value in each time period.

Note that metrics can also be fired via an HTTP conversation API. See go_http.send.HttpApiSender.fire_metric().

get_metric(metric, start, interval, nulls, end=None)¶

Get a metric.

Parameters:	metric (str) – Metric name. start (str) – How far back to get metrics from (e.g. -30d). interval (str) – Bucket size for grouping (e.g. 1d). nulls (str) – How nulls should be handled (e.g. omit). end (str) – When to get metrics until (e.g. -30d).

Client for Vumi Go’s opt out API.

count()¶

Return a count of the total number of opt out records.

Returns:	The total number of opt outs (an integer).

Example:

>>> client.count()
215

delete_optout(address_type, address)¶

Remove an out opt record.

Parameters:	address_type (str) – Type of address, e.g. msisdn. address (str) – The address to remove the opt out record for, e.g. +271235678.
Returns:	The deleted opt out record (a dict) or None if the API returned an HTTP 404 reponse.

Example:

>>> client.delete_optout('msisdn', '+12345')
{
    u'created_at': u'2015-11-10 20:33:03.742409',
    u'message': None,
    u'user_account': u'fxxxeee',
}

get_optout(address_type, address)¶

Retrieve an opt out record.

Parameters:	address_type (str) – Type of address, e.g. msisdn. address (str) – The address to retrieve an opt out for, e.g. +271235678.
Returns:	The opt out record (a dict) or None if the API returned a 404 HTTP response.

Example:

>>> client.get_optout('msisdn', '+12345')
{
    u'created_at': u'2015-11-10 20:33:03.742409',
    u'message': None,
    u'user_account': u'fxxxeee',
}

set_optout(address_type, address)¶

Register an address as having opted out.

Parameters:	address_type (str) – Type of address, e.g. msisdn. address (str) – The address to store an opt out for, e.g. +271235678.
Returns:	The created opt out record (a dict).

Example:

>>> client.set_optout('msisdn', '+12345')
{
    u'created_at': u'2015-11-10 20:33:03.742409',
    u'message': None,
    u'user_account': u'fxxxeee',
}