RC2FM Connector | Technical Documentation

RC2FM Help Docs

OVERVIEW

Current Version

Current Version: 1.1.1 - released 6/13/2017 Download demo file here View, diff, or download the XML source code from our Git repository Version history: Refer to Version History topic below Known Issues: Refer to Support section

Introduction

RC2FM Connector is a back-end web service for integrating FileMaker with RingCentral Office® – a best of breed VoIP Cloud PBX from RingCentral Inc. (NYSE:RNG). RC2FM Connector enables bolt-on FileMaker Cloud Telephony Integration (CTI) for all custom apps developed in FileMaker and running on iOS, Mac, Windows and the Web. RC2FM Connector is an authorized RingCentral Public App designed to allow FileMaker custom apps to leverage most significant functionality provided RingCentral's RESTful APIs using native FileMaker Scripts. Once configured and activated, this web service enables the following features and functions of a RingCentral phone system extension: • Click/Tap to dial any phone number stored in FileMaker.
• Send outbound calls to your cell phone, personal phone, or RingCentral extension.
• Send/receive SMS to/from any contact stored in FileMaker in near real time.
• NEW! Send/receive MMS to/from any contact stored in FileMaker in near real time.
• Send/receive Faxes directly from FileMaker containers or from your device's file system.
• Download call log and message log history and store them as FileMaker records.
• Download voicemails and store them as MP3's in FileMaker containers.
• Download call recordings and store them as MP3's in FileMaker containers.
• Download sent/received Faxes and store them as PDFs in FileMaker containers.
• Set “Read” status of unread SMS, voicemails, and fax messages.
• Trigger scripts in your FileMaker custom app on incoming calls (Pro/Advanced only).**

RC2FM Connector pre-processes API responses to strip out extraneous information. We also provide a fully unlocked demo file complete with ready-made modular FileMaker Scripts and field-mapped data tables to make the process of working with JSON virtually unnecessary. RC2FM Connector requires no locked connector files, no custom functions, no plugins, and works on locally stored custom apps as well as on apps hosted on FileMaker Server. Integration into a compatible FileMaker solution is as simple as 1-2-3: 1) Import all required tables with their associated records from our demo file;
2) Import (or copy/paste) all required scripts from our demo file;
3) Copy/paste the required layout objects from our demo file. Once you have connected the table occurrences and the scripts, all that is left to do is modify a single configuration script. For more details, refer to the Getting Connected section of this documentation. **Requires RingCentral Desktop app.

Supported platforms and versions

RC2FM Connector supports Claris FileMaker versions 13 and above running on iOS, macOS, Windows, and WebDirect. Although RC2FM Connector can be made to work on FileMaker 12, we do not recommend or officially support it. Automation USA strongly recommends developers implement RC2FM Connector on the most current release of FileMaker or minimally on version 16.0.3.302 or higher. RC2FM Connector supports all versions of FileMaker currently supported by Claris International. As Claris discontinues support for older releases of FileMaker, Automation USA will discontinue support for them as well.

Requirements

• RingCentral Office Standard, Premium or Enterprise Edition • NEW! Support for TELUS Business Connect and AT&T Office@Hand accounts • FileMaker Pro, Go, WebDirect versions 13+ (iOS, Windows, Mac) • Internet Explorer 11+ (Windows 8+) • Firefox 46+ (Windows, Mac), • Chrome 50+ (Windows, Mac) • Safari 10.1+ (Mac), Safari 11+ preferred

Version history

Latest Version: 1.1.1 - released 6/13/2017
XML source code: https://github.com/Automation-USA/RC2FM/releases/tag/1.1.1

Support for cURL options in all API calls:

Updated all remaining API calls which were still passing parameters in the url with conditional branching to support cURL options. This completes FileMaker 16 compatibility for all RC2FM endpoints. The nine (9) modifed scripts are:
1. 'RC2FM__Login' -- [calls "login.php" endpoint]
2. 'RC2FM__Logout' -- [calls "logout.php" endpoint)]
3. 'RC2FM__Check_Session_Status' -- [calls "get_token.php" endpoint]
4. 'RC2FM__Function__GetMessages_SUBMIT ( param )' -- [calls "msg.php" endpoint]
5. 'RC2FM__Function__GetCallLog_SUBMIT ( param )' -- [calls "calllog.php" endpoint]
6. 'RC2FM__Function__GetCallLogPro_SUBMIT ( param )' -- [calls "calllog_pro.php" endpoint]
7. 'RC2FM__Function__Fetch_Attachment ( param )' -- [calls "get_attachments.php" endpoint]
8. 'RC2FM__Function__Fetch_Recording' -- [calls "get_call_attachments.php" endpoint]
9. 'RC2FM__Update_ReadStatus' -- [calls "readstatus.php" endpoint] Previous Version: 1.1.0 - released 6/6/2017
XML source code: https://github.com/Automation-USA/RC2FM/releases/tag/1.1.0

New MMS functionality:

Enhanced the "sms.php" API to support new MMS capabilities in RingCentral's REST APIs. For details on mms, refer to the "sms" documentation under the "API Reference Guide" topic, located in the "Protocols" section.

New Account-level call log reporting:

Released new "calllog_pro.php" API for account level call reporting (company wide call history). For details on account level call log, refer to the "calllog_pro" documentation under the "API Reference Guide" topic, located in the "Protocols" section.

New Message log search parameters:

