> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tintim as a data source

> Bring leads, WhatsApp messages, stage changes, sales and attribution from Tintim to Nekt.

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](https://app.nekt.ai/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](#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](https://docs.nekt.com/runs/scheduling-and-triggers.md), 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](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#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](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/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.

| Stream | Slug | Description |
| - | - | - |
| Accounts | `accounts` | The Tintim accounts in scope, with whether API v2 and message reading are enabled on each. |
| Leads | `leads` | Every lead (WhatsApp conversation): contact, current stage, current sale value and attribution (link, Meta Ads, Google Ads, UTMs, click ids). |
| Lead messages | `lead_messages` | The WhatsApp messages exchanged with each lead. |
| Lead stage history | `lead_status_history` | Every stage change of every lead, with the sale value on sales stages. Use it for revenue. |
| Lead attribution history | `lead_origin_history` | Every attribution record of every lead, as it applied from the moment it started. |
| Pipeline stages | `pipeline_stages` | The stages of the buying journey, in funnel order, with their default sale value. |
| Tracking links | `tracking_links` | The active tracking links (click-to-WhatsApp links) and their URLs. Needs management access. |
| Conversion events | `conversion_events` | The conversion events configured to be sent to Meta Ads and Google Ads. Needs management access. |
| Sent conversions | `sent_conversions` | Every conversion the account sent to Meta Ads and Google Ads, with its dispatch status. |

Every table carries `account_code`, so one source can read several Tintim accounts. Attribution is flattened into `origin_*` columns.

> [!NOTE]
>
> `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.

> [!NOTE]
>
> 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

> [accordion] 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`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `code` | String | Code (UUID) of the Tintim account; account\_code in the other streams. |
> | `name` | String | Name of the account. |
> | `is_active` | Boolean | Whether the account is active (a deactivated account cannot be read). |
> | `is_trial` | Boolean | Whether the account is in its trial period. |
> | `access_type` | String | Type of access the token's user has to the account. |
> | `api_enabled` | Boolean | Whether Tintim API v2 is enabled on the account (required to read it). |
> | `messages_readable` | Boolean | Whether the token's user can read the account's WhatsApp messages (needed by lead\_messages). |
> | `messages_blocked_reason` | String | Why messages cannot be read: feature\_not\_enabled or messaging\_terms\_not\_accepted (null when readable). |
> | `workspace_is_active` | Boolean | Whether the account's Tintim workspace is active. |
> | `workspace_code` | String | Code (UUID) of the workspace the account belongs to. |
> | `wpp_store_phone` | String | WhatsApp number that serves the account's customers. |
> | `connection_status` | Boolean | WhatsApp connection: true connected, false disconnected, null when no number was ever connected. |

> [accordion] 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 with `is_active = false`)
> * Primary key(s): `account_code`, `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `account_code` | String | Code (UUID) of the Tintim account the record belongs to. |
> | `id` | Integer | Unique identifier of the lead (conversation) in Tintim. |
> | `name` | String | Name of the lead, as known by Tintim (may be null). |
> | `phone` | String | WhatsApp phone number of the lead. |
> | `source` | String | Declared source of the lead: google, meta, unknown or untracked. |
> | `status_id` | Integer | Id of the lead's current stage in the buying journey (see pipeline\_stages). |
> | `status_name` | String | Name of the lead's current stage in the buying journey. |
> | `sale_amount` | Number | Sale value currently registered on the conversation (manual entry or the stage's default value; 0 while none is registered). Only the LAST sale of a lead that bought more than once: do not sum it for revenue, sum lead\_status\_history.sale\_amount\_value on sales rows instead. |
> | `first_message_datetime` | Datetime | When the first message of the conversation was exchanged (UTC). |
> | `last_message_datetime` | Datetime | When the last message of the conversation was exchanged (UTC). |
> | `last_status_change_datetime` | Datetime | When the lead last changed stage (UTC). |
> | `first_response_status` | String | Status of the first response to the lead, as computed by Tintim. |
> | `created` | Datetime | When the lead was created in Tintim (UTC). |
> | `updated` | Datetime | When the lead was last written in Tintim (UTC); also moves on Tintim's internal rewrites. Used as the incremental replication key. |
> | `is_active` | Boolean | False when the conversation was removed from the account (removed leads are kept, flagged). |
> | `origin_campaign_id` | String | Attribution (current attribution of the lead): Id of the Tintim tracking link the lead came through (null when the conversation did not start from a tracking link click). |
> | `origin_campaign_name` | String | Attribution (current attribution of the lead): Name of the Tintim tracking link, as shown on the tracking links screen. |
> | `origin_meta_ad_account_id` | String | Attribution (current attribution of the lead): Id of the Meta Ads ad account that paid for the ad. |
> | `origin_meta_ad_account_name` | String | Attribution (current attribution of the lead): Name of the Meta Ads ad account. |
> | `origin_meta_campaign_id` | String | Attribution (current attribution of the lead): Id of the Meta Ads campaign that brought the lead. |
> | `origin_meta_campaign_name` | String | Attribution (current attribution of the lead): Name of the Meta Ads campaign. |
> | `origin_meta_adset_id` | String | Attribution (current attribution of the lead): Id of the Meta Ads ad set. |
> | `origin_meta_adset_name` | String | Attribution (current attribution of the lead): Name of the Meta Ads ad set. |
> | `origin_meta_ad_id` | String | Attribution (current attribution of the lead): Id of the Meta Ads ad that brought the lead. |
> | `origin_meta_ad_name` | String | Attribution (current attribution of the lead): Name of the Meta Ads ad (the creative the person saw). |
> | `origin_google_campaign_id` | String | Attribution (current attribution of the lead): Id of the Google Ads campaign that brought the lead. |
> | `origin_google_campaign_name` | String | Attribution (current attribution of the lead): Name of the Google Ads campaign. |
> | `origin_google_adgroup_id` | String | Attribution (current attribution of the lead): Id of the Google Ads ad group. |
> | `origin_google_adgroup_name` | String | Attribution (current attribution of the lead): Name of the Google Ads ad group. |
> | `origin_google_ad_id` | String | Attribution (current attribution of the lead): Id of the Google Ads ad that brought the lead. |
> | `origin_google_ad_name` | String | Attribution (current attribution of the lead): Name of the Google Ads ad. |
> | `origin_utm_source` | String | Attribution (current attribution of the lead): utm\_source of the click that started the conversation (tracking link visit or form page). |
> | `origin_utm_medium` | String | Attribution (current attribution of the lead): utm\_medium of the click that started the conversation. |
> | `origin_utm_campaign` | String | Attribution (current attribution of the lead): utm\_campaign URL parameter of the click (unrelated to the tracking link or the ad campaign). |
> | `origin_utm_term` | String | Attribution (current attribution of the lead): utm\_term of the click that started the conversation. |
> | `origin_utm_content` | String | Attribution (current attribution of the lead): utm\_content of the click that started the conversation. |
> | `origin_gclid` | String | Attribution (current attribution of the lead): Google Ads click identifier captured when the lead arrived (used to send conversions back to Google Ads). |
> | `origin_wbraid` | String | Attribution (current attribution of the lead): Google click identifier used instead of gclid for app-to-web clicks on iOS. |
> | `origin_gbraid` | String | Attribution (current attribution of the lead): Aggregated Google click identifier sent on iOS clicks. |
> | `origin_fbclid` | String | Attribution (current attribution of the lead): Meta click identifier captured when the lead arrived. |
> | `origin_ctwa_clid` | String | Attribution (current attribution of the lead): Click-to-WhatsApp ad click identifier, present when the conversation started from the ad's button. |
> | `origin_contact_method` | String | Attribution (current attribution of the lead): How the conversation started: 'whatsapp' (the lead wrote on WhatsApp) or 'form' (the lead came from a form). |

> [accordion] 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 `leads` stream brings in the run
> * Primary key(s): `account_code`, `lead_id`, `message_id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `account_code` | String | Code (UUID) of the Tintim account the record belongs to. |
> | `lead_id` | Integer | Id of the lead (conversation) the message belongs to. |
> | `message_id` | String | Identifier of the WhatsApp message. |
> | `message` | String | Text content of the message. |
> | `from_me` | Boolean | Direction: true when the account sent it, false when the lead wrote it, null when unknown. |
> | `message_datetime` | Datetime | When the message was sent or received (UTC). |
> | `lead_updated` | Datetime | The lead's 'updated' value when its messages were read (copied from leads). Used as the incremental replication key. |

