UserVoice Python SDK

UserVoice SDK is now packaged in a PyPI library (library & the source). This document illustrates its usage with installation instructions and a few examples just to get you quickly started.

Install the module from PyPI

Install the uservoice Python module from PyPI:

1

pip install uservoice

or download the latest release from PyPI, unpack it and use the setup.py method:

1
2

cd uservoice-vX.Y.Z
python setup.py install

Ready to go! Let’s see what we can do with this.

Creating a new API client

For creating a new API client you need to do a few things. First, get your API KEY and API SECRET from UserVoice Admin Console and pass them as parameters to the client like this:

1
2
3
4
5
6
7
8
9

import uservoice

SUBDOMAIN_NAME = 'uservoice'
API_KEY = 'oQt2BaunWNuainc8BvZpAm'
API_SECRET = '3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2'
SSO_KEY = '982c88f2df72572859e8e23423eg87ed'
URL = 'http://localhost:4567/'

client = uservoice.Client(SUBDOMAIN_NAME, API_KEY, API_SECRET, callback=URL)

Now we have an API client that we can use to connect Helpdesk API.

Post a new ticket

Making requests using the client follow the format client.method(path, hash-params). In the first example we post a new ticket, which is possible if you have the helpdesk service.

1
2
3
4
5
6
7
8
9

# Post a new ticket to your helpdesk from sidson@example.com
question = client.post("/api/v1/tickets.json", {
    'email': 'sidson@example.com',
    'ticket': {
        'subject': 'Python SDK',
        'message': "I'm wondering if you would have any OAuth example for Python?\n\n"+
                   "Thanks,\n\nSidson"
    }
})['ticket']

Post a suggestion using an access token

Acting on behalf of the user lets you leave out the email parameter from the previous example as well as access to user-requiring API calls. In the following example we post a new suggestion in your first forum. You need feedback service for this example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Login as man.with.only.answers@example.com and retrieve an access token
with client.login_as('man.with.only.answers@example.com') as access_token:
    # Get the first forum id for the example which access_token has access to
    forum_id = access_token.get_collection('/api/v1/forums?sort=newest', limit=1)[0]['id']

    # Make the request using the access token
    suggestion = access_token.post("/api/v1/forums/"+str(forum_id)+"/suggestions.json", {
        'suggestion': {
            'title': 'Color the left navbar to green'
        }
    })['suggestion']

    user = access_token.get("/api/v1/users/current.json")['user']

    print "{name} created suggestion: {url}".format(
      name=user['name'],
      url=suggestion['url'])
    # Prints: Anonymous created suggestion: http://.....

Get the access token of the account owner and post responses

To respond to the ticket, you need to log in as an admin (or owner).

1
2
3
4
5
6
7
8
9
10

# This logs in as the first owner of the account
with client.login_as_owner() as owner:
    posted_response = owner.post("/api/v1/tickets/{id}/ticket_messages.json".format(id=question['id']), {
        'ticket_message': {
            'text': "Hi " + question['contact']['name'].capitalize() + "!\n\n" +
                    "We sure do! See the installation instructions and a few example API calls " +
                    "here: http://developer.uservoice.com/docs/api/python-sdk\n\n" +
                    "Best regards,\n\nRaimo Tuisku\nDeveloper"
        }
    })

Getting a list of suggestions

You maybe noticed the use of get_collection when getting the first forum ID. Whenever you need to fetch paginated results (like all suggestions), you can use our lazy-loading collection.

1
2
3
4
5
6
7
8
9

# Creates a lazy-loading collection object but makes no requests to the API yet.
suggestions = client.get_collection("/api/v1/suggestions?sort=newest")

# Loads the first page (at most 100 records) of suggestions and reads the count.
print "Total suggestions: {total}".format(total=len(suggestions))

# Loops through all the suggestions and loads new pages as necessary.
for suggestion in suggestions:
    print "{title}: {url}".format(**suggestion)

Log your users into your Widget using SSO

If your site has both authenticated users and the UserVoice Widget installed, you should definitely pass the email of your logged-in user to the UserVoice Widget so that users don’t have to type it again in your site.

Generating an SSO token should be done on the server side, as you should never reveal your API SECRET to anyone. Here’s how you do it:

1
2
3
4

  def current_sso_token():
      uservoice.generate_sso_token(SUBDOMAIN_NAME, SSO_KEY, {
          'email': current_user.email
      }, 300) # Leaving this out sets the expiry time to 5 minutes = 300 seconds.

Now you can pass the SSO token to the UserVoice Widget JavaScript snippet. Make sure the aforementioned method current_sso_token() can be called from there.

1
2
3
4
5
6
7
8
9
10
11

<script type="text/javascript">
  var uvOptions = {
    params: { sso: '{% current_sso_token() %}' } // Example syntax in Jinja
  };
  (function() {
    var uv = document.createElement('script'); uv.type = 'text/javascript'; uv.async = true;
    uv.src = ('https:' == document.location.protocol ? 'https://' : 'http://') +
      'widget.uservoice.com/yourwidgetcodetobehere.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(uv, s);
  })();
</script>

That’s all! Now your users should be able to leave feedback and post tickets right away.

Associating your users with their UserVoice profiles

Connecting your users with their UserVoice profiles is possible by following a procedure called 3-Legged OAuth. The steps required to do this are explained below.

1. Provide a link or redirect user to /authorize from system X.

When you want to connect your current user to his or her UserVoice profile, redirect the browser to the authorization url like this:

1
2

# Redirects user to the UserVoice authorization dialog.
redirect_to client.authorize_url()

Providing a direct link is another way to do the trick:

1

link_to 'Connect UserVoice', client.authorize_url()

2. User is asked to log in and give X permission to access information in UserVoice.

The authorization dialog will look like this:

3. UserVoice redirects user back to system X and passes an oauth verifier

UserVoice will pass a verification code back to your system, which you can use to request an access token for the user, so you know which profile in UserVoice is owned by your currently logged-in user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Getting oauth verifier as a GET parameter
if params['oauth_verifier']:
    try:
        # Get access token for the user
        access_token = client.login_with_verifier(params['oauth_verifier'])

        # Persist the access token in the database for later use
        current_user.update(uservoice_token=access_token.token,
                            uservoice_secret=access_token.secret)
    except uservoice.Unauthorized:
        # false/old verifier, present error
        flash['error'] = "Access denied"

    redirect_to '/'

4. System X makes API calls to UserVoice using the access token.

Now whenever you need to, you can make calls on behalf of the user whom you verified. Just use the access token you got in exchange for the verifier.

1
2
3
4
5
6
7
8
9
10

try:
    # Use the previously saved access token. Makes zero requests!
    access_token = client.login_with_access_token(current_user.uservoice_token,
                                                  current_user.uservoice_secret)
    # Get current user
    user_attributes = access_token.get("/api/v1/users/current.json")
    print user_attributes['email']
    # Prints: man.with.only.answers@example.com
except uservoice.Unauthorized:
    # Tried to do something unauthorized

Raimo Tuisku (twitter: @raimo_t)

Didn’t find what you’re looking for?

Check out the UserVoice Help Center for more documentation.

Explore the Help Center