Enhanced the "msg.php" API to support three (3) additional optional parameters to exclude undesired messages. 1. 'messageType' = filter messages by type (acceptable values are "SMS", "Fax" , "VoiceMail")
2. 'direction' = filter messages by direction (acceptable values are "Inbound", "Outbound")
3. 'readStatus' = filter messages by status (acceptable values are "Read", "Unread") New AT&T Office@Hand compatibility:
Effective May 31st 2017, RC2FM Connector has been approved and enabled to support subscribers of RingCentral Office@Hand from AT&T.

New FileMaker 16+ compatibility:

Most RC2FM API calls have been updated with conditional branching to support cURL options and the new Insert From URL script step options available in FileMaker 16+, while still retaining backwards compatibilty with versions 13 thru 15. Where appropriate, response targets have been changed from global fields to local or global variables. Schema modifications:
---------------------------------------
'RC2FM_LOGS' table
added two (2) new text fields in support of mms attachments:
1. 'attachmentType'
2. 'mmscount' added one (1) number field in support of mms attachments:
1. 'size' added one (1) calculation field in support of mms attachments:
1. 'sizeCalc' modified one (1) calculation field to correct "php unserialize" function error:
1. 'sms_message'
--------------------------------------- 'RC2FM_ATTACHMENTS' table
added one (1) new calculation field:
1. 'binaryCalc'
--------------------------------------- RC2FM_GLOBALS' table
added one (1) global container field in support of MMS functionality:
1. 'MMS_Utility_Container' added three (3) non-essential global text fields in support of the demo file UI:
1. '_kftg_attachment_id'
2. '_kftg_chat_phone'
3. 'Email_To'
---------------------------------------
Previous Version: 1.0.3 - released 12/12/2016 XML source code: https://github.com/Automation-USA/RC2FM/releases/tag/1.0.3

Enhanced extension level call log reporting:

Introduced optional 'phone_number' parameter in RC2FM's 'calllog' API, allowing FileMaker to selectively request:
- all call activity for the logged in user (including extension-to-extension calls)
- selected call activity for any one of the user's possible secondary DID numbers
- default call activity (calls to/from the user's default phone number only) For details,on extension level call log, refer to the "calllog" documentation under the "API Reference Guide" topic, located in the "Protocols" section.

Schema and data parsing modifications:

In support of enhanced call log reporting, added two (2) new text fields ('toExtensionNumber' and 'fromExtensionNumber') to the 'RC2FM_LOGS' table and modified the "Parse Message/Call Logs" data operation to accept the additional values returned by the call log API reponse.

Performance tuning for server-side Data Operations:

Implemented a 1.1 second pause when executing recursive Remote Procedure Calls (looping Perform Script On Server script steps) to insert log records for large data sets. When executing "Create Log records" data operations in hosted environments, a brief pause once every five (5) RPC calls has been implemented to allow the server time to process the queued payloads. This modification reduces RC2FM's potential impact on server performance when parsing and inserting payloads in excess of 2,240 records.
--------------------------------------
Previous Version: 1.0 - released 6/15/2016
XML source code: https://github.com/Automation-USA/RC2FM/releases/tag/1.0.0
Initial release

INSTALLATION

Getting Connected

Automation USA provides a fully unlocked demo file containing all of the tables, scripts, and layout objects required to integrate RingCentral with any Claris FileMaker custom app that is compatible with RC2FM Connector. Developers can choose to either modify and extend the provided demo file, or bring the required elements into their own custom app(s). To implement this integration into a custom app requires performing several steps. The sequence of these integration steps is important and should be as follows: STEP 1) Import (or copy/paste) all required tables from the demo file
All required tables follow a naming convention whose name begins with the prefix "RC2FM_". Note that if you choose to copy/paste you wil still need to import table data. As of version 1.0, the required tables are: • RC2FM_GLOBALS (1 record)
• RC2FM_SETTINGS (1 record)
• RC2FM_FAX_COVERS (14 records)
• RC2FM_LOGS (zero records)
• RC2FM_ATTACHMENTS (zero records) Once you've imported these tables and their data into your app, you must join the tables together as shown in the figure below. All joins are Cartesian [X], with the exception of the join between "RC2FM_LOGS" and "RC2FM_ATTACHMENTS". The join between "RC2FM_LOGS" and "RC2FM_ATTACHMENTS" is a parent-child relationship with cascading delete and record creation options (see figure below). STEP 2) Copy/paste all required Scripts from the demo file.
All required Scripts contain the word "RC2FM" in their title. All required Scripts are also organized within a Script folder called "RC2M Modules [REQUIRED]". Copy/Paste (or import) all of these scripts into your custom app (see figure below). STEP 3) Copy/paste all required layout elements from the demo file
(REQUIRED ONLY FOR FILEMAKER VERSIONS 15 AND UNDER)
Required layout elements consit of global fields and web viewer objects. In all cases, the global fields can be found just outside and immediatelly adjactent to the right margin of each layout. In all cases, the web viewer object is concealed behind another layout object, either in the bottom right corner of the bottom navigation bar, or beneath a field in the body of the layout. In all layouts, the location of these required layout elements has been indicated in the demo file using red arrows and red lettering (see figure below).

Configuring your integration

Once all required elements are in place, configuration of the integration is a two-step process: 1) Modify the configuration Script titled 'RC2FM__Config'
2) Insert a call to the 'RC2FM__Config' Script into your 'OnFirstWindowOpen' script trigger. Step 1. Update global variables in 'RC2FM__Config' Script.
The 'RC2FM__Config' Script is designed to dynamically specify layout names, field paths, and table occurrence names referred to by many other RC2FM Connector Scripts. These dynamic paths are stored as global variables [$$varName] at startup. In the Script Workspace, locate the 'RC2FM__Config' Script and modify the following lines:

