​

Configuring RD Station Conversas as a Source

​

1. Add account access

• Access token: Token used for authentication. Required. You can get it at Apps & Integrations > API > RD Station Conversas (developers.rdstation.com).
• Private key (JWK) for decryption: JWK (JSON Web Key) of the private key as a JSON string, used to decrypt conversation history. Optional. Generate it at Apps & Integrations > API > Generate Key (both the encryption feature and the history endpoint require the Advanced plan). See Conversas v2 encryption. Without it, the messages_history stream is skipped and its table is not updated; every other stream syncs normally.
• Initial sync date: Start of the period fetched. It affects the reports stream and messages_history, which is read from attendances — every other stream is always synced in full, because the API offers no date filter for them. When left empty, both streams fall back to the last 30 days. Choose an old date with care: conversation history is fetched one request per contact against a strict API rate limit, so the further back this goes, the longer the sync takes. Use YYYY-MM-DD. On an existing source, moving this date back to fetch older data only takes effect after a Full Sync, because regular runs resume from the last saved bookmark — see Backfilling and Initial sync date.
• Requests per minute: Maximum requests per minute sent to RD Station Conversas. Optional, defaults to 45. The API allows 100 requests per 120 seconds (50 a minute sustained) and reports the remaining budget on every response — the connector reads that budget and slows itself down on its own when it runs thin. Lower this if the account is shared with another integration.

​

2. Select streams

Tip: The stream can be found more easily by typing its name.

​

3. Configure data streams

• Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
• Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
• Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
• Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
  • Incremental: every time the extraction happens, we’ll get only the new data - which is good if, for example, you want to keep every record ever fetched. (Supported by the reports and messages_history streams)
  • Full table: every time the extraction happens, we’ll get the current state of the data - which is good if, for example, you don’t want to have deleted data in your catalog. (Used by all other streams in this connector)

​

4. Configure data source

• Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
• Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

​

5. Check your new source

​

Availability per plan

​

Streams and Fields

​

Available streams

​

Fields by stream

​

Data Model

​

Implementation Notes

​

Message history and encryption

• The messages_history stream returns responses encrypted with JWE (RSA-OAEP-256), so the Private key (JWK) is what makes them readable. The connector automatically normalizes different JWK shapes and cleans up invisible or look-alike spaces (often accidentally included when copying keys from a web page or chat app) to ensure the key can be correctly processed. Without a key, or with one that cannot decrypt the payload, the stream is completely skipped to avoid replacing good data with unreadable values.
• Malformed payloads: If the API returns invalid UTF-8 bytes or raw control characters in the conversation history, the connector automatically replaces the unreadable characters (with U+FFFD) or parses them leniently so the rest of the message can still be loaded. If a contact’s decrypted history is not valid JSON, that specific contact is skipped while the rest of the sync continues normally. However, to prevent wasting rate limits on broken API responses, if more than 50% of the payloads are unreadable after attempting at least 100 contacts, the connector will stop the stream part-way.

​

Backfilling and Initial sync date

• Initial sync date bounds the period of reports and messages_history. On the history endpoint it is sent together with an end date because the API requires the pair and otherwise falls back to the last 30 days.
• For reports, each run starts at the later of your Initial sync date and the bookmark saved by the previous run. Moving the start date forward takes effect immediately; moving it back changes nothing while a newer bookmark exists. To backfill older data, run a Full Sync so the state is cleared and the connector reads from the older date again. Because messages_history is read from the attendances reports returns, the same rule decides which contacts get their history fetched.

​

Child stream behavior

• messages_history is a child of reports (attendances). The tap first syncs the attendances of the requested period, then requests message history once for each distinct contact found in them — a contact with several attendances in the period is fetched only once per run. The number of requests therefore grows with the number of contacts who had an interaction in the window, not with the size of your contact base: the contacts listing has no date filter, so hanging the history off it would mean walking every contact on every run.

​

Reports stream behavior

• The stream supports incremental sync on created_at: it resumes from the previous run’s bookmark instead of rebuilding its whole history every run. The bookmark’s own day is re-read, because the period filter has day granularity and a run that stopped mid-day would otherwise lose the rest of it; the primary key settles the overlap. Only a completed run leaves a bookmark — an interrupted run re-reads its whole window next time.
• The /v4/reports endpoint rejects date ranges wider than 90 days, so the connector slices the requested period (from the later of Initial sync date and the bookmark, to today) into consecutive 89-day windows. If no start date is configured, or the configured date is in the future, it falls back to a 30-day lookback window.
• The API’s documentation is ambiguous about where the records live in the payload (reports vs docs), so the connector accepts both keys and logs which one actually arrived.

​

Pagination and page size

• The contacts and messages_history endpoints are fetched at 100 records per page — the documented ceiling on the history endpoint.
• For messages_history, since the endpoint provides no total records or pagination headers, the connector uses offset pagination and correctly pages through each contact’s history until it returns a page with fewer than 100 records.
• The reports endpoint rejects page sizes of 50 or more, so it is fetched at 49 records per page.

​

Rate limiting

• RD Station Conversas allows 100 requests per 120 seconds and publishes an IETF-style rate limit budget in its headers (RateLimit-Policy, RateLimit-Remaining and RateLimit-Reset). The connector observes these headers on every response and spreads the remaining budget over the rest of the window, so it neither wastes budget nor walks into the wall.
• Until a budget has been reported, the connector relies on the configured Requests per minute (45 by default). If a 429 still arrives, it honours Retry-After when present, waits, retries, and reports the slowdown once in the run log. Lower Requests per minute if the account is shared with another integration that spends the same quota.

​

Unavailable resources

• A stream the account cannot read is skipped with an explanation in the run log; the run continues and every other stream is synced. Its table is left as it was rather than being emptied.

​

Skills for agents