> [accordion] 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 with `is_active = false`)
> * Primary key(s): `account_code`, `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `account_code` | String | Code (UUID) of the Tintim account the record belongs to. |
> | `id` | Integer | Unique identifier of the stage-change record. |
> | `lead_id` | Integer | Id of the lead (conversation) that changed stage. |
> | `leadstatus_name` | String | Name of the stage the lead moved to. |
> | `leadstatus_is_sales` | Boolean | Whether the stage the lead moved to is a sale. |
> | `current_status_id` | Integer | Id of the stage the lead moved to (see pipeline\_stages). |
> | `previous_status_id` | Integer | Id of the stage the lead left (null on the lead's first stage). |
> | `previous_status_name` | String | Name of the stage the lead left (null on the lead's first stage). |
> | `sale_amount_value` | Number | Sale value when the row is a sale (leadstatus\_is\_sales = true); on other rows it repeats the value in force on the conversation. Revenue of a period = sum of this field on sales rows. |
> | `change_method` | String | How the stage changed: m (manual), a (automatic), i (integration) or d (smart detection). |
> | `change_datetime` | Datetime | When the stage change happened (UTC). |
> | `changed_by_email` | String | E-mail of the user who made the change, when manual. |
> | `tracking_id` | Integer | Id of the attribution record in force at the time of the change (see lead\_origin\_history.id). |
> | `updated` | Datetime | When the record was last written in Tintim (UTC). Used as the incremental replication key. |
> | `is_active` | Boolean | False when the record was removed from the lead's history. |

> [accordion] 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`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `account_code` | String | Code (UUID) of the Tintim account the record belongs to. |
> | `id` | Integer | Unique identifier of the attribution record; equals lead\_status\_history.tracking\_id. |
> | `lead_id` | Integer | Id of the lead (conversation) the attribution belongs to. |
> | `event_at` | Datetime | When this attribution started to apply, usually the message that brought it (UTC; may be null). |
> | `updated` | Datetime | When the record was last written in Tintim (UTC). Used as the incremental replication key. |
> | `origin_campaign_id` | String | Attribution (in force from event\_at on): Id of the Tintim tracking link the lead came through (null when the conversation did not start from a tracking link click). |
> | `origin_campaign_name` | String | Attribution (in force from event\_at on): Name of the Tintim tracking link, as shown on the tracking links screen. |
> | `origin_meta_ad_account_id` | String | Attribution (in force from event\_at on): Id of the Meta Ads ad account that paid for the ad. |
> | `origin_meta_ad_account_name` | String | Attribution (in force from event\_at on): Name of the Meta Ads ad account. |
> | `origin_meta_campaign_id` | String | Attribution (in force from event\_at on): Id of the Meta Ads campaign that brought the lead. |
> | `origin_meta_campaign_name` | String | Attribution (in force from event\_at on): Name of the Meta Ads campaign. |
> | `origin_meta_adset_id` | String | Attribution (in force from event\_at on): Id of the Meta Ads ad set. |
> | `origin_meta_adset_name` | String | Attribution (in force from event\_at on): Name of the Meta Ads ad set. |
> | `origin_meta_ad_id` | String | Attribution (in force from event\_at on): Id of the Meta Ads ad that brought the lead. |
> | `origin_meta_ad_name` | String | Attribution (in force from event\_at on): Name of the Meta Ads ad (the creative the person saw). |
> | `origin_google_campaign_id` | String | Attribution (in force from event\_at on): Id of the Google Ads campaign that brought the lead. |
> | `origin_google_campaign_name` | String | Attribution (in force from event\_at on): Name of the Google Ads campaign. |
> | `origin_google_adgroup_id` | String | Attribution (in force from event\_at on): Id of the Google Ads ad group. |
> | `origin_google_adgroup_name` | String | Attribution (in force from event\_at on): Name of the Google Ads ad group. |
> | `origin_google_ad_id` | String | Attribution (in force from event\_at on): Id of the Google Ads ad that brought the lead. |
> | `origin_google_ad_name` | String | Attribution (in force from event\_at on): Name of the Google Ads ad. |
> | `origin_utm_source` | String | Attribution (in force from event\_at on): utm\_source of the click that started the conversation (tracking link visit or form page). |
> | `origin_utm_medium` | String | Attribution (in force from event\_at on): utm\_medium of the click that started the conversation. |
> | `origin_utm_campaign` | String | Attribution (in force from event\_at on): utm\_campaign URL parameter of the click (unrelated to the tracking link or the ad campaign). |
> | `origin_utm_term` | String | Attribution (in force from event\_at on): utm\_term of the click that started the conversation. |
> | `origin_utm_content` | String | Attribution (in force from event\_at on): utm\_content of the click that started the conversation. |
> | `origin_gclid` | String | Attribution (in force from event\_at on): Google Ads click identifier captured when the lead arrived (used to send conversions back to Google Ads). |
> | `origin_wbraid` | String | Attribution (in force from event\_at on): Google click identifier used instead of gclid for app-to-web clicks on iOS. |
> | `origin_gbraid` | String | Attribution (in force from event\_at on): Aggregated Google click identifier sent on iOS clicks. |
> | `origin_fbclid` | String | Attribution (in force from event\_at on): Meta click identifier captured when the lead arrived. |
> | `origin_ctwa_clid` | String | Attribution (in force from event\_at on): Click-to-WhatsApp ad click identifier, present when the conversation started from the ad's button. |
> | `origin_contact_method` | String | Attribution (in force from event\_at on): How the conversation started: 'whatsapp' (the lead wrote on WhatsApp) or 'form' (the lead came from a form). |

