RingCentral feature snapshot

A high-level look at Stitch's RingCentral (v1) integration, including release status, useful links, and the features supported in Stitch.

STITCH
Release status

Released on August 23, 2019

 Supported by

Singer Community
Stitch plan

Standard

 API availability

Available
Singer GitHub repository

singer-io/tap-ringcentral
REPLICATION SETTINGS
Anchor Scheduling

Supported

 Advanced Scheduling

Supported
Table-level reset

Unsupported

 Configurable Replication Methods

Unsupported
DATA SELECTION
Table selection

Supported

 Column selection

Supported
Select all

Supported
TRANSPARENCY
Extraction Logs

Supported

 Loading Reports

Supported

Connecting RingCentral

Step 1: Generate RingCentral credentials

Step 1.1: Create a RingCentral developer application

In this step, you’ll create a RingCentral developer application.

  1. Navigate to the RingCentral Developer Console.
  2. Create a free account, if you don’t already have one.
  3. After you’ve created an account and logged in, click the Create App button.

RingCentral App Type & Platform window for creating a developer app.

  1. In the window that displays, enter a name and description for the app.
  2. In the App Type & Platform window, fill in the fields as follows:
    • Application Type: Select Private.
    • Platform Type: Select Server-only (No UI).
  3. Click Next.

RingCentral OAuth Settings window for creating a developer app.

  1. Next, you’ll grant permissions to the app. In the Permissions Needed field, select the following:
    • Read Accounts
    • Read Call Log
    • Read Messages
  2. Click Create.

Step 1.2: Retrieve application credentials

After your application is created, you’ll retrieve its credentials.

  1. On the Apps page, click the developer application you created in the previous step.
  2. Click the Credentials option in the menu on the left side of the page.

RingCentral Application Credentials page with the Production Environment column highlighted.

  1. In the Application Credentials section, locate the following in the Production Environment column:

    • API Server URL
    • Client ID
    • Client Secret

Keep this page handy for now - you’ll need it to complete the setup in Stitch.

Step 2: Add RingCentral as a Stitch data source

  1. Sign into your Stitch account.

  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the RingCentral icon.

  4. Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.

    For example, the name “Stitch RingCentral” would create a schema called stitch_ringcentral in the destination. Note: Schema names cannot be changed after you save the integration.

  5. In the Client ID field, enter the Client ID from Step 1.2.
  6. In the Client Secret field, enter the Client Secret from Step 1.2.
  7. In the Username field, enter the username for the RingCentral developer app. This is typically the phone number used to create the app.
  8. In the Password field, enter the password for the RingCentral developer app.
  9. In the API URL field, enter the API Server URL from Step 1.2.

Step 3: Define the historical replication start date

The Sync Historical Data setting defines the starting date for your RingCentral integration. This means that:

  • For tables using Key-based Incremental Replication, data equal to or newer than this date will be replicated to your destination.
  • For tables using Full Table Replication, all data - including records that are older, equal to, or newer than this date - will be replicated to your destination.

Change this setting if you want to replicate data beyond RingCentral’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.

Step 4: Create a replication schedule

In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.

RingCentral integrations support the following replication scheduling methods:

To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.

Step 5: Set objects to replicate

The last step is to select the tables and columns you want to replicate. Learn about the available tables for this integration.

Note: If a replication job is currently in progress, new selections won’t be used until the next job starts.

For RingCentral integrations, you can select:

  1. Individual tables and columns

  2. All tables and columns

Click the tabs to view instructions for each selection method.

  1. In the integration’s Tables to Replicate tab, locate a table you want to replicate.

  2. To track a table, click the checkbox next to the table’s name. A blue checkmark means the table is set to replicate.

  3. To track a column, click the checkbox next to the column’s name. A blue checkmark means the column is set to replicate.

  4. Repeat this process for all the tables and columns you want to replicate.
  5. When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.
  1. Click into the integration from the Stitch Dashboard page.

  2. Click the Tables to Replicate tab.

  3. In the list of tables, click the box next to the Table Names column.

  4. In the menu that displays, click Track all Tables and Fields:

    The Track all Tables and Fields menu in the Tables to Replicate tab

  5. Click the Finalize Your Selections button at the bottom of the page to save your data selections.

Initial and historical replication jobs

After you finish setting up RingCentral, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.

RingCentral table reference

call_log

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

dateFrom : dateTo

Primary Key :

id

 API endpoint :

Get User Call Log Records

The call_log contains info about your call logs.

call_log table schema

id
STRING

The call log record ID.

_contact_id
INTEGER

Reference:

action
STRING

The type of call operation.

deleted
ANYTHING

Deleted calls. This value will return ‘True’ only if a call was deleted.

direction
STRING

The call direction - inbound or outbound.

duration
INTEGER

The duration of the call recorded, in seconds.

extension
OBJECT

The extension of the person a call was made on behalf of.

Click to expand extension

id
INTEGER