Modify line 4 ('$$showDialogs' variable). This variable enables/disables the display of application error message alerts
Modify line 9 ('$$messageLogLayout' variable). Specify the name of a default layout of your choosing that is based on the 'RC2FM_LOGS' table occurrence. This layout should contain all fields from the 'RC2FM_LOGS' table. Additionally, it is reccomended (but not required) that you also add the 'rawBase64' and 'binary' fields from the 'RC2FM_ATTACHMENTS' table occurrence to that same layout. If no such layout exists in your custom app, you must create one.
Modify line 12 ('$$rc2fm_caller_id_storage' variable). When a user 'logs in' to their RingCentral account, the RC2FM Connector API responds with a list of available caller ID choices for that user (main company number, direct line, etc.). These values can be used to populate a value list of choices in FileMaker for RingOut use as well as for setting caller ID. You must create a field in your solution that is available to the script during login and then specify the fully qualified name to that field in this line.

Step 2. Add 'RC2FM__Config' Script to your startup routine.
Once it has been properly configured, the 'RC2FM__Config' Script must be set to run at startup. If you have no such script trigger defined, simply specify the 'RC2FM__Config' Script as your startup script

Troubleshooting your integration

We've made every effort to make the RC2FM Connector integration as dyanmic and easily configurable as possible so it can be easily transferred to any supported FileMaker solution. However there are some script steps such as "Insert from URL" which require hard coded paths in legacy versions of FileMaker (15 and earlier). The most common configuration errors are as follows:

script step errors. When pasting/importing into your custom app, be sure to review all RC2FM scripts for missing field references.
Configuration script errors. Verify that all global variables in the 'RC2FM__Config' script point to valid table names, field names, and layout names in your solution and follow the path formats used in the demo file.
Layout object or field is missing on the layout. Verify that all required global fields and other layout elements are present on the layout the script is using or navigating to
Object placement and naming. The required Web Viewer object must be named 'ajax_web_viewer' and be placed within the margins of any layout part (not the pasteboard). The required global fields can be placed outside the layout marging (on the pasteboard) but must must "touch" (overlap) the edge of the layout margin.

PROTOCOLS

Service Activation

We've made service activation much easier by making it self service. RC2FM now leverages OAuth2 authentication to securely activate your subscription. Activation no longer requires that you provide Automation USA with your RingCentral® Account ID. Instead, now you simply click on a link a follow a two step process of authorizing our app. Now when you purchase an RC2FM subscription, the checkout screen and the order confirmation email will both contain an "Authorize" button (see screenshot below). When you click on the "Authorize" button, you will come to an access request page on RingCentral's website (see image below). Simply click on "Authorize" again and sign into your RingCentral account using an account with System Administration rights. If your login is successful, you will be redirected back to a confirmation page our online store. Your subscription is automatically activated and ready for immediate use.

Authentication

Once your RC2FM account has been activated, your RingCentral users may authenticate against our RC2FM servers using their existing RingCentral credentials. Although each user may sign on to RC2FM from as many as three (3) FileMaker devices simultaneously, the maximum number of concurrent RC2FM users will be restricted to the subcription level you purchased (minimum of 1 user and maximum of all users in your account). As with RingCentral authentication, the RC2FM user name may be supplied in either of two ways:

User name= Main company phone number + user's extension number; or
User name= direct phone number (no extension number requried)

In either case, the correct phone number must include the country code format, and should be in E164 format. Main number + extension authentication example:
User name: 13055551212
Extension: 123
Password: RC2FM_rocks! Direct Number (DID) authentication example:
User name: 17865512008
Extension: [leave blank]
Password: RC2FM_rocks!

Session Control

RingCentral uses OAuth2 authorization flow to exchange your RingCentral credentials for a session token, which carries an expiration time. RC2FM Connector manages the entire session control on behalf of FileMaker on a per device basis and either expires or renews the session based upon device activity. Concurrent Connections
RC2FM Connector manages RingCentral API sessions on a per user/per device basis. RC2FM Connector allows up to three (3) concurrent devices per user, but only one (1) user session per device. Default Timeouts
The default timeout for RC2FM Connector sessions is 45 minutes. If a connected FileMaker device does not make a RingCentral API call during a 45 minute period, that device's session is automatically expired and the device must authenticate again to establish a new session. If, however, the device makes at least one (1) RingCentral API call every 45 minutes, that device's sesion is automatically renewed for an additional 45 minutes. API Rate/Usage Limits
RingCentral places limits on the number of API calls an application can make on a per user/per minute basis. This means that regardless of the number of concurrent device sessions a user may have, the maximum number of API calls allowed remains limited based on the user. RingCentral categorizes API calls into four groups: Heavy, Medium, Light, and Auth and assigns a usage rate plan on a per app basis. If a user exceeds the maximum number of API calls/minute for any of those four groups, the user will be penalized for a period of one (1) minute during which the user will not be allowed to make any API calls from any device session. Currently, our RC2FM Connector app is categorized according to the following rate plan:

Heavy API group: 20 requests/ user / 60 secs
Medium API group: 40 requests / user / 60 secs
Light API group: 50 requests / user / 60 secs
Auth API group: 5 requests / user60 secs 60 secs

How each specific API call is categorized can be found in the API Reference section.

Transmission Control