> [accordion] 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`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `account_code` | String | Code (UUID) of the Tintim account the record belongs to. |
> | `id` | Integer | Unique identifier of the stage (status\_id / current\_status\_id elsewhere). |
> | `name` | String | Name of the stage. |
> | `funnel_order` | Integer | Position of the stage in the funnel. |
> | `is_sales` | Boolean | Whether the stage represents a sale. |
> | `is_first_contact` | Boolean | Whether the stage represents the first contact. |
> | `default_value` | Number | Default sale value of the stage. |
> | `hook_message` | String | Key phrase that moves a lead to this stage automatically. |
> | `is_active` | Boolean | Whether the stage is active (removed stages are not listed). |
> | `conversion_ids` | Array of integers | Ids of the conversion events the stage triggers (see conversion\_events). |

> [accordion] 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`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `account_code` | String | Code (UUID) of the Tintim account the record belongs to. |
> | `id` | Integer | Unique identifier of the tracking link (origin\_campaign\_id in leads). |
> | `code` | String | Public code (UUID) of the tracking link. |
> | `name` | String | Name of the tracking link. |
> | `wpp_first_message` | String | Message pre-filled in the WhatsApp conversation. |
> | `whatsapp_desktop_link_redirect` | String | Where a desktop click is redirected. |
> | `message_for_redirect_title` | String | Title of the waiting screen shown before the redirect. |
> | `message_for_redirect_content` | String | Content of the waiting screen shown before the redirect. |
> | `short_link_code` | String | Code of the short link, when the link is shortened. |
> | `meta_ads_url` | String | URL to use as the destination of a Meta Ads ad. |
> | `site_url` | String | URL to use on the WhatsApp buttons of a website. |
> | `short_url` | String | Short version of site\_url (null when the link is not shortened). |
> | `is_active` | Boolean | Whether the tracking link is active. |
> | `created` | Datetime | When the tracking link was created (UTC). |
> | `updated` | Datetime | When the tracking link was last changed (UTC). |

