RC2FM Help Docs
OVERVIEW
Current Version
Introduction
• 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.
2) Import (or copy/paste) all required scripts from our demo file;
3) Copy/paste the required layout objects from our demo file.
Supported platforms and versions
Requirements
Version history
XML source code:
https://github.com/Automation-USA/RC2FM/releases/tag/1.1.1
-
Support for cURL options in all API calls:
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]
XML source code: https://github.com/Automation-USA/RC2FM/releases/tag/1.1.0
-
New MMS functionality:
-
New Account-level call log reporting:
-
New Message log search parameters:
2. 'direction' = filter messages by direction (acceptable values are "Inbound", "Outbound")
3. 'readStatus' = filter messages by status (acceptable values are "Read", "Unread")
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:
---------------------------------------
'RC2FM_LOGS' table
added two (2) new text fields in support of mms attachments:
1. 'attachmentType'
2. 'mmscount'
1. 'size'
1. 'sizeCalc'
1. 'sms_message'
---------------------------------------
added one (1) new calculation field:
1. 'binaryCalc'
---------------------------------------
added one (1) global container field in support of MMS functionality:
1. 'MMS_Utility_Container'
1. '_kftg_attachment_id'
2. '_kftg_chat_phone'
3. 'Email_To'
---------------------------------------
Previous Version: 1.0.3 - released 12/12/2016
-
Enhanced extension level call log reporting:
- 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)
-
Schema and data parsing modifications:
-
Performance tuning for server-side Data Operations:
--------------------------------------
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.
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_SETTINGS (1 record)
• RC2FM_FAX_COVERS (14 records)
• RC2FM_LOGS (zero records)
• RC2FM_ATTACHMENTS (zero records)
All required Scripts contain the word "RC2FM" in their title. All required Scripts are also organized within a Script folder called "RC2M Modules [REQUIRED]".
(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.
Configuring your integration
2) Insert a call to the 'RC2FM__Config' Script into your 'OnFirstWindowOpen' script trigger.
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.
-
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.
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).
-
<field> script step errors. When pasting/importing into your custom app, be sure to review all RC2FM scripts for missing field references.
</field> -
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
Authentication
-
User name= Main company phone number + user's extension number; or -
User name= direct phone number (no extension number requried)
User name: 13055551212
Extension: 123
Password: RC2FM_rocks!
User name: 17865512008
Extension: [leave blank]
Password: RC2FM_rocks!
Session Control
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.
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.
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.
-
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
RC2FM requires all transmissions take place over port 443 (https) using SSL certificate verification.
RC2FM requires all parameter values be Base64 Encoded.
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+
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
Faxing:
RingCentral's FaxOut API renders 1-bit images to be transmitted via fax and supports the following file formats/media types:
API Reference Guide (Endpoints)
'login'
Session authentication
https://{BaseURL}/api/login.php?
-
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'
Session termination
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'
Check for active session token
https://{BaseURL}/api/get_token.php?
-
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'
Upload outgoing fax
https://{BaseURL}/api/v1.php?action=fax_base64?
-
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'
Initiate outgoing phone call
https://{BaseURL}/api/v1.php?action=ringout?
-
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)
Heavy
'sms'
Send outgoing sms or mms message
https://{BaseURL}/api/v1.php?action=sms?
-
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)
Medium
'msg'
Download all message logs (mms, sms, fax, voicemail)
https://{BaseURL}/msg.php?
-
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)
Heavy
'calllog'
Download all extension-level call logs (with call recording record ids)
RC2FM Endpoint:
https://{BaseURL}/calllog.php?
-
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: <null>(leave blank), "all", and specific phone number in E164 format (numeric only)}</null> -
dateFrom={optional, unix timestamp indicating starting date/time} -
environment parameters (see below)
Heavy
'calllog_pro'
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?
-
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)
Heavy
'get_attachments'
Download a single message attachment (fax or voicemail file)
https://{BaseURL}/get_attachments.php?
-
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)
Medium
'get_call_attachments'
Download a single call recording
https://{BaseURL}/get_call_attachments.php?
-
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)
Heavy
'readstatus'
Changes the status flag of a message from 'Unread' to 'Read'
https://{BaseURL/readstatus.php?
-
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)
Medium
environment parameters
Session control parameters, required by most RC2FM Connector API calls
-
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}
N/A
API Responses
Manages downloading of all incoming/outgoing call logs (including call recording ids) Manages downloading of all incoming/outgoing call logs (including call recording ids)
Get Recording manages downloading of a single phone call recording from the logged in user's message store only.
RC2FM Connector
"extensionNumber" : "(your telephone extension number)"
'get_token' success
:
RC2FM Connector
{
------------------
'logout' success
:
RC2FM Connector
'fax_base64' success:
RingCentral API endpoint
'ringout' success:
RingCentral API endpoint
'sms' success:
RingCentral API endpoint
RC2FM error messages:
RC2FM Connector
Maximum number of device connections per user has been exceeded.
{
RC2FM Connector
Maximum number of subscribers purchased has been exceeded.
{"error":200,"message":"Concurrent login on same device denied."}
RC2FM Connector
Only one user session per device is allowed.
{
RC2FM Connector
Device session has been idle for too long and token has been expired.
FUNCTIONS
Functions Summary
FaxOut Function
Handler Script 1: 'RC2FM__FaxOut ( chooseFile )'
Manages uploading of user selected fax documents from file system
$$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}
$result={Get (ScriptResult) from call to execution Script}
Handler Script 2: 'RC2FM__FaxOut ( selectedContainer)'
Manages uploading of user selected container field
$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}
$result={Get (ScriptResult) from call to execution Script}
Validates fax documents against supported MIME types and file size restrictions
$fileName={document file name (trimmed of special characters)}
$$mimeType={fax document's MIME type}
$$fileContainer={fully qualified container field name to be faxed}
$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
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
Execution Script: 'RC2FM__Function__RingOut_SUBMIT ( params )'
Executes API call against 'ringout' RC2FM endpoint
$$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)}*
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!
SMS/MMS Function
Execution Script: 'RC2FM__Function__MMS_SUBMIT ( params )'
Executes API call aginst 'sms' RC2FM endpoint
$$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)}
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
Executes call against 'sms' RC2FM API endpoint with no MMS attachment handling
$$smsTo={Destination phone number (only digits, or E164)}
$$message={sms message body}
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'
Get Messages Function
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
for the logged in user.
Execution Script: 'RC2FM__Function__GetCallLog_SUBMIT ( param )'
Executes API call against RC2FM's 'calllog' endpoint
Get Call Log Pro Function
for all users under your RingCentral account.*
Execution Script: 'RC2FM__Function__GetCallLogPro_SUBMIT ( param )'
Executes API call against 'calllog_pro' RC2FM endpoint.
Get Attachment Function
Executes API call against 'get_attachments' RC2FM endpoint
Get Recording Function
Includes one execution Script
Execution Script: 'RC2FM__Function__Fetch_Recording'
Executes call to 'get_call_attachments' RC2FM API endpoint
Update "Read" Status Function
Execution Script: 'RC2FM__Update_ReadStatus'
Executes API call against 'readstatus' RC2FM endpoint
OPERATIONS
Data Operations Summary
Parse Message/Call Logs
Create Log Records
Execution Script: 'RC2FM__Operation__Create_MessageLog_Records ( param )'
This Script performs the following data operations:
Execution Subscript: 'RC2FM__Operation__Create_MessageAttachment_Records ( param )'
Decode Base64 Binaries
Execution Script: 'RC2FM__Operation__Decode_Binary ( param )'
This Script performs the following data operations:
SUPPORT
Known Issues
Support Levels
Contact Support
