RingCentral Avatars

Overview

This library will build RingCentral avatars using Gmail-like default avatars. It can build Gmail-like avatars for the following:

all RingCentral users (extensions) without images
all RingCentral users, overwriting existing images (useful for testing in Sandbox accounts)
specific extensions
authorized user extension only

By default, the images will look like the following in the RingCentral softphone:

This library uses Avatarly to generate the avatars and can pass through any avatar option for customization purposes.

Experimental Identicon support is also included via ruby_identicon. Please see the source for usage until it gets a bit more use.

PNG metadata is supported which can be uploaded to and downloaded from RingCentral.

Pre-requisites

ImageMagick
A RingCentral account (production or sandbox) with REST API access
A RingCentral administrator account is necessary to update profile images for others

Test first in sandbox. Your app needs to be graduated in order to run against your production account.

Installation

$ gem install ringcentral-avatars

Usage

require 'ringcentral-avatars'
require 'ringcentral_sdk'

client = RingCentralSdk::REST::Client.new [...]

avatars = RingCentral::Avatars.new client                                # Default options
avatars = RingCentral::Avatars.new client, avatar_opts: {font_size: 275} # Avatarly options

avatars.create_defaults             # create default avatars only
avatars.create_all                  # create all avatars, overwriting existing avatars

avatars.create_mine                 # does not overwrite existing user avatar
avatars.create_mine overwrite: true # overwrite existing user avatar

avatars.create_avatar ext                  # create a default for an extension hash
avatars.create_avatar ext, overwrite: true # overwrite existing for an extension hash

For batch operations, consider using [RingCentral SDK's] config.retry = true option for automatic handling of rate limiting using 429 headers.
For avatar customization, see Avatarly options. The default avatar size is 600.

Adding PNG Metadata

RingCentral Avatars supports adding PNG Metadata per the W3C PNG Specification. This can be useful for tracking avatars created by this library for selective updates vs. avatars uploaded via other means.

The default description is RingCentral Default Avatar, however it can be modified as shown below.

avatars = RingCentral::Avatars.new client, png_metadata: { 'Description': 'RingCentral Avatar' }

avatars.png_metadata['Description'] = 'Updated Description'

Sample Scripts

The following sample scripts are provided in the GitHub repo under the ./scripts directory.

update_avatar.rb - Updates all or own avatar image with optional rewrite CLI arguments.
get_avatar.rb - Retrieve and save own avatar image to _my_avatar.png file.
avatar_info.rb - Parses and dumps PNG metadata for validation of _my_avatar.png file.

To run these files, install dependencies and configure the demo with the following:

$ cd scripts
$ bundle
$ cp rc_config_sample.env.txt .env
$ vi .env

Run the scripts with the following:

$ ruby update_avatar.rb --overwrite
$ ruby get_avatar.rb
$ ruby avatar_info.rb

Test Uploads

The scripts directory contains test images for png, jpg, and gif file types: test_filetype_png.png, test_filetype_jpg.jpg, and test_filetype_gif.gif.

Test Upload Script

This repo also includes test scripts to upload PNG, JPG, and GIF format images.

$ cd ringcentral-avatars-ruby/scripts
$ vi .env
$ ruby test_filetype.rb --filetype=png
$ ruby test_filetype.rb --filetype=jpg
$ ruby test_filetype.rb --filetype=gif

Test cURL Command

$ curl -v -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' -F image=@test_filetype_gif.gif 'https://platform.devtest.ringcentral.com/restapi/v1.0/account/~/extension/~/profile-image'

Change Log

See CHANGELOG.md

Credits

Test icons files are adapted from freeware Filetype Icons by GraphicLoads.

Contributing

Fork it ( http://github.com/ringcentral-ruby/ringcentral-avatars-ruby/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

RingCentral Avatars is available under an MIT-style license. See LICENSE.txt for details.