UserVoice C# SDK

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

Install UserVoice library from NuGet

The UserVoice C# library can be installed using NuGet, the package manager. Go to NuGet Gallery | UserVoice and follow the instructions in Visual Studio and run this command in Package Manager Console.

1

Install-Package UserVoice

If you are using the NuGet.exe command line tool (in Mono, for exampe), simply run the following in your project:

1

NuGet.exe install UserVoice

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
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

using System;

namespace UserVoice
{
    class Example
    {
        static string SUBDOMAIN_NAME = "uservoice";
        static string API_KEY = "oQt2BaunWNuainc8BvZpAm";
        static string API_SECRET = "3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2";
        static string SSO_KEY = "982c88f2df72572859e8e23423eg87ed";
        static string CALLBACK = "http://localhost:4567/";

        public Example()
        {
            var client = new UserVoice.Client(SUBDOMAIN_NAME, API_KEY, API_SECRET, CALLBACK);

            // ...
        }
        public static void Main()
        {
            new Example();
        }
    }
}

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, 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
10
11
12
13

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

Console.WriteLine(string.Format("{0} posted ticket: {1}", question["contact"], question["url"]));
// Prints: sidson posted ticket: http://.....

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 to have the feedback service for this example.

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

// Login as man.with.only.answers@example.com and retrieve an access token
var accessToken = client.LoginAs("man.with.only.answers@example.com");

// Get the first forum id for the example which accessToken has access to
var forumId = accessToken.GetCollection("/api/v1/forums?sort=newest", 1)[0]["id"];

// Post the suggestion using the access token
var suggestion = accessToken.Post("/api/v1/forums/" + forumId + "/suggestions", new {
    suggestion = new {
        title = "Color the left navbar to green"
    }
})["suggestion"];

var user = accessToken.Get("/api/v1/users/current")["user"];

Console.WriteLine(string.Format("{0} created suggestion: {1}", user["name"], 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
11
12
13
14
15
16

// This logs in as the first owner of the account
var owner = client.LoginAsOwner();

var contactName = (string) question["contact"].Value<string>("name");
var posted_response = owner.Post("/api/v1/tickets/" + question["id"] + "/ticket_messages", new {
    ticket_message = new {
        text = "Hi " + char.ToUpper(contactName[0]) + contactName.Substring(1) + "!\n\n" +
               "We sure do! See the installation instructions and a few example API calls " +
               "here: http://developer.uservoice.com/docs/api/php-sdk\n\n" +
               "Best regards,\n\nRaimo Tuisku\nDeveloper"
    }
})["ticket"];
Console.WriteLine(string.Format("{0} posted response to: {1}",
                  posted_response["messages"][0]["sender"]["name"],
                  posted_response["url"]));
// Prints: Raimo posted response to: http://.....·

Getting a list of suggestions

You maybe noticed the use of GetCollection 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
10

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

// Loads the first page (at most 100 records) of suggestions and reads the count.
Console.WriteLine("Total suggestions: " + suggestions.Count);

// Loops through all the suggestions and loads new pages as necessary.
foreach (var suggestion in suggestions) {
    Console.WriteLine(string.Format("{0}: {1}", suggestion["title"], suggestion["url"]));
}

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
5
6

string currentSSOToken()
{
    return UserVoice.SSO.generateToken(SUBDOMAIN_NAME, SSO_KEY, new {
        email = CurrentUser().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 currentSSOToken() can be called from there.

1
2
3
4
5
6
7
8
9
10
11

<script type="text/javascript">
  var uvOptions = {
    params: { sso: '<%= currentSSOToken(); ?>' }
  };
  (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.
Response.Redirect(client.AuthorizeURL());

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

1

Html.ActionLink("Connect UserVoice", client.AuthorizeURL());

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
15
16
17
18
19

// Getting oauth verifier as a GET parameter
var verifier = Request.QueryString("oauth_verifier").ToString();

if (verifier.Length > 0) {
    try {
        // Get access token for the user
        var accessToken = client.LoginWithVerifier(verifier);


        // Persist the access token in the database for later use
        var user = CurrentUser(); // CurrentUser() returns a persistable object
        user.UservoiceToken = accessToken.Token;
        user.UservoiceSecret = accessToken.Secret;
        user.Save();
    } catch (UserVoice.Unauthorized ua) {
        // false/old verifier, present error
    }
    Response.Redirect("/");
}

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
11

try {
    // Use the previously saved access token. Makes zero requests!
    var accessToken = client.LoginWithAccessToken(CurrentUser().UservoiceToken,
                                                  CurrentUser().UservoiceSecret);
    // Get current user
    var user = accessToken.Get("/api/v1/users/current.json")["user"];
    Console.WriteLine(user["email"]);
    // Prints: man.with.only.answers@example.com
} catch (UserVoice.Unauthorized ua) {
    // 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