API documentation

Authenticator object

class yampy.Authenticator(client_id, client_secret, oauth_dialog_url=None, oauth_base_url=None)

Responsible for authenticating users against the Yammer API.

The OAuth2 authentication process involves several steps:

1. Send the user to the URL returned by authorization_url. They can use this page to grant your application access to their account.
2. Yammer redirects them to the redirect_uri you provided with a code that can be exchanged for an access token.
3. Exchange the code for an access token using the fetch_access_token method.

__init__(client_id, client_secret, oauth_dialog_url=None, oauth_base_url=None)

Initializes a new Authenticator. The client_id and client_secret identify your application, you acquire them when registering your application with Yammer. See http://www.yammer.com/client_applications

Keyword arguments can be used to modify the URLs generated in this class, e.g. to avoid hitting the live API from a client application’s test suite. Pass None to use the default URLs.

• oauth_dialog_url – The URL the user must visit to authorize the application. Used by the authorization_url method.
• oauth_base_url – The base URL for OAuth API requests, e.g. token exchange. Used by fetch_access_data or fetch_access_token.

authorization_url(redirect_uri)

Returns the URL the user needs to visit to grant your application access to their Yammer account. When they are done they will be redirected to the redirect_uri you provide with a code that can be exchanged for an access token.

fetch_access_data(code)

Returns the complete response from the Yammer API access token request. This is a dict with “user”, “network” and “access_token” keys.

You can access the token itself as: response.access_token.token

If you only intend to make use of the token, you can use the fetch_access_token method instead for convenience.

fetch_access_token(code)

Convenience method to exchange a code for an access token, discarding the other user and network data that the Yammer API returns with the access token.

If you require user and network information, you should use the fetch_access_data method instead.

Yammer object

class yampy.Yammer(access_token=None, base_url=None)

Main entry point for accessing the Yammer API.

Essentially this is just a Factory class that provides instances of various classes that interact directly with the API. For example, the messages method returns a MessagesAPI object.

__init__(access_token=None, base_url=None)

Initialize a new Yammer instance.

• access_token identifies the current user. You can acquire an access token using an yampy.Authenticator.
• base_url defaults to the live Yammer API. Provide a different base URL to make requests against some other server, e.g. a fake in your application’s test suite.

client

Returns a yampy.client.Client object which can be used to make HTTP requests to any of the Yammer REST API endpoints.

You should use this if there isn’t a more specific interface available for the request you want to make, e.g. if you want to request users you should use the users method instead of the client method.

messages

Returns a yampy.apis.MessagesAPI object which can be used to call the Yammer API’s message-related endpoints.

users

Returns a yampy.apis.UsersAPI object which can be used to call the Yammer API’s user-related endpoints.

MessagesAPI object

class yampy.apis.MessagesAPI(client)

Provides an interface for accessing the message related endpoints of the Yammer API. You should not instantiate this class directly; use the yampy.Yammer.messages() method instead.

__init__(client)

Initializes a new MessagesAPI that will use the given client object to make HTTP requests.

all(older_than=None, newer_than=None, limit=None, threaded=None)

Returns public messages from the current user’s network.

Customize the response using the keyword arguments:

• older_than – Only fetch messages older than this message ID.
• newer_than – Only fetch messages newer than this message ID.
• limit – Only fetch this many messages.
• threaded – Set to True to only receive the first message of each thread, or to "extended" to recieve the first and two newest messages from each thread.

create(body, group_id=None, replied_to_id=None, direct_to_id=None, topics=[], broadcast=None, open_graph_object={})

Posts a new message to Yammer. Returns the new message in the same format as the various message listing methods (all(), sent(), etc.).

The following keyword arguments are supported:

• group_id – Send this message to the group identified by group_id.

• replied_to_id – This message is a reply to the message identified by replied_to_id.

• direct_to_id – Send this as a direct message to the user identified by direct_to_id.

• topics – A list of topics for the message. Topics should be given as strings. There cannot be more than 20 topics for one message.

• broadcast – Set this to True to send a broadcast message. Only network admins have permission to send broadcast messages.

• open_graph_object – A dict describing an open graph object to attach to the message. It supports the following keys:

  • url (required)
  • title
  • image
  • description
  • object_type
  • site_name
  • fetch (set to True to derive other OG data from the URL)
  • meta (for custom structured data)

delete(message_id)

Deletes the message identified by message_id.

email(message_id)

Emails the message identified by message_id to the authenticated user.

find(message_id)

Returns the message identified by the given message_id.

from_followed_conversations(older_than=None, newer_than=None, limit=None, threaded=None)

Returns messages from users the current user follows, or groups the current user belongs to.

See the all() method for a description of the keyword arguments.

from_my_feed(older_than=None, newer_than=None, limit=None, threaded=None)

Returns messages from the current user’s feed. This will either correspond to from_top_conversations() or from_followed_conversations() depending on the user’s settings.

See the all() method for a description of the keyword arguments.

from_top_conversations(older_than=None, newer_than=None, limit=None, threaded=None)

Returns messages from the current user’s top conversations.

See the all() method for a description of the keyword arguments.

from_user(user_id, older_than=None, newer_than=None, limit=None, threaded=None)

Returns messages that were posted by the user identified by user_id.

See the all() method for a description of the keyword arguments.

in_thread(thread_id, older_than=None, newer_than=None, limit=None, threaded=None)