Encrypted Communication
RC2FM requires all transmissions take place over port 443 (https) using SSL certificate verification. Base64 Encoding
RC2FM requires all parameter values be Base64 Encoded. MMS Limitations
RingCentral restricts outbound MMS attachments to no more than 1.5 MB (total) and no more than 10 attachments. However, RC2FM supports only a maximum of five (5) outbound attachments per message.
Also, due to technical limitations relating to legacy versions of WebDirect, RC2FM Connector discards all outbound MMS attachments on WebDirect versions 15 and earlier and send only the SMS text portion. This restriction does not apply to FileMaker WebDirect 16+ FaxOut Limitations
RingCentral restricts faxes to no more than 20 MB and 200 pages. However, due to technical limitations relating to legacy versions of WebDirect, RC2FM Connector limits FaxOut documents to no more than 6KB on WebDirect versions 15 and earlier. This restriction does not apply to FileMaker WebDirect 16+

Supported MIME Types

MMS Attachments: RingCentral's MMS API currently supports the following 13 outbound file formats/media types: extension = "vcf" ; "text/vcard" ; extension = "rtf" ; "application/rtf" ; extension = "svg" ; "image/svg+xml" ; extension = "gif" ; "image/gif" ; extension = "png" ; "image/png" ; extension = "bmp" ; "image/bmp" ; extension = "jpeg" or extension = "jpg" ; "image/jpeg" ; extension = "tiff" or extension = "tif" ; "image/tiff" ; extension = "mp3" ; "audio/mpeg" ; extension = "mp4" or extension = "m4v" ; "video/mp4" ; extension = "m1v" or extension = "m2v" or extension = "mpg" or extension = "mpeg" ; "video/mpeg" ; extension = "zip" ; "application/zip" ; extension = "gz" or extension = "gzip" ; "application/gzip" RingCentral's MMS API currently supports the following 19 inbound file formats/media types: extension = "vcf" ; "text/vcard" ; extension = "htm" or or extension = "html" ; "text/html" ; extension = "txt" ; "text/plain" ; extension = "rtf" ; "application/rtf" ; extension = "svg" ; "image/svg+xml" ; extension = "gif" ; "image/gif" ; extension = "png" ; "image/png" ; extension = "bmp" ; "image/bmp" ; extension = "jpeg" or extension = "jpg" ; "image/jpeg" ; extension = "tiff" ; "image/tiff" ; extension = "mp3" ; "audio/mpeg" ; extension = "avi" ; "video/msvideo" ; extension = "flv" ; "video/x-flv" ; extension = "mp4" or extension = "m4v" ; "video/mp4" ; extension = "m1v" or extension = "m2v" or extension = "mpg" or extension = "mpeg" ; "video/mpeg" ; extension = "mov" ; "video/quicktime" ; extension = "wmv" ; "video/x-ms-wmv" ; extension = "zip" ; "application/zip" ; extension = "gz" or extension = "gzip" ; "application/gzip"
Faxing:
RingCentral's FaxOut API renders 1-bit images to be transmitted via fax and supports the following file formats/media types: extension = "pdf" ; mime type = "application/pdf" ; extension = "psd" ; mime type = "image/vnd.adobe.photoshop" ; extension = "doc" ; mime type = "application/msword" ; extension = "docm" ; mime type = "application/vnd.ms-word.document.macroenabled.12" ; extension = "docx" ; mime type = "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ; extension = "xls" ; mime type = "application/vnd.ms-excel" ; extension = "xlsb" ; mime type = "application/vnd.ms-excel.sheet.binary.macroenabled.12" ; extension = "xlsm" ; mime type = "application/vnd.ms-excel.sheet.macroenabled.12" ; extension = "xlsx" ; mime type = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" ; extension = "ppt" ; mime type = "application/vnd.ms-powerpoint" ; extension = "pptm" ; mime type = "application/vnd.ms-powerpoint.presentation.macroenabled.12" ; extension = "pptx" ; mime type = "application/vnd.openxmlformats-officedocument.presentationml.presentation" ; extension = "vsd" ; mime type = "application/vnd.visio" ; extension = "pub" ; mime type = "application/x-mspublisher" ; extension = "wps" ; mime type = "application/vnd.ms-works" ; extension = "wri" ; mime type = "application/x-mswrite" ; extension = "tiff" or extension = "tif" ; mime type = "image/tiff" ; extension = "jpeg" or extension "jpg" ; = mime type = "image/jpeg" ; extension = "gif" ; mime type = "image/gif" ; extension = "bmp" ; mime type = "image/bmp" ; extension = "png" ; mime type = "image/png" ; extension = "pcx" ; mime type = "image/x-pcx" ; extension = "tga" ; mime type = "image/x-tga" ; extension = "wpd" ; mime type = "application/vnd.wordperfect" ; extension = "htm" or extension = "html" ; mime type = "text/html" ; extension = "rtf" ; mime type = "application/rtf" ; extension = "txt" ; mime type = "text/plain" ; extension = "xml" ; mime type = "application/xml" ; extension = "csv" ; mime type = "text/csv"

API Reference Guide (Endpoints)

RC2FM Connector supports a select group of RingCentral's API endpoints. Furthermore, where possible we have consolidated and synthesized functions to simpify the integration. What follows is a list of RC2FM Connector's API endpoints, as of the most current release: ------------------
'login' Purpose:
Session authentication RC2FM Endpoint:
https://{BaseURL}/api/login.php? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
password={ RingCentral Password }
extension={ RingCentral Extension (if Main Phone Number is used) }
environment parameters (see below)

rate plan:
Auth ------------------
'logout' Purpose:
Session termination RC2FM Endpoint:
https://{BaseURL}/api/logout.php?
parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={ RingCentral Extension (if Main Phone Number is used) }
user_id={ 'extension' parameter returned by login.php ($$extension global variable)}
environment parameters (see below)

