Before you start
- Create an API token in Tintim. In Tintim, open Tokens de API and create a token (it starts with
tintim_pat_). The secret is shown only once, so copy it right away. The token belongs to your Tintim user: it reads every account that user can access. - API v2 must be enabled on the account. Tintim enables API v2 access per account. If it is not enabled, the connection fails with a message saying so: ask Tintim support to enable API v2 for the account.
- Messages need two more things. To sync
lead_messages, message viewing must be enabled on the account and the token’s user must have accepted Tintim’s messaging terms of use for that account. - Some streams need management access.
tracking_linksandconversion_eventscan only be read by a user with management access to the account. Use a manager’s token or leave these streams out.
Configuring Tintim as a Source
In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Tintim option from the list of connectors. Click Next and you’ll be prompted to add your access.1. Add account access
The following configurations are available:- API token: The personal API token you created in Tintim (
tintim_pat_...). - Account codes: (Advanced, optional) Read only these Tintim accounts, by their code (UUID). Leave it empty to read every account the token’s user reaches that has API v2 enabled. Accounts without API v2 are skipped and listed in the run log; if an account that earlier syncs already read can no longer be read, the sync stops instead (see Troubleshooting). The codes are in the
accountstable after the first run.
2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis.Tip: The stream can be found more easily by typing its name.Select the streams and click Next.
3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.- 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 (recommended for
leads,lead_messages,lead_status_historyandlead_origin_history): the first run reads everything, and the next runs read only what changed in Tintim since the last one. - Full table: every run reads everything again. The configuration streams (
accounts,pipeline_stages,tracking_links,conversion_events) andsent_conversionsare always read in full.
- Incremental (recommended for
4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. Incremental runs are light, so hourly or daily runs work well. Optionally, you can define some additional settings:- 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. A full sync reads every lead and message again, which can take long on large accounts; a weekly or monthly one is enough.
5. Check your new source
You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.Streams and Fields
Available streams
The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description.
Every table carries
account_code, so one source can read several Tintim accounts. Attribution is flattened into origin_* columns.
leads.sale_amount holds only the last sale registered on a conversation. A lead that bought twice keeps only the second value there. For revenue, sum sale_amount_value in lead_status_history on the rows where leadstatus_is_sales is true.Removed leads and removed stage-history records stay in your tables with
is_active = false, so you can filter them out without losing track of what was removed.Fields by stream
Accounts
Accounts
Stream name:
accounts. One row per Tintim account in scope (every account the token reaches, or the configured subset).Sync Strategy:- Full table
- Primary key(s):
code
Leads
Leads
Stream name:
leads. One row per lead (WhatsApp conversation), with its current stage, sale value and attribution.Sync Strategy:- Incremental on
updated(removed leads are kept withis_active = false) - Primary key(s):
account_code,id
Lead messages
Lead messages
Stream name:
lead_messages. One row per WhatsApp message exchanged with a lead.Sync Strategy:- Incremental: messages are read for every lead the
leadsstream brings in the run - Primary key(s):
account_code,lead_id,message_id
Lead stage history
Lead stage history
Stream name:
lead_status_history. One row per stage change of a lead, sales included.Sync Strategy:- Incremental on
updated(removed records are kept withis_active = false) - Primary key(s):
account_code,id
Lead attribution history
Lead attribution history
Stream name:
lead_origin_history. One row per attribution record of a lead (which link, ad or UTM brought the conversation, from event_at on).Sync Strategy:- Incremental on
updated - Primary key(s):
account_code,id
Pipeline stages
Pipeline stages
Stream name:
pipeline_stages. One row per active stage of the buying journey, in funnel order.Sync Strategy:- Full table
- Primary key(s):
account_code,id
Tracking links
Tracking links
Stream name:
tracking_links. One row per active tracking link (click-to-WhatsApp link).Sync Strategy:- Full table
- Primary key(s):
account_code,id
Conversion events
Conversion events
Stream name:
conversion_events. One row per conversion event configured to be sent to Meta Ads or Google Ads.Sync Strategy:- Full table
- Primary key(s):
account_code,id
Sent conversions
Sent conversions
Stream name:
sent_conversions. One row per conversion the account sent to Meta Ads or Google Ads.Sync Strategy:- Full table
- Primary key(s):
account_code,id
Use cases
Revenue by Meta Ads campaign
Leads per day and source
Implementation Notes
- First run: reads every lead, stage change and attribution record of each account; with
lead_messagesselected it also reads the messages of every lead, one lead at a time. On large accounts the first run can take hours. Later runs read only what changed. - Later runs with
lead_messages: each run makes at least one request per lead with a message in the last 8 days or so. With 10,000 leads active in a week, a run takes roughly 35 to 70 minutes. Schedule this source every few hours (or daily) rather than hourly; if you need other tables more often, create a second Tintim source withoutlead_messages. - First-run checks: confirm that
accountsshowsapi_enabled = truefor your accounts, send a WhatsApp message to a test lead and check it inlead_messagesafter the next run, and check that a stage change appears inlead_status_history. - Rate limit: Tintim allows 600 requests per minute per Tintim user, shared by all of that user’s tokens and integrations (including Tintim’s MCP server). The connector uses at most about half of it (300 per minute) and waits when Tintim asks it to.
- Only active configuration rows: Tintim lists only active tracking links and pipeline stages, so a link that is deactivated or a stage that is removed disappears from
tracking_linksandpipeline_stageson the next run. - Messages on later runs: the connector reads the messages of every lead that changed since the last run and of every lead with a message in the 7 days before the last run, from the newest message back to that point. A message that reaches Tintim more than about 7 days after its own date, on a lead with no newer message, only arrives with a full sync. After the first runs, send a WhatsApp message to a test lead and check that it shows up in
lead_messagesafter the next run. - Metrics and creatives (dashboard aggregates and Meta Ads creative performance) are not synced: compute them from the tables above, or use the Meta Ads and Google Ads connectors.