Returns messages that belong to the thread identified by thread_id.

See the all() method for a description of the keyword arguments.

like(message_id)

The current user likes the message identified by message_id.

private(older_than=None, newer_than=None, limit=None, threaded=None)

Returns of the private messages received by the current user.

See the all() method for a description of the keyword arguments.

received(older_than=None, newer_than=None, limit=None, threaded=None)

Returns messages received by the current user.

See the all() method for a description of the keyword arguments.

sent(older_than=None, newer_than=None, limit=None, threaded=None)

Returns of the current user’s sent messages.

See the all() method for a description of the keyword arguments.

unlike(message_id)

Removes the current user’s “like” from the message identified by message_id.

UsersAPI object

class yampy.apis.UsersAPI(client)

Provides an interface for accessing the user related endpoints of the Yammer API. You should not instantiate this class directly; use the yampy.Yammer.users() method instead.

__init__(client)

Initializes a new UsersAPI that will use the given client object to make HTTP requests.

all(page=None, letter=None, sort_by=None, reverse=None)

Returns all the users in the current user’s network.

Customize the response using the keyword arguments:

• page – Enable pagination, and return the nth page of 50 users.
• letter – Only return users whose username begins with this letter.
• sort_by – Sort users by “messages” or “followers” (default order is alphabetical by username).
• reverse – Reverse sort order.

create(email_address, full_name=None, job_title=None, location=None, im=None, work_telephone=None, work_extension=None, mobile_telephone=None, significant_other=None, kids_names=None, interests=None, summary=None, expertise=None, education=None, previous_companies=None)

Creates a new user.

Most of the parameter names are self explanatory, and accept strings. A few expect specific formats:

• im – Provide instant messages details as a dict with provider and username keys, e.g. {"provider": "gtalk", "username": "me@gmail.com"}
• education – Provide education details as a list of dicts. Each dict should have the keys: school, degree, description, start_year and end_year.
• previous_companies – Provide previous employment details as a list of dicts. Each dict should have the keys: company, position, start_year, end_year.

delete(user_id)

Delete the user identified by user_id.

find(user_id)

Returns the user identified by the given user_id.

find_by_email(email_address)

Returns the user identified by the given email_address.

find_current(include_group_memberships=None, include_followed_users=None, include_followed_tags=None)

Returns the current user.

in_group(group_id, page=None)

Returns all the users belonging to the group identified by the given group_id.

Use the page parameter to enable pagination and retrieve a specific page of users.

suspend(user_id)

Suspend the user identified by user_id.

update(user_id, full_name=None, job_title=None, location=None, im=None, work_telephone=None, work_extension=None, mobile_telephone=None, significant_other=None, kids_names=None, interests=None, summary=None, expertise=None, education=None, previous_companies=None)

Updates the user identified by the given user_id.

For more information on parameter formats, see the create() method.

Client object

class yampy.client.Client(access_token=None, base_url=None)

A client for the Yammer API.

__init__(access_token=None, base_url=None)

delete(path, **kwargs)

Makes an HTTP DELETE request to the Yammer API.

The path should be the path of an API endpoint, e.g. “/messages/123”

get(path, **kwargs)

Makes an HTTP GET request to the Yammer API. Any keyword arguments will be converted to query string parameters.

The path should be the path of an API endpoint, e.g. “/messages”

post(path, **kwargs)

Makes an HTTP POST request to the Yammer API. Any keyword arguments will be sent as the body of the request.

The path should be the path of an API endpoint, e.g. “/messages”

put(path, **kwargs)

Makes an HTTP PUT request to the Yammer API. Any keyword arguments will be sent as the body of the request.

The path should be the path of an API endpoint, e.g. “/users/123”

GenericModel object

class yampy.models.GenericModel

A dict subclass that provides access to its members as if they were attributes.

Note that an attribute that has the same name as one of dict’s existing method (keys, items, etc.) will not be accessible as an attribute.

classmethod from_json(json_string)

Parses the given json_string, returning GenericModel instances instead of dicts.

Errors

Exception classes representing error responses from the Yammer API.

exception yampy.errors.InvalidAccessTokenError

Raised when a request is made with an access token that has expired or has been revoked by the user.

exception yampy.errors.InvalidEducationRecordError

Raised when creating a user with an education record that doesn’t include all of the requried information.

exception yampy.errors.InvalidMessageError

Super class for the various kinds of errors that can occur when creating a message.

exception yampy.errors.InvalidOpenGraphObjectError

Raised when an invalid Open Graph object is attached to a new message.

exception yampy.errors.InvalidPreviousCompanyRecord

Raised when creating a user with a previous_companies record that doesn’t include all of the required fields.

exception yampy.errors.InvalidUserError

Super class for the various kinds of errors that can occur when creating a user.

exception yampy.errors.NotFoundError

Raised when the Yammer API responds with an HTTP 404 Not Found error.

exception yampy.errors.RateLimitExceededError

Raised when a request is rejected because the rate limit has been exceeded.

exception yampy.errors.ResponseError

Raised when the Yammer API responds with an HTTP error, and there isn’t a more specific subclass that represents the situation.

exception yampy.errors.TooManyTopicsError

Raised when a message cannot be created because too many topics have been specified.

exception yampy.errors.UnauthorizedError

Raised when the Yammer API responds with an HTTP 401 Unauthorized error. This may mean that the access token you are using is invalid.