> ## 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. # Umbler Talk as a data source > Bring your Umbler Talk (uTalk) contacts, chats, messages, ratings, channels, chatbots, campaigns and templates to Nekt. Umbler Talk (uTalk) is Umbler's platform for customer service, sales and chatbots on WhatsApp and other channels. This connector reads your Umbler Talk organization through the Umbler Talk API and brings your contacts, chats and their messages, contact ratings, channels, sectors, tags, custom fields, members, chatbots, WhatsApp Flows and their answers, bulk sends (campaigns) and the messages they delivered, tasks, quick answers and message templates. > [!NOTE] > > The connector only reads data. It never sends messages or creates, changes or deletes anything in Umbler Talk. This is the Umbler Talk connector; for Umbler hosting, domains and e-mail, use the [Umbler](https://docs.nekt.com/sources/umbler.md) connector. ## Configuring Umbler Talk 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 Umbler Talk option from the list of connectors. Click **Next** and you'll be prompted to add your access. ### 1. Add account access The Umbler Talk API uses an **access token**. To create one, open Umbler Talk, click your profile picture and go to **Access Tokens**, then create a token and copy it. * **API Token**: the access token you created. * **Start Date**: the earliest date read by the incremental tables (chats, messages, ratings, WhatsApp Flow answers and bulk send messages). The other tables are always read whole. * **Organization ID** (advanced, optional): leave it empty when your user belongs to a single Umbler Talk organization. If it belongs to more than one, the first sync fails and its log lists your organizations with their IDs; copy the ID of the one to sync into this field. > [!TIP] > > The connector sees what the user who created the token sees. Create the token with a user who has the **Administrator** role in the organization: users below admin only see part of the chats, tasks and settings, and some tables would be skipped. > [!WARNING] > > API access depends on your Umbler Talk plan. If your plan does not include it, the sync fails with a message saying so. Check your plan with Umbler. 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. You can select entire groups of streams or pick specific ones. > 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**: keep the suggested type. Chats, Messages, Contact Ratings, WhatsApp Flow Answers and Bulk Send Messages are **Incremental**: each sync reads only what changed since the previous one and merges it into the table. The other tables are **Full table**: the Umbler Talk API has no filter by date for them, so each sync reads them whole and replaces the table. 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. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Chats and messages are read incrementally, so an hourly or daily sync works well. Optionally, you can 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). Chats and Messages catch conversations that receive new messages without one. An Additional Full Sync (for example, weekly) is still useful to refresh what incremental syncs do not see: chats closed or transferred without a new message, and message states or reactions that change more than 3 days after the message (see Data Quality Considerations). 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 | Sync | Description | | - | - | - | - | | Organization | `organization` | Full table | The organization read by the source: plan, contract and available features. | | Organization Members | `organization_members` | Full table | People and AI agents of the organization, with their permissions. | | Channels | `channels` | Full table | WhatsApp numbers, Instagram accounts, website widgets and other channels. | | Sectors | `sectors` | Full table | Sectors (departments) chats are routed to. | | Tags | `tags` | Full table | Tags used on contacts and chats. | | Custom Field Definitions | `custom_field_definitions` | Full table | Custom fields defined for contacts and chats. | | Contacts | `contacts` | Full table | Every contact, with its tags and custom field values. | | Chats | `chats` | Incremental | Conversations of every state (pinned included), with contact, channel, sector, responsible member, tags and custom fields. | | Messages | `messages` | Incremental | Messages of the chats, sent and received. | | Contact Ratings | `contact_ratings` | Incremental | Ratings (satisfaction surveys) given by contacts. | | Chatbots | `bots` | Full table | Chatbots of the organization. | | WhatsApp Flows | `flows` | Full table | WhatsApp Flows (forms). | | WhatsApp Flow Answers | `flow_answers` | Incremental | Answers contacts sent to the forms. | | Bulk Sends | `bulk_send_sessions` | Full table | Bulk sends (campaigns) of templates or chatbots. | | Bulk Send Messages | `bulk_send_messages` | Incremental | Each message a bulk send delivered, with its delivery state. | | Tasks | `organization_tasks` | Full table | Tasks linked to chats, contacts or pipeline items. | | Quick Answers | `quick_answers` | Full table | Saved replies of every member. | | Message Templates | `templates` | Full table | WhatsApp message templates and their approval status. | ## Fields by stream Fields marked String (JSON) hold a nested object or list as JSON text; use your warehouse's JSON functions to read them. > [accordion] Organization > > The Umbler Talk organization read by the source: plan, contract and the features the plan includes. > > Table: `organization` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the record in Umbler Talk. | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `name` | String | Name of the Umbler Talk organization. | > | `icon_url` | String | URL of the organization's icon. | > | `max_members` | Integer | Maximum number of members the organization's contract allows. | > | `contract_status` | String | Status of the organization's Umbler Talk contract. | > | `contract_plan` | String | Umbler Talk plan contracted by the organization. | > | `free_until_utc` | Datetime | Date and time (UTC) the organization's free period ends. | > | `has_implementation` | Boolean | Whether the organization contracted the Umbler Talk implementation service. | > | `has_contract_pendence` | Boolean | Whether the organization's contract has a pending issue (e.g. an overdue payment). | > | `has_sent_first_message` | Boolean | Whether the organization has already sent its first message. | > | `origin` | String | How the organization was created in Umbler Talk. | > | `pending_invites` | Integer | Number of member invitations not yet accepted. | > | `exceeding_credits` | Integer | Conversation credits used above the plan's allowance. | > | `chats` | String (JSON) | Number of chats per state in the organization (JSON object). | > | `features` | String (JSON) | Features available to the organization under its plan, such as API access and message history (JSON object). | > | `flags` | String (JSON) | Feature flags set on the organization (JSON array). | > | `groups` | String (JSON) | Groups the organization uses to organize members, tags, bots and other records (JSON array). | > [accordion] Organization Members > > People and AI agents of the organization, with their permissions. > > Table: `organization_members` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the member (a person or an AI agent) in the organization. | > | `model_type` | String | Kind of member: human agent or AI agent (the API's `_t` discriminator). | > | `display_name` | String | Name shown for the member. | > | `email_address` | String | E-mail address of a human member. | > | `profile_picture_url` | String | URL of the member's profile picture. | > | `active` | Boolean | Whether the member is active in the organization. | > | `billable` | Boolean | Whether the member counts as a paid seat. | > | `status` | String | Current status of the member (availability for a person, state for an AI agent); JSON when the API sends an object. | > | `access_expires_at_utc` | Datetime | Date and time (UTC) the member's access expires, when temporary. | > | `last_bot_transference_utc` | Datetime | Date and time (UTC) a chatbot last transferred a chat to this member. | > | `group_ids` | Array of strings | Identifiers of the organization groups this record belongs to. | > | `reassign` | String | How chats of this member are reassigned when the member is away. | > | `allowed_sector` | String (JSON) | Sectors the member may access (JSON object). | > | `allowed_channel` | String (JSON) | Channels the member may access (JSON object). | > | `allowed_channel_session` | String (JSON) | Channel sessions the member may access (JSON object). | > | `allowed_contacts_board` | String (JSON) | Contact boards the member may access (JSON object). | > | `allowed_pipeline` | String (JSON) | Sales pipelines the member may access (JSON object). | > | `allow_reports` | Boolean | Whether the member may see reports. | > | `allowed_templates` | Boolean | Whether the member may use message templates. | > | `allowed_contacts` | String | Which contacts the member may see. | > | `contact_phone_visibility` | String | Per member override of the organization's contact phone privacy policy. | > | `private_chats_behavior` | String | Whether the member may use private chats. | > | `send_templates_behavior` | String | Whether the member may send message templates. | > | `tags_behavior` | String | What the member may do with tags. | > | `chats_visibility` | String | Which chats the member may see. | > | `pipeline_items_access` | String | Which sales pipeline items the member may access. | > | `allowed_quick_answers` | Array of strings | What the member may do with quick answers. | > | `permissions` | Array of strings | Permissions of the member in the organization. | > | `permission_actions` | Array of strings | Actions the member is allowed to perform. | > | `two_factor_enabled` | Boolean | Whether the member has two-factor authentication enabled. | > | `chatbot_type` | String | Kind of chatbot, for an AI agent member. | > | `bot_llm` | String | Language model used, for an AI agent member. | > | `is_ai_assistant_agent` | Boolean | Whether the AI agent is the organization's AI assistant. | > [accordion] Channels > > Channels of the organization: WhatsApp numbers, Instagram accounts, website widgets and others. > > Table: `channels` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the channel (a WhatsApp number, Instagram account, website widget...). | > | `model_type` | String | Kind of channel, e.g. WhatsApp Cloud API, WhatsApp Starter, Instagram or website widget (the API's `_t` discriminator). | > | `name` | String | Name of the channel. | > | `state` | String | State of the channel (e.g. Live, Offline, Disabled, Deleted). | > | `phone_number` | String | Phone number of a phone-based channel, in E.164 format. | > | `channel_type` | String | Type of channel, when the API reports it. | > | `waba_state` | String | State of the WhatsApp Business Account, for Gupshup WhatsApp channels. | > | `host` | String | Host of the channel's provider, for Gupshup WhatsApp channels. | > | `domains` | Array of strings | Website domains where the website widget channel is allowed. | > | `group_ids` | Array of strings | Identifiers of the organization groups this record belongs to. | > [accordion] Sectors > > Sectors (departments) chats are routed to. > > Table: `sectors` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the sector (department) of the organization. | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `name` | String | Name of the sector. | > | `default` | Boolean | Whether this is the organization's default sector. | > | `order` | Number | Position of the sector in the organization's list. | > | `group_ids` | Array of strings | Identifiers of the organization groups this record belongs to. | > [accordion] Tags > > Tags used on contacts and chats. > > Table: `tags` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the tag. | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `name` | String | Name of the tag. | > | `emoji` | String | Emoji shown with the tag. | > | `color` | String | Color of the tag. | > | `description` | String | Description of the tag. | > | `order` | Number | Position of the tag in the organization's list. | > | `group_ids` | Array of strings | Identifiers of the organization groups this record belongs to. | > [accordion] Custom Field Definitions > > Custom fields defined for contacts and chats. Their values are in the `custom_fields` column of Contacts and Chats, linked by `customFieldDefinitionId`. > > Table: `custom_field_definitions` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the custom field definition. | > | `model_type` | String | Kind of custom field (text, number, date, currency, CPF, CNPJ, options, member, contact reference...) (the API's `_t` discriminator). | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `name` | String | Name of the custom field. | > | `description` | String | Description of the custom field. | > | `scope` | String | Where the field is used: Contact, Chat or ContactAndChat. | > | `attributes` | String (JSON) | Attributes shown for reference fields (JSON array). | > | `currency` | String | Currency of a currency field. | > | `min_range` | Number | Minimum value accepted by a currency or decimal field. | > | `max_range` | Number | Maximum value accepted by a currency or decimal field. | > | `scale` | Integer | Number of decimal places of a currency or decimal field. | > | `allows_multiple_selections` | Boolean | Whether a list or options field accepts more than one value. | > | `allowed_members` | Array of strings | Members that can be chosen in a member field. | > | `options` | String (JSON) | Options of a multiple-options field (JSON array). | > [accordion] Contacts > > Every contact of the organization, blocked contacts and WhatsApp groups included, with the values of every contact custom field. > > Table: `contacts` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the contact. | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `name` | String | Name of the contact. | > | `phone_number` | String | Phone number of the contact, in E.164 format. | > | `lid` | String | WhatsApp LID (privacy identifier) of the contact. | > | `whats_app_username` | String | WhatsApp username of the contact. | > | `email` | String | E-mail address of the contact. | > | `landline` | String | Landline phone number of the contact. | > | `gender` | String | Gender of the contact. | > | `address` | String (JSON) | Address of the contact (JSON object: addressLine1, addressLine2, city, state, zipCode, country). | > | `profile_picture_url` | String | URL of the contact's profile picture. | > | `is_blocked` | Boolean | Whether the contact is blocked. | > | `contact_type` | String | Kind of contact: DirectMessage (a person) or Group (a WhatsApp group), among others. | > | `group_identifier` | String | Identifier of the WhatsApp group, for group contacts. | > | `organization_members` | Array of strings | Identifiers of the members responsible for the contact. | > | `channel_ids` | Array of strings | Identifiers of the channels the contact talked through. | > | `tags` | String (JSON) | Tags of the contact (JSON array of tag references). | > | `last_active_utc` | Datetime | Date and time (UTC) of the contact's last activity. | > | `channels` | String (JSON) | Activity of the contact per channel, including the 24-hour conversation window (JSON array). | > | `custom_fields` | String (JSON) | Custom field values of the contact, each with its customFieldDefinitionId (JSON array). | > [accordion] Chats > > Conversations of every state (open, waiting and closed), pinned chats included. A chat is loaded again whenever it gets a new message, with its latest state. > > Table: `chats` · Primary key: `id` · Sync: Incremental (by `event_at_utc`) > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the chat (conversation). | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `event_at_utc` | Datetime | Date and time (UTC) of the chat's latest event (new message, transfer, closing...); used as the incremental replication key. | > | `contact_id` | String | Identifier of the contact of the chat. | > | `contact_name` | String | Name of the contact of the chat. | > | `contact_phone_number` | String | Phone number of the contact of the chat. | > | `channel_id` | String | Identifier of the channel the chat happens on. | > | `channel_name` | String | Name of the channel the chat happens on. | > | `sector_id` | String | Identifier of the sector (department) the chat is in. | > | `sector_name` | String | Name of the sector (department) the chat is in. | > | `organization_member_id` | String | Identifier of the member currently responsible for the chat. | > | `last_organization_member_id` | String | Identifier of the last member who was responsible for the chat. | > | `open` | Boolean | Whether the chat is open. | > | `waiting` | Boolean | Whether the chat is waiting for a member to take it. | > | `waiting_since_utc` | Datetime | Date and time (UTC) the chat started waiting. | > | `private` | Boolean | Whether the chat is private (visible only to its participants). | > | `visibility` | String | Visibility of the chat in the inbox: Show, Hide or HideUntilNextMessage. | > | `total_unread` | Integer | Number of unread messages in the chat. | > | `total_ai_responses` | Integer | Number of responses an AI agent sent in the chat. | > | `closed_at_utc` | Datetime | Date and time (UTC) the chat was closed. | > | `closed_by_id` | String | Identifier of who closed the chat. | > | `redact_reason` | String | Why the chat's content was redacted, when it was. | > | `last_message_id` | String | Identifier of the last message of the chat. | > | `last_message_at_utc` | Datetime | Date and time (UTC) of the last message of the chat. | > | `first_contact_message_id` | String | Identifier of the contact's first message in the chat. | > | `first_contact_message_at_utc` | Datetime | Date and time (UTC) of the contact's first message in the chat. | > | `first_member_reply_message_id` | String | Identifier of the first reply a member sent in the chat. | > | `first_member_reply_at_utc` | Datetime | Date and time (UTC) of the first reply a member sent in the chat. | > | `using_inactivity_flow` | Boolean | Whether the chat is under the organization's inactivity flow. | > | `inactivity_flow_at` | Datetime | Date and time (UTC) the inactivity flow acts on the chat. | > | `using_waiting_flow` | Boolean | Whether the chat is under the organization's waiting flow. | > | `waiting_flow_at` | Datetime | Date and time (UTC) the waiting flow acts on the chat. | > | `organization_members` | String (JSON) | Members who took part in the chat (JSON array). | > | `organization_member_history` | String (JSON) | History of the members responsible for the chat (JSON array). | > | `sector_history` | String (JSON) | History of the sectors the chat went through (JSON array). | > | `tags` | String (JSON) | Tags of the chat (JSON array of tag references). | > | `bots` | String (JSON) | Chatbots that ran in the chat (JSON array). | > | `favorite_messages` | Array of strings | Identifiers of the chat's messages marked as favorite. | > | `custom_fields` | String (JSON) | Custom field values of the chat, each with its customFieldDefinitionId (JSON array). | > | `timeline` | String (JSON) | Segments of the chat's time with chatbots, in queue, with AI agents and with members (JSON array). | > [accordion] Messages > > Messages of the chats read in each sync. For each chat, messages are read from 3 days before the sync window, so an old conversation that gets a new message only adds its recent messages, and recent messages get their latest delivery state. Binary file content is never loaded (the file URL, name, type and size are). > > Table: `messages` · Primary key: `id` · Sync: Incremental (by `event_at_utc`) > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the message. | > | `model_type` | String | Kind of timeline entry: a received message or a sent message (the API's `_t` discriminator). | > | `chat_id` | String | Identifier of the chat the message belongs to. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `event_at_utc` | Datetime | Date and time (UTC) the message happened, as reported by the messaging provider; used as the incremental replication key. | > | `message_type` | String | Original type of the message (text, image, audio, document, template...). | > | `source` | String | Where the message came from (contact, member, chatbot, AI agent, bulk send, API...). | > | `message_state` | String | Latest delivery state of the message (sent, received, read, failed...), at the time it was extracted. | > | `content` | String | Written content of the message. | > | `prefix` | String | Prefix of the message, usually the name of the member who sent it. | > | `header_content` | String | Header of the message (templates only). | > | `footer` | String | Footer of the message (templates only). | > | `is_private` | Boolean | Whether the message is a private note, visible only to members. | > | `sent_by_organization_member_id` | String | Identifier of the member who sent the message; empty when sent by the contact. | > | `from_contact_id` | String | Identifier of the contact who sent the message, when sent by the contact. | > | `contact_id` | String | Identifier of the contact the message was sent to (sent messages). | > | `template_id` | String | Identifier of the template, when the message is a template. | > | `bot_instance_id` | String | Identifier of the chatbot run that sent the message. | > | `bulk_send_session_id` | String | Identifier of the bulk send (campaign) that sent the message. | > | `scheduled_message_id` | String | Identifier of the scheduled message that originated this message. | > | `in_reply_to_id` | String | Identifier of the message this one replies to. | > | `file` | String (JSON) | File attached to the message (JSON object with URL, name, content type, size, caption and transcription; never the binary content). | > | `file_id` | String | Identifier of the file saved in the organization files. | > | `contacts` | String (JSON) | Contact cards shared in the message (JSON array). | > | `location` | String (JSON) | Coordinates shared in the message (JSON object). | > | `question` | String (JSON) | Question and options presented by a chatbot (JSON object). | > | `buttons` | String (JSON) | Buttons the contact could press (JSON array). | > | `whatsapp_flow` | String (JSON) | WhatsApp Flow (form) sent in the message (JSON object). | > | `whatsapp_flow_reply` | String (JSON) | Answers the contact gave to a WhatsApp Flow (JSON object). | > | `catalog` | String (JSON) | Product catalog content of the message (JSON object). | > | `carousel` | String (JSON) | Cards of a carousel message (JSON array). | > | `elements` | String | Interactive elements of the message, as sent by the API. | > | `mentions` | String (JSON) | Members or contacts mentioned in the message (JSON array). | > | `reactions` | String (JSON) | Reactions to the message (JSON array). | > | `latest_edit` | String (JSON) | Latest edit of the message (JSON object). | > | `forwarded_from` | String (JSON) | Original message, when this one was forwarded (JSON object). | > | `forward_count` | Integer | How many times the message has been forwarded along the chain. | > | `frequently_forwarded` | Boolean | Whether WhatsApp flags the message as frequently forwarded. | > | `is_forward_restricted` | Boolean | Whether the message can only be forwarded to one destination at a time. | > | `ad` | String (JSON) | Click-to-WhatsApp ad that originated the message (JSON object). | > | `deducted_ai_credits` | Integer | AI credits deducted for the message, when an AI agent sent it. | > | `is_favorite` | Boolean | Whether a member marked the message as favorite. | > | `billable` | String (JSON) | Billing information of the message (JSON object). | > [accordion] Contact Ratings > > Ratings (satisfaction surveys) given by contacts. > > Table: `contact_ratings` · Primary key: `id` · Sync: Incremental (by `created_at_utc`) > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the rating. | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the rating was given; used as the incremental replication key. | > | `chat_id` | String | Identifier of the rated chat. | > | `contact_id` | String | Identifier of the contact who gave the rating. | > | `repository` | String | Name of the rating repository (the survey the rating belongs to). | > | `rating` | String | Score given by the contact (e.g. Awful, Bad, Average, Good, Excellent). | > | `feedback` | String | Written feedback the contact left with the rating. | > | `bot_id` | String | Identifier of the chatbot that asked for the rating. | > | `bot_instance_id` | String | Identifier of the chatbot run that asked for the rating. | > | `bot_step_id` | String | Identifier of the chatbot step that asked for the rating. | > [accordion] Chatbots > > Chatbots of the organization. > > Table: `bots` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the chatbot. | > | `model_type` | String | Kind of chatbot (the API's `_t` discriminator). | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `updated_at_utc` | Datetime | Date and time (UTC) the chatbot was last updated. | > | `title` | String | Title of the chatbot, for internal reference. | > | `order` | Number | Order in which the chatbot runs alongside the others. | > | `final` | Boolean | When true, no other chatbot runs on the channel after this one decides to run. | > | `active` | Boolean | Whether the chatbot is active. | > | `channels` | String (JSON) | Channels the chatbot acts on (JSON array of channel references). | > | `last_snapshot_id` | String | Identifier of the chatbot's latest saved version. | > | `snapshot_title` | String | Title of the chatbot's latest saved version. | > | `executions_count` | Integer | How many times the chatbot was executed. | > | `executions_date_utc` | Datetime | Date and time (UTC) of the chatbot's last execution. | > | `group_ids` | Array of strings | Identifiers of the organization groups this record belongs to. | > [accordion] WhatsApp Flows > > WhatsApp Flows (forms) of the organization. > > Table: `flows` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the WhatsApp Flow (form). | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `updated_at_utc` | Datetime | Date and time (UTC) the form was last updated. | > | `name` | String | Name of the form. | > | `category` | String | Category of the form. | > | `status` | String | Status of the form (draft, published, deprecated...). | > | `channels` | String (JSON) | Channels the form is published on, with their status (JSON array). | > | `published_on_web_at_utc` | Datetime | Date and time (UTC) the form was published. | > | `default_message` | String | Default message sent with the form. | > | `default_cta` | String | Default call-to-action button label of the form. | > | `answer_bot` | String (JSON) | Chatbot started when the form is answered (JSON object). | > | `screen_count` | Integer | Number of screens of the form. | > | `question_count` | Integer | Number of questions of the form. | > | `field_names` | Array of strings | Names of the form's fields. | > | `group_ids` | Array of strings | Identifiers of the organization groups this record belongs to. | > [accordion] WhatsApp Flow Answers > > Answers contacts sent to the WhatsApp Flows. > > Table: `flow_answers` · Primary key: `id` · Sync: Incremental (by `answered_at_utc`) > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the answer. | > | `answered_at_utc` | Datetime | Date and time (UTC) the contact answered the form; used as the incremental replication key. | > | `flow_id` | String | Identifier of the WhatsApp Flow (form) answered. | > | `flow_name` | String | Name of the form answered. | > | `chat_id` | String | Identifier of the chat the answer came through. | > | `message_id` | String | Identifier of the message that carried the answer. | > | `contact_id` | String | Identifier of the contact who answered. | > | `contact_name` | String | Name of the contact who answered. | > | `contact_phone_number` | String | Phone number of the contact who answered. | > | `contact_profile_picture_url` | String | URL of the profile picture of the contact who answered. | > | `bulk_send_session_id` | String | Identifier of the bulk send (campaign) that sent the form. | > | `bulk_send_session_title` | String | Title of the bulk send (campaign) that sent the form. | > | `fields` | String (JSON) | Questions and the answers given (JSON array). | > [accordion] Bulk Sends > > Bulk sends (campaigns) of templates or chatbots. > > Table: `bulk_send_sessions` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the bulk send (campaign). | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `title` | String | Title of the bulk send. | > | `type` | String | What the bulk send sent: Template or Bot. | > | `initiated_by_id` | String | Identifier of the member who started the bulk send. | > | `channel_id` | String | Identifier of the channel the bulk send went out from. | > | `messages_sent` | Integer | Number of messages sent by the bulk send. | > | `total_scheduled` | Integer | Number of messages scheduled by the bulk send. | > [accordion] Bulk Send Messages > > Each message a bulk send delivered, with its delivery state. Every sync reads again the bulk sends created in the 30 days before the newest one already loaded, so delivery states keep updating while they can still change. > > Table: `bulk_send_messages` · Primary key: `bulk_send_session_id`, `message_id` · Sync: Incremental (by `session_created_at_utc`) > > | Field | Type | Description | > | :- | :- | :- | > | `bulk_send_session_id` | String | Identifier of the bulk send (campaign) that sent the message. | > | `session_created_at_utc` | Datetime | Date and time (UTC) the bulk send was created; used as the incremental replication key. | > | `message_id` | String | Identifier of the message sent (joins with messages.id). | > | `chat_id` | String | Identifier of the chat the message was sent in. | > | `state` | String | Delivery state of the message (sent, received, read, failed...), at the time it was extracted. | > | `event_at_utc` | Datetime | Date and time (UTC) of the message. | > | `is_resend` | Boolean | Whether the message was a resend. | > | `contact_id` | String | Identifier of the contact the message was sent to. | > | `contact_name` | String | Name of the contact the message was sent to. | > | `contact_phone_number` | String | Phone number of the contact the message was sent to. | > | `contact_whats_app_username` | String | WhatsApp username of the contact the message was sent to. | > | `contact_profile_picture_url` | String | URL of the profile picture of the contact the message was sent to. | > [accordion] Tasks > > Tasks of the organization, linked to chats, contacts or pipeline items. > > Table: `organization_tasks` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the task. | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `title` | String | Title of the task. | > | `description` | String | Description of the task. | > | `due_at_utc` | Datetime | Date and time (UTC) the task is due. | > | `reminder_at_utc` | Datetime | Date and time (UTC) of the task's reminder. | > | `visibility` | String | Who can see the task. | > | `assigned_members` | Array of strings | Identifiers of the members assigned to the task. | > | `links` | String (JSON) | Chats, contacts or pipeline items the task is linked to (JSON array). | > | `created_by_id` | String | Identifier of who created the task. | > | `created_by_type` | String | Kind of author who created the task (member, chatbot, AI agent...). | > | `completed_at_utc` | Datetime | Date and time (UTC) the task was completed. | > | `completed_by_id` | String | Identifier of who completed the task. | > [accordion] Quick Answers > > Quick answers (saved replies) of every member. > > Table: `quick_answers` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the quick answer (saved reply). | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `name` | String | Name (shortcut) of the quick answer. | > | `content` | String | Text of the quick answer. | > | `organization_member_id` | String | Identifier of the member the quick answer belongs to, when it is personal. | > | `created_by_id` | String | Identifier of the member who created the quick answer. | > | `variables` | String (JSON) | Variables used in the quick answer (JSON array). | > | `attachment` | String (JSON) | File attached to the quick answer (JSON object). | > | `group_ids` | Array of strings | Identifiers of the organization groups this record belongs to. | > [accordion] Message Templates > > WhatsApp message templates and their approval status. > > Table: `templates` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Unique identifier of the WhatsApp message template. | > | `model_type` | String | Umbler Talk type name of the object (the API's `_t` discriminator), e.g. the channel or custom field kind. | > | `created_at_utc` | Datetime | Date and time (UTC) the record was created in Umbler Talk. | > | `label` | String | Name of the template. | > | `category` | String | WhatsApp category of the template (marketing, utility, authentication). | > | `status` | String | Approval status of the template. | > | `template_type` | String | Type of template (text, media, carousel...). | > | `channel_id` | String | Identifier of the channel the template was created in. | > | `channels` | String (JSON) | Official channels the template was created in, with the status in each (JSON array). | > | `requires_media_reupload` | Boolean | Whether the media must be uploaded again to add the template to more channels. | > | `header` | String (JSON) | Header of the template (JSON object). | > | `content` | String | Body text of the template. | > | `footer` | String | Footer text of the template. | > | `buttons` | String (JSON) | Buttons of the template (JSON array). | > | `variables` | String (JSON) | Example values of the template's variables (JSON array). | > | `carousel` | String (JSON) | Cards of a carousel template (JSON array). | > | `approved_at_utc` | Datetime | Date and time (UTC) the template was approved. | > | `reject_error_reason` | String | Why the template was rejected, when it was. | > | `group_ids` | Array of strings | Identifiers of the organization groups this record belongs to. | ## Implementation Notes ### Data Quality Considerations * **How chats and messages stay up to date.** Each sync reads, in order of their last message, the chats that got a message since the previous sync (with a 2-hour margin), up to the moment the sync started, plus your pinned chats. For each of them it reads the messages of that period and of the 3 days before it. A conversation that started months ago and gets a new message today is updated in Chats and its recent messages are added to or refreshed in Messages. A chat that gets a message while a sync is running is read by the next sync. If a sync is interrupted, the next one continues where it stopped, and still loads the full message period of the chats the interrupted sync had not reached. Chats that have no message yet are read too. * **Closings and transfers.** A chat whose only change is a closing or a transfer, without a new message, is refreshed in Chats when it gets its next message or in a full sync. * **Message states.** The `message_state` of a message (sent, received, read) and its reactions are refreshed whenever its chat is read within 3 days of the message. Later changes are only picked up by a full sync. In Bulk Send Messages, delivery states are read again for 30 days after each campaign. * **Late messages.** Message times come from the messaging provider. A message that reaches Umbler Talk up to about 3 days after its own time is loaded the next time its chat is read; later than that, only by a full sync. The same applies when syncs are more than 3 days apart. * **Message history limited by plan.** Some Umbler Talk plans limit how far back messages can be read. When that happens, the sync log warns once, and the older messages are not available to the connector. * **Full table tables are never half updated.** The connector reads all the data of a full table table before writing any of it. If Umbler Talk fails or refuses part of it, nothing of that table is sent and the sync shows it as failed. On GCP (BigQuery) the table keeps its previous content; on AWS, a full table table whose stream was skipped may be emptied by the load step until the next successful sync. A full table table that suddenly comes back empty is not emptied either: the sync fails for that table. If the data really was removed in Umbler Talk, run a full sync of the source to accept it. * **Permissions.** Tables the token's user may not read are skipped, shown as failed in the sync, and named in the sync log; the other tables keep syncing. If Umbler Talk refuses the messages of a chat or no longer has them, that chat's messages are skipped, everything else is loaded, and the chat is tried again in the next sync. For a private chat of other members, the sync log only warns (use a token of an Administrator to include them); if it is refused again in the next sync, it is no longer retried. For any other chat, the Messages table is also shown as failed in that sync, so missing messages never go unnoticed. A chat is dropped from the retries only when Umbler Talk confirms it was deleted. At most 500 chats are kept for retry. * **Scheduled messages are not extracted.** The Umbler Talk API only lists them one contact at a time. * **Times are in UTC** in every column ending in `_utc` and in every other date column. ### API Limits & Performance * Umbler Talk allows up to 100 requests every 5 seconds, shared with your other integrations. The connector makes at most about 10 requests per second and, when Umbler Talk asks it to slow down, waits and tells you in the sync log. * Lists are read 50 records per request, and messages 250 per request per chat. The first sync reads everything since the Start Date and can take a while on large accounts; later syncs read only what changed in Chats, Messages and the other incremental tables, and read the full table tables whole. ## Troubleshooting | Error or symptom | What it means | What to do | | :- | :- | :- | | "Umbler Talk rejected the API Token" | The token is wrong, expired or was deleted. | Create a new access token in Umbler Talk (profile picture > Access Tokens) and update the source. | | "The user of this Umbler Talk token belongs to N organizations" | The token's user is in more than one organization. | Copy the ID of the organization to sync from the message into the Organization ID field. | | "The Organization ID of this source ... is not one of the organizations of the token's user" | The Organization ID does not match the token. | Fix the Organization ID, or use a token of a user of that organization. | | "The Umbler Talk plan of this organization does not include API access" or "refused API access for this organization (HTTP 402)" | Your plan does not allow API access. | Check your plan with Umbler. | | "Umbler Talk refused access to these tables" / "refused part of ..." | The token's user may not read those tables. They were skipped; the other tables were loaded. | Use a token of an Administrator, or deselect the skipped tables. | | "Umbler Talk refused again the messages of N private chat(s)" | Those private chats were refused twice and are no longer retried. | Use a token of an Administrator to include private chats. | | "More than 500 chats had their messages refused" | Only the 500 most recent refused chats are retried. | Use a token of an Administrator, or contact Nekt support. | | "Umbler Talk refused the messages of N private chat(s)" | Those are private chats of other members. Their messages were not loaded; everything else was. | Use a token of an Administrator to include private chats. | | "Umbler Talk refused or did not return the messages of N chat(s) that are not private" | Umbler Talk refused or did not return those chats' messages. Messages is shown as failed; everything else was loaded, and those chats are read again in the next sync. | Usually temporary. If it repeats, use a token of an Administrator or contact Nekt support. | | "Umbler Talk did not return the pinned chats of the token's user" | The pinned chats list was refused or is unavailable. Pinned chats are loaded once they get a new message or leave the pinned list. | Usually no action needed. If it repeats, contact Nekt support. | | "Umbler Talk listed ... out of date order" | The Umbler Talk API answered in an unexpected order, so the sync stopped instead of skipping chats. | Contact Nekt support. | | "The Umbler Talk plan of this organization limits how far back messages can be read" | Older messages are hidden by your plan. | No action needed, unless you need the older messages: check your plan with Umbler. | | "Umbler Talk returned no ... records at all, although the previous sync read N" | Umbler Talk returned an empty list for a table that had rows. The table was kept. | If the data really was removed, run a full sync of the source. Otherwise run the sync again later. | | "The ... list kept changing in Umbler Talk while it was being read" | Many records were deleted during the sync. | Usually temporary; the next sync tries again. | | "Umbler Talk is limiting how fast this sync may read" | The request limit was reached, possibly together with your other integrations. | No action needed; the sync waits and continues. | | "Could not reach Umbler Talk" or "Umbler Talk kept failing" | Umbler Talk did not answer, or answered with errors, after several attempts. | Usually temporary; the next sync tries again. | | "Umbler Talk answered ... in a format this connector does not recognize" or "... more items on a single instant than one page holds" | The Umbler Talk API changed or answered in an unexpected way. | Contact Nekt support. | ## Skills for agents > [card] [Download Umbler Talk skills file](https://docs.nekt.com/sources/umbler-talk.md) > > Umbler Talk connector documentation as plain markdown, for use in AI agent contexts. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.