rate plan:
N/A ------------------
'get_token' Purpose:
Check for active session token RC2FM Endpoint:
https://{BaseURL}/api/get_token.php? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={ RingCentral Extension (if Main Phone Number is used) }
user_id={ 'extension' parameter returned by login.php ($$extension global variable)}
persistent_id={device persistent id}

rate plan:
N/A ------------------
'fax_base64' Purpose:
Upload outgoing fax RC2FM Endpoint:
https://{BaseURL}/api/v1.php?action=fax_base64? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
user_id={'extension' parameter returned by login.php ($$extension global variable)}
account_id={'account' parameter returned by login.php ($$account global variable)}
to={destination fax number (E164 format) }
faxResolution= {'High' or 'Low'}
Content-Type= {MIME type}
coverIndex= {cover page template id}
coverPageText= {cover page text message}
attachment_filename= {fax document name}
attachment_content= {fax document file}
environment parameters (see below)

rate plan:
Heavy ------------------
'ringout' Purpose:
Initiate outgoing phone call RC2FM Endpoint:
https://{BaseURL}/api/v1.php?action=ringout? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={'extensionNumber' parameter returned by login.php ($$extensionNumber global variable) }
user_id={'extension' parameter returned by login.php ($$extension global variable)}
account_id={'account' parameter returned by login.php ($$account global variable)}
to={destination phone number (digits only or E164)}
from={pickup call from phone number (digits only or E164)}
caller_id={available caller id phone number (digits only or E164)}*
environment parameters (see below)

*the 'caller_id' parameter is currently disabled. Refer to the Known Issues section rate plan:
Heavy ------------------
'sms' Purpose:
Send outgoing sms or mms message RC2FM Endpoint:
https://{BaseURL}/api/v1.php?action=sms? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={'extensionNumber' parameter returned by login.php ($$extensionNumber global variable) }
user_id={'extension' parameter returned by login.php ($$extension global variable)}
account_id={'account' parameter returned by login.php ($$account global variable)}
from={sms originating phone number (digits only or E164)}
to={sms destination phone number (digits only or E164)}
text={sms message body}
attachment_filename={(optional**) mms attachment 1 file name}
attachment_content={(optional**) mms attachment 1 binary (Base64 encoded)}
attachment_filename1={(optional**) mms attachment 2 file name}
attachment_content1={(optional**) mms attachment 2 binary (Base64 encoded)}
attachment_filename2={(optional**) mms attachment 3 file name}
attachment_content2={(optional**) mms attachment 3 binary (Base64 encoded)}
attachment_filename3={(optional**) mms attachment 4 file name}
attachment_content3={(optional**) mms attachment 4 binary (Base64 encoded)}
attachment_filename4={(optional**) mms attachment 5 file name}
attachment_content4={(optional**) mms attachment 5 binary (Base64 encoded)}
environment parameters (see below)

** introduced in version 1.1.0, for mms only rate plan:
Medium ------------------
'msg' Purpose:
Download all message logs (mms, sms, fax, voicemail) RC2FM Endpoint:
https://{BaseURL}/msg.php? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={'extensionNumber' parameter returned by login.php ($$extensionNumber global variable) }
user_id={'extension' parameter returned by login.php ($$extension global variable)}
account_id={'account' parameter returned by login.php ($$account global variable)}
dateFrom={(optional) unix timestamp indicating starting date/time, defaults to previous 6 months}
message_type={(optional, introduced in version 1.1.0) filter request by message type, acceptable values are "SMS" , "Fax", or "VoiceMail"}
direction={(optional, introduced in version 1.1.0) filter request by message direction, acceptable values are "Inbound" or "Outbound"}
read_status={(optional, introduced in version 1.1.0) filter request by message status, acceptable values are "Read" or "Unread"}
environment parameters (see below)

rate plan:
Heavy ------------------
'calllog' Purpose:
Download all extension-level call logs (with call recording record ids)
RC2FM Endpoint:
https://{BaseURL}/calllog.php? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={'extensionNumber' parameter returned by login.php ($$extensionNumber global variable) }
user_id={'extension' parameter returned by login.php ($$extension global variable)}
account_id={'account' parameter returned by login.php ($$account global variable)}
phone_number={(optional, introduced in version 1.0.3), allows for requesting all call activity (includes extension-to-extension calls) or selected call acitivity by phone number. Acceptable parameter values are: (leave blank), "all", and specific phone number in E164 format (numeric only)}
dateFrom={optional, unix timestamp indicating starting date/time}
environment parameters (see below)

rate plan:
Heavy ------------------
'calllog_pro' Purpose:
Download all account-level call logs (with call recording record ids). This endpoint is available only to site license subscribers with 5 user subscriptions or more and requires the authenticated user to have either "Super Admin" or "Phone System Admin" RingCentral privileges.
RC2FM Endpoint:
https://{BaseURL}/calllog_pro.php? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={'extensionNumber' parameter returned by login.php ($$extensionNumber global variable) }
user_id={'extension' parameter returned by login.php ($$extension global variable)}
account_id={'account' parameter returned by login.php ($$account global variable)}
dateFrom={optional, unix timestamp indicating starting date/time}
environment parameters (see below)

rate plan:
Heavy ------------------
'get_attachments' Purpose:
Download a single message attachment (fax or voicemail file) RC2FM Endpoint:
https://{BaseURL}/get_attachments.php? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={'extensionNumber' parameter returned by login.php ($$extensionNumber global variable) }
user_id={'extension' parameter returned by login.php ($$extension global variable)}
account_id={'account' parameter returned by login.php ($$account global variable)}
attachment_id={'id' field from 'RC2FM_LOGS' table record}
environment parameters (see below)