> [accordion] 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`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `account_code` | String | Code (UUID) of the Tintim account the record belongs to. |
> | `id` | Integer | Unique identifier of the conversion event. |
> | `name` | String | Name of the event, as the ad platform knows it (e.g. Purchase). |
> | `platform` | Integer | Destination platform: 1 Meta Ads, 2 Google Ads. |
> | `platform_display` | String | Destination platform name. |
> | `description` | String | Description of the event. |
> | `google_conversion_action_id` | String | Google Ads conversion action id, when set. |
> | `created` | Datetime | When the event was created (UTC). |
> | `updated` | Datetime | When the event was last changed (UTC). |

> [accordion] 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`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `account_code` | String | Code (UUID) of the Tintim account the record belongs to. |
> | `id` | Integer | Unique identifier of the dispatch. |
> | `lead_id` | Integer | Id of the lead (conversation) that originated the conversion. |
> | `lead_phone` | String | Phone number of that lead. |
> | `status_name` | String | Name of the stage at dispatch time. |
> | `status_is_sales` | Boolean | Whether that stage represents a sale. |
> | `event_name` | String | Name of the conversion event at dispatch time. |
> | `status_code` | Integer | HTTP status the platform answered (null while no answer arrived). |
> | `created` | Datetime | When the dispatch was created (UTC). |
> | `platform` | Integer | Destination platform: 1 Meta Ads, 2 Google Ads. |
> | `dispatch_status` | String | Where the dispatch stands (e.g. succeeded when the platform confirmed, scheduled while queued). |
> | `dispatch_message` | String | Message explaining the dispatch status. |
> | `scheduled_for` | Datetime | When a scheduled dispatch will be sent (UTC). |
> | `conversion_datetime` | Datetime | Conversion time sent to the platform (UTC). |
> | `click_identifier` | String | Google click identifier sent with the conversion (gclid, wbraid or gbraid). |