The internal ID of the caller extension.

uri
STRING

The link to the extension.
call_log (table), extension (attribute)

from
OBJECT

The caller.

Click to expand from

extensionId
STRING

The internal extension ID.

location
STRING

The city of the caller’s area code, if the phoneNumber field is not empty.

name
STRING

The name of the caller.

phoneNumber
STRING

The caller’s phone number.
call_log (table), from (attribute)

message
ANYTHING

The linked voicemail/fax message.

Click to expand message

id
STRING

The message ID.

Reference:

type
STRING

The type of the message.

uri
STRING

Link to the message resource.
call_log (table), message (attribute)

reason
ANYTHING

The reason of a call result.

reasonDescription
ANYTHING

result
STRING

The status of the call operation.

sessionId
STRING

The call session ID.

Reference:

startTime
DATE-TIME

The start datetime of a call. This value is in ISO 8601 format, including the timezone.

to
OBJECT

The callee.

Click to expand to

extensionId
STRING

The internal extension ID.

location
STRING

The city of the callee’s area code, if the phoneNumber field is not empty.

name
STRING

The name of the callee.

phoneNumber
STRING

The callee’s phone number.
call_log (table), to (attribute)

type
STRING

The call type - voice or fax.

uri
STRING

The canonical URI of a call log record.

company_call_log

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

dateFrom : dateTo

Primary Key :

id

 API endpoint :

Get Company Call Log Records

The company_call_log contains info about company call log records.

company_call_log table schema

id
STRING

The call log record ID.

_contact_id
INTEGER

The contact ID.

Reference:

action
STRING

The type of call operation.

deleted
ANYTHING

Deleted calls. This value will return ‘True’ only if a call was deleted.

direction
STRING

The call direction - inbound or outbound.

duration
INTEGER

The duration of the call recorded, in seconds.

extension
OBJECT

The extension of the person a call was made on behalf of.

Click to expand extension

id
INTEGER

The internal ID of the caller extension.

uri
STRING

The link to the extension.
company_call_log (table), extension (attribute)

from
OBJECT

The caller.

Click to expand from

location
STRING

The city of the caller’s area code, if the phoneNumber field is not empty.

name
STRING

The name of the caller.

phoneNumber
STRING

The caller’s phone number.
company_call_log (table), from (attribute)

message
ANYTHING

The linked voicemail/fax message.

Click to expand message

id
STRING

The message ID.

Reference:

type
STRING

The type of the message.

uri
STRING

Link to the message resource.
company_call_log (table), message (attribute)

reason
ANYTHING

The reason of a call result. Refer to RingCentral’s documentation for a list of possible values.

reasonDescription
ANYTHING

result
STRING

The status of the call operation.

sessionId
STRING

The call session ID.

Reference:

startTime
DATE-TIME

The start datetime of a call. This value is in ISO 8601 format, including the timezone.

to
OBJECT

The callee.

Click to expand to

location
STRING

The city of the callee’s area code, if the phoneNumber field is not empty.

name
STRING

The name of the callee.

phoneNumber
STRING

The callee’s phone number.
company_call_log (table), to (attribute)

type
STRING

The call type - voice or fax.

uri
STRING

The canonical URI of a call log record.

contacts

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

id
API endpoint :

Get Corporate Directory Entry

The contacts contains info about corporate users of federated accounts.

contacts table schema

id
INTEGER

The contact ID.

Reference:

account
OBJECT

Details about the owning account.

Click to expand account

id
INTEGER

The owning account ID.
contacts (table), account (attribute)

email
STRING

The contact’s email address.

extensionNumber
INTEGER

The contact’s phone number extension.

firstName
STRING

The contact’s first name.

jobTitle
STRING

The contact’s job title.

lastName
STRING

The contact’s last name.

name
STRING

The contact’s name, for non-user extensions.

phoneNumbers
ARRAY

The contact’s phone numbers.

Click to expand phoneNumbers

phoneNumber
STRING

The phone number.

type
STRING

The phone number type.

usageType
STRING

The phone number’s category.
contacts (table), phoneNumbers (attribute)

status
STRING

The contact’s status.

type
STRING

The contact’s type.

messages

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

dateFrom : dateTo

Primary Key :

id : conversationId

 API endpoint :

Get Message List

The messages contains info about an extension mailbox’s messages.

messages table schema

id
STRING

The message ID.

Reference:

conversationId
ANYTHING

The conversation ID.

_contact_id
INTEGER

The contact ID.

Reference:

attachments
ANYTHING

The list of message attachments.

Click to expand attachments

id
STRING

The attachment ID.

uri
STRING

Canonical URI of a message attachment.

type
STRING

The type of message attachment. Possible values are:

  • AudioRecording
  • AudioTranscription
  • Text
  • SourceDocument
  • RenderedDocument
  • MmsAttachment

contentType
STRING

MIME type for a given attachment, for instance ‘audio/wav’.

vmDuration
INTEGER

