Skip to main content
Tintim tracks the WhatsApp conversations of a business and attributes each one to the link, ad or campaign that started it. The Nekt connector reads Tintim’s API (v2) and brings your leads, their WhatsApp messages, every stage change of the buying journey (sales included), the attribution history, the journey stages, tracking links and the conversions sent to Meta Ads and Google Ads into your Catalog.

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_links and conversion_events can 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 accounts table after the first run.
Once you’re done, click Next.

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_history and lead_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) and sent_conversions are always read in full.
Once you are done configuring, click Next.

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.
Once you are ready, click Next to finalize the setup.

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.
For you to be able to see it on your Catalog, you need at least one successful source run.

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

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
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 with is_active = false)
  • Primary key(s): account_code, id
Stream name: lead_messages. One row per WhatsApp message exchanged with a lead.Sync Strategy:
  • Incremental: messages are read for every lead the leads stream brings in the run
  • Primary key(s): account_code, lead_id, message_id
Stream name: lead_status_history. One row per stage change of a lead, sales included.Sync Strategy:
  • Incremental on updated (removed records are kept with is_active = false)
  • Primary key(s): account_code, id
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
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
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
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_messages selected 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 without lead_messages.
  • First-run checks: confirm that accounts shows api_enabled = true for your accounts, send a WhatsApp message to a test lead and check it in lead_messages after the next run, and check that a stage change appears in lead_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_links and pipeline_stages on 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_messages after 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.

Troubleshooting