## Use cases

### Revenue by Meta Ads campaign

```sql theme={null}
SELECT
  o.origin_meta_campaign_name,
  COUNT(*) AS sales,
  SUM(s.sale_amount_value) AS revenue
FROM lead_status_history s
LEFT JOIN lead_origin_history o
  ON o.account_code = s.account_code AND o.id = s.tracking_id
WHERE s.leadstatus_is_sales AND s.is_active
GROUP BY o.origin_meta_campaign_name
ORDER BY revenue DESC
```

### Leads per day and source

```sql theme={null}
SELECT DATE(first_message_datetime) AS day, source, COUNT(*) AS leads
FROM leads
WHERE is_active
GROUP BY DATE(first_message_datetime), source
ORDER BY day
```

## 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

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "The Tintim API (v2) is not enabled for this Tintim account" | Tintim has not enabled API v2 on the account. | Ask Tintim support to enable API v2 access for the account. |
| "Tintim rejected the API token" | The token is wrong, was revoked, or its user lost access. | Create a new token under **Tokens de API** in Tintim and update the source. |
| "...has not accepted Tintim's messaging terms..." | The token's user cannot read the account's messages yet. | Accept the messaging terms in Tintim with that user, or deselect `lead_messages`. |
| "...needs management access to the account..." | `tracking_links` or `conversion_events` need a manager. | Give the user management access, use a manager's token, or deselect those streams. |
| An account is missing from the tables | It has no API v2, is deactivated, or its workspace is inactive. The run log lists the skipped accounts. | Ask Tintim support to enable API v2, or check the account in Tintim. |
| "...were read by earlier syncs but cannot be read anymore" | An account the source already synced lost API v2 access, was deactivated, its workspace became inactive, or the token's user no longer has access to it. The sync stops so its data is not removed from your tables. | Restore the access (or ask Tintim support to enable API v2 on it again), or fill **Account codes** with only the accounts you want to keep. |
| "Tintim answered 'not found' for the messages of N leads" | Many leads could not be read; the token's user may have lost access to the account. | Check the user's access in Tintim and run the sync again. |
| The run slows down with "Tintim is limiting the request rate" | Other integrations of the same Tintim user are using the shared request budget. | Nothing to do: the run waits and continues. Spread the schedules if it happens often. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.