rate plan:
Medium ------------------
'get_call_attachments' Purpose:
Download a single call recording RC2FM Endpoint:
https://{BaseURL}/get_call_attachments.php? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
extension={'extensionNumber' parameter returned by login.php ($$extensionNumber global variable) }
user_id={'extension' parameter returned by login.php ($$extension global variable)}
account_id={'account' parameter returned by login.php ($$account global variable)}
attachment_id={'recordingid' field from 'RC2FM_LOGS' table record}
environment parameters (see below)

rate plan:
Heavy ------------------
'readstatus' Purpose:
Changes the status flag of a message from 'Unread' to 'Read' RC2FM Endpoint:
https://{BaseURL/readstatus.php? parameters:

auth={RingCentral Main Phone Number or User's Direct Phone Number}
user_id={'extension' parameter returned by login.php ($$extension global variable)}
pid={'id' field from 'RC2FM_LOGS' table record}
environment parameters (see below)

rate plan:
Medium ------------------
environment parameters Purpose:
Session control parameters, required by most RC2FM Connector API calls parameters:

persistent_id={device persistent id}
device {device number}
platform {device platform}
network {device network type}
fm_version {filemaker version}
user_language {device's user language}

rate plan:
N/A

API Responses

'login' success: Source:
RC2FM Connector Response: { "success" : 94 , "message" : "You are successfully logged in" , "account" : "(your account id, numeric)", "extension" : "(your extension id, numeric)", "MainCompanyNumber" : "(your company's main phone number)", "CompanyFaxNumber" : "(your company's main fax number)", "DirectNumber" : "(your first direct phone number)", "DirectNumber2" : "(your second direct or 'vanity' phone number", "admin" : { "enabled" : (boolean) },
"extensionNumber" : "(your telephone extension number)" } ------------------
'get_token' success : Source:
RC2FM Connector Response:
{ "success":1, "message":"User is already active." }
------------------
'logout' success : Source:
RC2FM Connector Response: { "success":98, "message":"You are sucessfully logged out." } ------------------
'fax_base64' success: Source:
RingCentral API endpoint Response: { "uri":"(RingCentral transaction endpoint)", "id":{contentid, "to": [ { "phoneNumber":"(E164 destination Fax Number)" "location":"Miami, FL", "messageStatus":"Queued" } ], "type":"Fax", "creationTime":"(UNIXtimestamp}", "readStatus":"Unread", "priority":"Normal", "attachments": [ { "id":(transaction id, numeric), "uri":(RingCentral transaction endpoint), "type":"RenderedDocument", "contentType":"(MIME type)" } ], "direction":"Outbound", "availability":"Alive", "messageStatus":"Queued", "faxResolution":"High", "faxPageCount":(number of pages), "lastModifiedTime":"(UNIXtimestamp)", "coverIndex":(cover page template id) } ------------------
'ringout' success: Source:
RingCentral API endpoint Response: { "uri":"(RingCentral transaction endpoint)", "id":(transaction id, numeric), status": { "callStatus":"InProgress", "callerStatus":"InProgress", "calleeStatus":"InProgress" }, "limit_remain":"(rate plan counter) }" ------------------
'sms' success: Source:
RingCentral API endpoint Response: { "uri":"(RingCentral FQDN transaction endpoint)", "id":transaction id, numeric), "to": [ { "phoneNumber":"(destination Phone Number(s))" } ], "from": { "phoneNumber":"(source Phone Number)" "location":"(City, State)" }, "type":"(SMS or MMS)", "creationTime":"{UNIXtimestamp}, "readStatus":"Read", "priority":"Normal", "attachments": [ { "id":(message id, numeric), "uri":"(RingCentral transaction endpoint)", "type":"Text", "contentType":"text/plain" } ], "direction":"Outbound", "availability":"Alive", "subject":"(message body)", "messageStatus":"Sent", "smsSendingAttemptsCount":1, "conversationId":(conversation id, numeric), "conversation": { "id":"(conversation id, numeric)", "uri":(RingCentral message store uri)" }, "lastModifiedTime":"(UNIXtimestamp)", "limit_remain":"(rate plan counter)" } ------------------
RC2FM error messages: Error 613 { "error":613, "message":"Concurrent device count exceeded. Maximum is 3 devices per user." } Source:
RC2FM Connector Definition:
Maximum number of device connections per user has been exceeded. -------- Error 614
{ "error":614, "message":"Concurrent PBX subscriber count exceeded." } Source:
RC2FM Connector Definition:
Maximum number of subscribers purchased has been exceeded. -------- Response:
{"error":200,"message":"Concurrent login on same device denied."} Source:
RC2FM Connector Definition:
Only one user session per device is allowed. -------- Error 1629
{ "error":1629, "message":"Access token expired. Maximum idle client time is 2700 seconds." } Source:
RC2FM Connector Definition:
Device session has been idle for too long and token has been expired.

FUNCTIONS

Functions Summary

In addition to basic authentication, session, and protocol controls, RC2FM Connector supports nine (9) core RingCentral integration functions:

FaxOut
RingOut
MMS/SMS (+ feature)
Get Messages
Get Call Log
Get Call Log Pro (new)
Get Attachment
Get Recording
Update 'Read' Status

1. FaxOut Manages uploading of outgoing faxes 2. RingOut Manages placing of outgoing phone calls 3. MMS/SMS Manages sending of outgoing SMS messages and uploading of MMS attachments 4. Get Messages Manages downloading of all incoming/outgoing message logs (sms, fax, voicemail) 5. Get Call Log Manages downloading of extension-level (user level) incoming/outgoing call logs (including call recording ids) 6. Get Call Log Pro Manages downloading of account-level (company wide) incoming/outgoing call logs (including call recording ids). Available for site licensed accounts of 5+ subscribers. 7. Get Attachment Manages downloading of a single message attachement (fax or voicemail binary) 8. Get Recording Manages downloading of a single phone call recording 9. Update 'Read' Status Manages the changing of message status from 'Unread' to 'Read'

FaxOut Function

FaxOut manages uploading of outgoing faxes. Includes two handler Scripts, a validation Script, and a function execution Script:
Handler Script 1: 'RC2FM__FaxOut ( chooseFile )'
Manages uploading of user selected fax documents from file system Parameters: $toPhone={Destination phone number (only digits, or E164)}
$$fileName={document file name (trimmed of special characters)}
$$mimeType={fax document's MIME type}
$$fileContainer={fully qualified container field name where fax is temporarily stored} Response:
$result={Get (ScriptResult) from call to execution Script} ------------------
Handler Script 2: 'RC2FM__FaxOut ( selectedContainer)'
Manages uploading of user selected container field Parameters:
$toPhone={Destination phone number (only digits, or E164)}
$$fileName={document file name (trimmed of special characters)}
$$mimeType={fax document's MIME type}
$$fileContainer={fully qualified container field name to be faxed} Success Response:
$result={Get (ScriptResult) from call to execution Script} ------------------ Validation Script: 'RC2FM__Subscript__FaxOut_Validate ( param )'
Validates fax documents against supported MIME types and file size restrictions Parameters:
$fileName={document file name (trimmed of special characters)}
$$mimeType={fax document's MIME type}
$$fileContainer={fully qualified container field name to be faxed} Sucess Response:
$mimeType={'Exit Script' result, matching MIME type for file's extension} ------------------
Execution Script: 'RC2FM__Function__FaxOut_SUBMIT ( params )'
Executes API call against 'fax_base64' RC2FM endpoint API Response:
In FileMaker Go/Pro - API response inserted into the global field 'RC2FM_GLOBALS::API_Response__RC_Reply'
In FileMaker WebDirect 16+ - API response inserted into the global field 'RC2FM_GLOBALS::API_Response__RC_Reply'
In leagcy WebDirect (version 15 and earlier) - No API response handling

RingOut Function

RingOut manages placing of outgoing phone calls. Includes one execution Script:
Execution Script: 'RC2FM__Function__RingOut_SUBMIT ( params )'
Executes API call against 'ringout' RC2FM endpoint Parameters:
$$callTo={Destination phone number (only digits, or E164)}
$$callFrom={pickup call from phone number (digits only or E164)}
$$callerID={available caller id phone number (digits only or E164)}* API Response:
In FileMaker Go/Pro - API response inserted into the global field 'RC2FM_GLOBALS::API_Response__RC_Reply'
In FileMaker WebDirect 16+ - API response inserted into the global field 'RC2FM_GLOBALS::API_Response__RC_Reply'
In legacy WebDirect (version 15 and earlier) - No API response handling
* NOTE: the 'caller_id' parameter is fully functional! This feature was previously disabled due to a RingCentral endpoint issue. For more details, refer to the Known Issues topic under the Support section.

SMS/MMS Function

Manages sending of outgoing SMS messages and uploading of MMS attachments. Includes one execution Script + one alternate (legacy) Script:
Execution Script: 'RC2FM__Function__MMS_SUBMIT ( params )'
Executes API call aginst 'sms' RC2FM endpoint Parameters:
$$smsTo={Destination phone number (only digits, or E164)}
$$message={sms message body}
attachment_filename={(optional**) mms attachment 1 file name}
attachment_content={(optional**) mms attachment 1 binary (Base64 encoded)}
attachment_filename1={(optional**) mms attachment 2 file name}
attachment_content1={(optional**) mms attachment 2 binary (Base64 encoded)}
attachment_filename2={(optional**) mms attachment 3 file name}
attachment_content2={(optional**) mms attachment 3 binary (Base64 encoded)}
attachment_filename3={(optional**) mms attachment 4 file name}
attachment_content3={(optional**) mms attachment 4 binary (Base64 encoded)}
attachment_filename4={(optional**) mms attachment 5 file name}
attachment_content4={(optional**) mms attachment 5 binary (Base64 encoded)} API Response:
In FileMaker Go/Pro - API response inserted into the global field 'RC2FM_GLOBALS::API_Response__RC_Reply'
In FileMaker WebDirect 16+ -API response inserted into the global field 'RC2FM_GLOBALS::API_Response__RC_Reply'
In legacy WebDirect (version 15 and earlier) - No API response handling Alternate Legacy Script: 'RC2FM__Function__SMS_SUBMIT ( params )'
Executes call against 'sms' RC2FM API endpoint with no MMS attachment handling Parameters:
$$smsTo={Destination phone number (only digits, or E164)}
$$message={sms message body} API Response:
In FileMaker Go/Pro - API response inserted into the global field 'RC2FM_GLOBALS::API_Response__RC_Reply'
In FileMaker WebDirect 16+ -API response inserted into the global field 'RC2FM_GLOBALS::API_Response__RC_Reply' In legacy WebDirect (version 15 and earlier) - No API response handling

Get Messages Function

Get Messages manages downloading of all incoming/outgoing message logs (sms, fax, voicemails) for the logged in user. Includes one execution Script: Execution Script: 'RC2FM__Function__GetMessages_SUBMIT ( param )'
Executes API call against 'msg' RC2FM endpoint

Parameters:
$dateFrom= {(optional defaults to previous 6 months) unix timestamp indicating starting date/time}
$$messageType={(optional, filters request by message type) acceptable values are "SMS" , "Fax", or "VoiceMail")}
$$direction={(optional, filters request by message direction) acceptable values are "Inbound" or "Outbound")}
$$readStatus={(optional, filters request by message status) acceptable values are "Read" , or "Unread")}

Get Call Log Function

Manages downloading of all incoming/outgoing call logs (including call recording ids)
for the logged in user. Includes one execution Script
Execution Script: 'RC2FM__Function__GetCallLog_SUBMIT ( param )'
Executes API call against RC2FM's 'calllog' endpoint

Get Call Log Pro Function

Manages downloading of all incoming/outgoing call logs (including call recording ids)
for all users under your RingCentral account.* Includes one execution Script
Execution Script: 'RC2FM__Function__GetCallLogPro_SUBMIT ( param )'
Executes API call against 'calllog_pro' RC2FM endpoint. *Requires authentication as the RingCentral superadmin or other account with RingCentral reporting access privileges.

Get Attachment Function

Get Attachment manages downloading of a single message attachement (fax or voicemail binary) from the logged in user's message store only. Includes one execution Script: Execution Script: 'RC2FM__Function__Fetch_Attachment ( param )'
Executes API call against 'get_attachments' RC2FM endpoint

Get Recording Function

Get Recording manages downloading of a single phone call recording from the logged in user's message store only.

Includes one execution Script
Execution Script: 'RC2FM__Function__Fetch_Recording'
Executes call to 'get_call_attachments' RC2FM API endpoint

Update "Read" Status Function

Update 'Read' Status manages the toggling of message status indicators between 'Read' and 'Unread'. Includes one execution Script:
Execution Script: 'RC2FM__Update_ReadStatus'
Executes API call against 'readstatus' RC2FM endpoint

OPERATIONS

Data Operations Summary

Data Operation Summary To facilitate the parsing of RingCentral API responses, the creation of FileMaker records, and the insertion of data into FileMaker fields, RC2FM Connector provides three (3) core data operations Scripts that virtually eliminate the need for additional data parsing/data handling routines:

Parse Message/Call Logs
Create Log records
Decode Base64 Binaries

1. Parse Message/Call Logs Parses RingCentral's message and call log data downloads. Manages data chunking and triggering of Script which creates and populates log records (local or Server Side {'Perform Script on Server'}). 2. Create Log records Loops thru message and call log download, creates records and populates fields. 3. Decode Base64 Binaries Decodes Base64 downloads (faxes, voicemails, call recordings) and stores them in container field in 'RC2FM_ATTACHMENTS' records.

Parse Message/Call Logs

Parses RingCentral's message and call log data downloads. Manages data chunking and triggering of Script which creates and populates log records (local or Server Side {'Perform Script on Server'}). Includes one execution Script: Execution Script: 'RC2FM__Operation__Parse_MessageLog
This Script performs the following data operations: A. Parses API response data from "Insert From URL' script step as stored in global field 'RC2FM_GLOBALS::API_Response__RC_download_log' B. Determines if FileMaker custom app is hosted on FileMaker Server and can execute remote procedure calls ('Perform Script On Server'). C. Determines if data needs to be chunked for submission to Create Log records Script.

Create Log Records

Loops thru message and call log downloads, inserts records into 'RC2M_LOGS' table, and populates matching fields. Includes two execution Scripts:
Execution Script: 'RC2FM__Operation__Create_MessageLog_Records ( param )'
This Script performs the following data operations: A. Parses Script parameter into name-spaced record values B. Parses record value into name-spaced field values. C. Creates log records and inserts data into matching field names . Calls subscript "RC2FM__Operation__Create_MessageAttachment_Records ( param )" as needed when MMS records are encountered.
Execution Subscript: 'RC2FM__Operation__Create_MessageAttachment_Records ( param )'
This Script performs the following data operations: A. Parses Script parameter into name-spaced record values B. Parses record value into name-spaced field values. C. Creates MMS attachment log records and inserts data into matching field names.

Decode Base64 Binaries

Decodes Base64 downloads (faxes, voicemails, call recordings) and stores them in container field as individual records in the 'RC2FM_ATTACHMENTS' table. Includes one execution Script:
Execution Script: 'RC2FM__Operation__Decode_Binary ( param )'
This Script performs the following data operations: A. Determines MIME type from content type field B. Assigns binary file name based on log record id C. Decodes Base64 file and inserts result into container field, with correct file type attributes.

SUPPORT

Known Issues

Currently there are no known issues. Previously, an older version of RingCentral's RingOut API was not handling the 'caller_id" parameter. This issue prevented users from specifying their caller id from their list of available phone numbers. RIngCentral has since resolved this with the introduction of a new endpoint and deprecation of the old. Effective immediately, all our subscribers may re-enable the 'caller_id' parameter in lines 31 and 41 of the script 'RC2FM__Function__RingOut__SUMBIT ( params)'.

Support Levels

Automation USA offers three (3) support levels to RC2FM Connector subscribers: Online Help Reference Docs, Email based support, and phone based support. Email based support is available to all subscribers at every subscription level. Phone based support is availble to subscribers with 5 users or more. Phone based level support is offered on a 12-24 hour call-back, depending on time zone. Email based support is offered on an asap basis. We will continue to update and revise the searchable Online Help documentation on an ongoing basis to maintain its relevance.

Contact Support

Email based support (subscribers only): rc2fm_support@automationusa.net Phone based support (subscribers with 5-users and above): 844-MY-RC2FM (697-2236) All other questions: rc2fm@automationusa.net