Supported for Voicemail only. Duration of a voicemail in seconds.

filename
STRING

The name of the attached file.

size
INTEGER

The size of the attachment, in bytes.
messages (table), attachments (attribute)

availability
STRING

The message availability status.

conversation
ANYTHING

SMS and Pager only. Details about the conversation the message belongs to.

Click to expand conversation

id
STRING

The conversation ID.
messages (table), conversation (attribute)

coverIndex
INTEGER

creationTime
DATE-TIME

The datetime of when the message was created. This value is in ISO 8601 format, including the timezone.

deleted
ANYTHING

Indicates if the message has been deleted.

direction
STRING

The direction of the message. Possible values are:

  • inbound
  • outbound

faxPageCount
INTEGER

The page count of a fax message.

faxResolution
STRING

The resolution of a fax message. Possible values are:

  • high
  • low

from
OBJECT

The sender.

Click to expand from

extensionNumber
STRING

Extension short number (usually 3 or 4 digits). This property is filled when parties communicate by means of short internal numbers, for example when calling to other extension or sending/receiving Company Pager message.

messageStatus
STRING

Status of a message. Returned for outbound fax messages only. Possible values are:

  • Queued
  • Sent
  • Delivered
  • DeliveryFailed
  • SendingFailed
  • Received

faxErrorCode
STRING

Fax only. Error code returned in case of fax sending failure. Returned if messageStatus: SendingFailed.

Possible values are:

  • InternationalCallingDisabled
  • DestinationCountryDisabled
  • NoAnswer
  • LineBusy
  • CallerHungUp
  • UnknownCountryCode
  • InvalidNumber
  • NotAccepted
  • CallDeclined
  • TooManyCallsPerLine
  • NotEnoughCredits
  • SentPartially
  • CallFailed

location
STRING

Contains party location (city, state) if one can be determined from phoneNumber. This property is filled only when phoneNumber is not empty and server can calculate location information from it (for example, this information is unavailable for US toll-free numbers).

name
STRING

Symbolic name associated with a party. If the phone does not belong to the known extension, only the location is returned, the name is not determined.

phoneNumber
STRING

Phone number of a party. Usually it is a plain number including country and area code like 18661234567. But sometimes it could be returned from database with some formatting applied, for example (866)123-4567. This property is filled in all cases where parties communicate by means of global phone numbers, for example when calling to direct numbers or sending/receiving SMS.
messages (table), from (attribute)

lastModifiedTime
DATE-TIME

The datetime of when the message was last modified. This value is in ISO 8601 format, including the timezone.

messageStatus
STRING

The message’s delivery status. Possible values are:

  • Queued
  • Sent
  • Delivered
  • DeliveryFailed
  • SendingFailed
  • Received

priority
STRING

The message priority - normal or high.

readStatus
STRING

The read status of a message - read or unread.

smsSendingAttemptsCount
ANYTHING

The number of attempts made to send an outbound SMS.

subject
ANYTHING

The message subject.

to
ANYTHING

The recipient’s information.

Click to expand to

extensionNumber
STRING

Extension short number (usually 3 or 4 digits). This property is filled when parties communicate by means of short internal numbers, for example when calling to other extension or sending/receiving Company Pager message.

messageStatus
STRING

Status of a message. Returned for outbound fax messages only. Possible values are:

  • Queued
  • Sent
  • Delivered
  • DeliveryFailed
  • SendingFailed
  • Received

faxErrorCode
STRING

Fax only. Error code returned in case of fax sending failure. Returned if messageStatus: SendingFailed.

Possible values are:

  • InternationalCallingDisabled
  • DestinationCountryDisabled
  • NoAnswer
  • LineBusy
  • CallerHungUp
  • UnknownCountryCode
  • InvalidNumber
  • NotAccepted
  • CallDeclined
  • TooManyCallsPerLine
  • NotEnoughCredits
  • SentPartially
  • CallFailed

location
STRING

Contains party location (city, state) if one can be determined from phoneNumber. This property is filled only when phoneNumber is not empty and server can calculate location information from it (for example, this information is unavailable for US toll-free numbers).

name
STRING

Symbolic name associated with a party. If the phone does not belong to the known extension, only the location is returned, the name is not determined.

phoneNumber
STRING

Phone number of a party. Usually it is a plain number including country and area code like 18661234567. But sometimes it could be returned from database with some formatting applied, for example (866)123-4567. This property is filled in all cases where parties communicate by means of global phone numbers, for example when calling to direct numbers or sending/receiving SMS.
messages (table), to (attribute)

type
STRING

The message type.

uri
STRING

vmTranscriptionStatus
ANYTHING

Voicemail only. Status of voicemail to text transcription. If VoicemailToText feature is not activated for account, the NotAvailable value is returned. Possible values are:

  • NotAvailable
  • InProgress
  • TimedOut
  • Completed
  • CompletedPartially
  • Failed
Related Troubleshooting
Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.