* A classification that assigns a discrete and qualitative label (e.g., P1, P2, Critical) to an opportunity based on its numerical **Impact Score**. It allows for a quicker and more intuitive understanding of an opportunity's priority level. The process works as follows: * **Range Mapping:** The system takes the Impact Score value of an opportunity. * **Category Assignment:** Based on pre-defined value ranges for each client, it assigns a label (an "impact level"). * **Visualization:** This classification is visible on the platform, allowing for quick identification of the importance of each opportunity. The assigned tag can also be manually overridden if an opportunity is considered relevant due to specific business rules, for example. When this happens, the manually set tag will be visually marked with an asterisk (\*). > **Note:** As this is a metric with a custom configuration, the client needs to contact the Customer Success (CS) team to change the value ranges and category labels. \
* Create one collection per “dimension” of segmentation (Firmographics, Behaviors, Lifecycle). * Agree internally on naming conventions (e.g. “DAU > 30” vs. “High DAU”). * Use Collections as a training tool — new team members will quickly see “how we slice data here.” * Review Collections quarterly: retire unused segments, align with evolving CRM or analytics sources. ## How to create a collection of Segments * Navigate to your Segments tab in Exploration * Select the Segment you want to group into a collection (e.g.: These 3 segments related to Customer Size)  * Click in Save Collection * Give your Collection a name  * Change Segments table to group by collections  * Done! * Now, get even more insightful analysis from your segmented data  {% endtab %} {% endtabs %} # Understanding and Creating Opportunities in Birdie ## What Are Opportunities in Birdie? In Birdie, an Opportunity represents a specific insight derived from customer feedback that highlights emerging trends, critical issues, or areas for improvement. These insights enable teams to delve into granular details, understand root causes, and identify actionable areas that can enhance the overall customer experience. By effectively managing Opportunities, organizations can prioritize initiatives that directly impact customer satisfaction and business growth.  ## Page Structure of an Opportunity Each Opportunity in Birdie is organized into several key components: {% stepper %} {% step %} ### Title and Description A clear and concise title accompanied by a detailed description outlining the nature of the Opportunity. {% endstep %} {% step %} ### Tabs There a few tabs to better divide and navigate the information of an Opportunity. They are: Overview, Areas, Opportunities and Segments. [Areas](/core-concepts-and-entities/areas): Areas that the Opportunity is related to. [Opportunities](/customer-intelligence/opportunities): Other Opportunities that are related to this one. [Segments](/core-concepts-and-entities/segments): Specific segments of feedback linked to the Opportunity {% endstep %} {% step %} ### Overview Chart and Metrics A summary section displaying a chart with the Opportunity feedback count and essential [metrics](/getting-started/metrics-glossary) related to the Opportunity, such as overall feedback count, customer impact scores, and trend analyses.  {% endstep %} {% step %} ### What's Happening An AI-generated summary that provides an overview of the data, offering immediate insights into the Opportunity's context and significance.  {% endstep %} {% step %} ### Skye Birdie's AI assistant is integrated into the Opportunity page to help users deepen their understanding of the identified issue. Within an Opportunity, Skye can: * provide in-depth insights into the nature and extent of the problem, * detect related or underlying issues associated with the current Opportunity, * suggest potential actions or focus areas to effectively address the identified problems, * highlight emerging trends or patterns in the feedback that may influence the Opportunity.  {% endstep %} {% step %} ### Feedbacks A space for you and your team to explore and find insights about the feedbacks from each source that are related to the Opportunity.  {% endstep %} {% endstepper %} By understanding and utilizing these components, teams can effectively analyze and address Opportunities to drive continuous improvement within their organization. *** ## How to Create Opportunities in Birdie In Birdie, there are two ways to create an Opportunity: {% stepper %} {% step %} ### From an Area of Interest If you already know of a problem that you want to quantify and explore further: * Navigate to the desired Area of Interest. * Click the "Add Opportunity" buttonon the top right corner. * Provide a title and description for the new Opportunity. For more detailed guidance on working with Areas of Interest, see the [Areas of Interest Documentation](/core-concepts-and-entities/areas).   {% endstep %} {% step %} ### Via the Skye Chat To add an Opportunity through the Skye chat: * Ensure you are within an Area or within an existing Opportunity (applied filters will shape Skye's search results). * Ask Skye to search for Opportunities; she will present a list. * Click the "+Add" button on an Opportunity entry to add it to your workflow. For details on using filters and leveraging Skye, see the [Filters Documentation](/customer-intelligence/exploration-and-analysis/using-filters-in-birdie) and the [Skye Usage Documentation](/customer-intelligence/exploration-and-analysis/understanding-and-using-skye-in-birdie).  {% endstep %} {% endstepper %} *** ## Explore the Power of Opportunities Step into Birdie and discover how the Opportunity feature can transform your customer feedback into actionable insights. By leveraging our intuitive interface and advanced tools like Skye, you can pinpoint critical issues, quantify challenges, and drive impactful improvements across your organization. Get started now and unlock a new level of understanding that fuels better decision-making and continuous growth! # Product Overview Birdie's Customer Intelligence act as a centralized command center that transforms raw customer sentiment into actionable business strategy. By leveraging advanced Natural Language Processing (NLP), the platform ingests unstructured qualitative feedback from multiple channels—such as surveys, social media, and support tickets—to categorize into Opportunities. Users can navigate using Exploration to uncover deep-seated customer pain points. Beyond analysis, the platform features a management system where insights are directly converted into strategic Initiatives. Teams can assign owners, set key performance indicators (KPIs), and track the real-time impact of specific improvements on customer satisfaction scores. To report to stakeholders receive high-level summaries and data visualizations that bridge the gap between hearing the customer and driving measurable organizational change. ## Explore the avaliable features
:compass: | Exploration | Find feedback insights | /pages/Goa6SJlZry9c3p7A8UW3 |
:lightbulb: | Opportunities | Categorize feedbacks | /pages/bd4229ae7a5e5cb18ee0a10b1355c1e053a09a04 |
:bullseye-arrow: | Initiatives | Track progress | /pages/016de836f55d57a8fa6801b4476d378dc7ef3e1d |
:gauge-low: | Dashboards & Reporting | Tell stories | /pages/F8x6BCkZ9LGQ1RO790sA |
# How to analyze Opportunities After an Opportunity is quantified in Birdie, it becomes a rich source of insights about patterns, trends, and emerging problems in your customers' feedback. Analyzing Opportunities allows you to identify root causes, monitor impact over time, segment issues by different criteria, and make informed decisions about where to invest resources to improve the customer experience. ### Components of the Opportunities page * Metrics Header: * Total volume of feedbacks identified; * Frequency of occurrence of the opportunity; * Temporal trends (growth, decline, seasonality); * Distribution across channels, products, or segments; * "What's Happening": * Summary automatically generated by AI highlighting main insights; * Emerging patterns in feedbacks; * Correlations with other factors; * Segments and Filters: * Analyze the distribution of the opportunity by period, channel, product, region, etc; * Compare different groups to identify significant variations. * Skye Integrated: * Ask specific questions about the opportunity; * Explore root causes and associated factors; * Request suggestions for actions or areas of focus. * Related Feedbacks: * List of feedbacks classified as containing the opportunity; * Possibility to explore specific examples for additional context. ### Types of possible analyses * Temporal Analysis: * Identify if the opportunity is growing or declining; * Detect seasonal or cyclical patterns; * Correlate with business events or changes. * Segmented Analysis: * Compare incidence across different channels; * Analyze variations by product or service; * Identify customer profiles most impacted. * Correlation Analysis: * Explore relationships with other opportunities; * Identify factors that amplify or reduce occurrence; * Discover interdependencies between problems. * Impact Analysis: * Measure total volume of affected customers; * Calculate relative frequency per segment; * Estimate impact on the business or satisfaction. ### Step-by-Step Guide for effective analysis 1. Examine general metrics: Understand the volume, frequency, and trend of the opportunity; 2. Read the AI summary: Absorb the main insights identified automatically; 3. Segment the data: Use filters to explore variations by different criteria; 4. Converse with Skye: Ask specific questions to deepen the analysis; 5. Explore examples: Review specific feedbacks to contextualize the data; 6. Document insights: Record conclusions and next steps identified. ## Example Scenario: Analyze opportunity "Difficulty finding information about fees" ### Analysis performed * Metrics: 1,200 feedbacks identified in the last 3 months, 15% growth; * Segmentation: 80% concentrated in the digital channel, higher incidence in individual customers; * Question to Skye: "What are the most mentioned fees by customers?"; * Main insight: Maintenance fee is the biggest problem, especially in the mobile app; * Recommended action: Improve visibility of fee information in the app. ### Useful questions for Skye * About root causes: * "What are the main factors that cause this opportunity?" * "In what contexts does this opportunity appear most?" * About impact: * "How does this opportunity affect customer satisfaction?" * "What is the profile of customers most impacted?" * About solutions: * "What actions could reduce this opportunity?" * "Are there best practices observed in the feedbacks?" ## Best Practices * Combine quantitative analysis (metrics) with qualitative (examples); * Use segmentation to identify priority groups; * Explore correlations with other opportunities or business metrics; * Ask specific questions to Skye to deepen insights; * Document conclusions and next steps for responsible teams; * Monitor trends regularly to detect changes; ## Common Questions * How often should I analyze opportunities?\ Weekly analysis is recommended for critical opportunities and monthly for others; * Can I export the data for external analysis?\ Yes, you can export feedbacks and use complementary tools if necessary. ## Read also * [Opportunities](/customer-intelligence/opportunities) * [Using Birdie's AI agent, Skye](/customer-intelligence/exploration-and-analysis/understanding-and-using-skye-in-birdie) * [How to use filters in Birdie](/customer-intelligence/exploration-and-analysis/using-filters-in-birdie) # Initiatives ## What Are Initiatives in Birdie? In Birdie, the power of centralizing, exploring, and uncovering hidden opportunities from user feedback allows teams to deep dive into granular details and understand root causes. However, uncovering insights is only the beginning—eventually, action is required. This is where Initiatives come into play. An Initiative is an action plan designed to activate a change based on a discovered opportunity. It functions like a task or to-do item that the CX or Operations Team—responsible for monitoring Customer Intelligence—creates to escalate an issue or opportunity to another team within the company for resolution. ## How to Create an Initiative There are two ways to create an Initiative in Birdie: ### From an Existing Opportunity If you've identified an opportunity and need to take action, you can create an Initiative directly from the Opportunity Page: * Click the Add to Initiative button at the top right corner. * Give it a name and save. * A new Initiative is created and automatically associated with the given opportunity. * Add all necessary details, such as assignee, description, and external links.  ### From the Initiatives Page To create an Initiative independently: * Navigate to the Initiatives Overview Page. * Click the Create Initiative button on the top right corner. * Add relevant details and later associate it with one or more existing opportunities, agents or criteria.  ## Key Associations to Keep in Mind A single opportunity can be linked to multiple initiatives if different teams need to address it separately. * Example: A product issue might require a new FAQ by Product Marketing, a bug fix by Engineering, and a process update by Customer Support. A single initiative can be linked to multiple opportunities, agents or criterion when a single solution addresses multiple issues. * Example: A new feature release may resolve several different pain points across different customer journeys. ## Example: Initiatives in Action Imagine a CX Team in a digital bank startup monitoring Customer Intelligence within the "Credit Card" product. They track the "Credit Card Invoice Payment" journey and uncover a major issue: Delayed credit limit release after invoice payment. Through root cause analysis, they discover that users expect an immediate credit limit release upon invoice payment. However, they are unaware of the payment confirmation process that occurs before the release. To address this, the CX Team needs to escalate the issue. They do so by creating an Initiative in Birdie. * Initiative Name: Improve communication about invoice payment and limit release process * Assignee: Product Marketing Team * Description: Highlights findings and the need for better FAQ or communication materials to set proper user expectations, reducing complaint volume. * Additional Details: The assignee can add an estimated due date and an external link to an internal task management tool (e.g., Jira, Trello, Asana). ## Managing and Tracking Initiatives {% stepper %} {% step %} ### Initiative Listing and Filtering All created Initiatives are listed under the Initiative Page in Birdie. Here, teams can: * View all Initiatives created to address different opportunities. * Filter by Owner, Assignee or Status to track responsibilities across departments.  {% endstep %} {% step %} ### Initiative Status Control Each Initiative follows a status workflow: * To Do → Initial status when the Initiative is created. * Doing → Assigned teams are actively working on it. * Done → The Initiative is completed and action has been taken. * Custom Status → You can create any number of custom status on your Settings page > Custom status.
# Dashboard tabs Tabs allow you to organize widgets within a dashboard into distinct, named sections — making it easier to navigate complex dashboards and group related data without creating multiple separate dashboards. ### Overview When a dashboard grows to cover multiple topics or teams, scrolling through a long list of widgets becomes inefficient. Tabs let you divide a dashboard's content into clearly labelled sections. Each tab holds its own set of widgets, and viewers switch between them with a single click. Tabs are created and managed in dashboard edit mode. Viewers see the tab navigation automatically.
💬 Got questions or want to share your feedback?
Get in touch with our support team. Your opinion is essential for us to keep improving the dashboard experience. Let us know what you think of this update!# Line Chart ### What is the Line Chart Widget? The Line Chart is one of the core widget types available in Birdie Dashboards. It is designed to help you visualize how a metric evolves over time by plotting data points connected by a continuous line. With support for multiple series displayed simultaneously, the Line Chart makes it easy to track trends, identify peaks and drops, and compare performance across different areas, teams, or feedback channels, all within a single view. #### How to extract the most value from the Line Chart? The Line Chart is most valuable when your primary question involves change over time. Use it when you want to answer questions such as: * How has the volume of feedback from my different support channels changed over the past 30 days? * Which areas of the product are generating the most feedback this quarter compared to last? * Are certain feedback categories growing or declining week over week? Because the Line Chart supports breakdowns by dimensions like Areas or Opportunities, you can layer multiple series onto one chart and immediately see which segments are driving changes in your data.
Comparison chart set up screen
Multi-series chart set up screen
Does the AI Prompt Widget work with any type of filter?
Yes, when using the Filter context type, it analyzes data based on the filters you apply.Can I reference a widget from another dashboard tab?
Yes, when using the Widget context type, the selector shows all widgets in the current dashboard, regardless of which tab they are on.Can I reference a widget from a different dashboard?
No, only widgets within the same dashboard are available as context sources.Can I have multiple AI Prompt Widgets in the same dashboard?
Yes, you can add as many as needed, each with its own prompt and context configuration.The preview is blank after configuring the axes. What should I check?
Verify that the **Selection** field under Horizontal axis has at least one value selected, and that the chosen **Start period** and **End period** contain data for the selected metric.Why are some bars missing from the chart?
The **Limit** field caps the number of bars displayed. Increase this value in the Setup tab to show more breakdown categories.The chart is showing unexpected values when the dashboard filter changes.
If the widget should remain unaffected by dashboard-level filtering, enable **Ignore global filter** in the Filter tab.What does the Mix Effect bar represent?
The Mix Effect bar captures the portion of the total change that results from shifts in the composition of the breakdown dimension rather than performance changes within individual categories. Disable **Show Mix Effect** in Display settings if you do not need this breakdown.:list-check: | Criteria | Define FI rules | /pages/Umg5JxH3daWNSQnH8UhJ |
:phone-arrow-down-left: | Reason | Contact reason | /pages/5VHc1LdZYJpbK56C3jUY |
:headset: | Agent | Agent performance | /pages/93pEJ5ryeMEWas8l07w8 |
*** ### Page Layout The page is organized into two main areas: * **Analytics** — three summary metrics displayed at the top, always reflecting the current filter selection\
* Go to the Digest tab. * Click + Add new Digest. * Enter a name for your digest (to help with management). * Choose your layout: * Review Pulse * Multi-Purpose Pulse * Define your filters. * The more specific your filters, the more relevant your notifications will be. * You can create multiple digests for different use cases. * Set the frequency and delivery time that best fits your team’s workflow. * Select your delivery channels. * You can send the same digest to multiple Slack channels at once. {% endstep %} {% endstepper %}
| Type | Description | Page |
|---|---|---|
| Areas | Manage broad themes used to organize feedback. | /pages/ixCBYIeVZhWEhX2544X8 |
| Opportunities | Manage specific issues and improvement opportunities. | /pages/90ExVjWAMbaj4rli6hjr |
| Segments | Manage audience and behavior-based groupings. | /pages/a71rzcRLRRHKzZKv5KDb |
| Reasons | Manage contact motives and FI service categories. | /pages/SyDOubzYWgBG0DZSLrg5 |
| Criteria | Manage FI rules used to evaluate service quality. | /pages/ZIFvGHYICnblww3lgEic |
This view helps teams organize Criteria by theme, process, behavior, or quality framework. Use collections when you need to: * keep criteria grouped by topic * simplify FI administration * make workspace organization easier ### Managing collections Use collections to group related criteria under the same operational theme. #### Create a collection 1. Click **+ Add collection** 2. Enter the collection name 3. Confirm with the check icon
Key pillars of our security program include: • Certifications & Compliance: SOC 2 Type II, GDPR, LGPD, USDP, and HIPAA-aligned controls • Data Protection: Encryption in transit and at rest, strict access controls, and environment isolation • Privacy by Design: Data minimization, anonymization, and purpose limitation built into the platform • Operational Security: Continuous monitoring, vulnerability management, and incident response procedures • Governance: Documented policies covering information security, access management, risk management, and vendor oversight Detailed security documentation, policies, and compliance reports are available upon request. After signing an NDA, authorized stakeholders can request access through our [Trust Center in Vanta.](https://trust.birdie.ai/) # PII & PHI anonymization ## PII & PHI anonymization When it comes to qualitative feedback ingestion, anonymizing PII and sensitive information is a key step to keep your data pipeline secure and privacy compliant. Any personally identifiable information (PII) or sensitive information that could identify individuals is therefore removed and securely discarded. This includes: * Personal numbers or codes such as a United States Social Security Number, driver's license, or any document from other countries. * A person's full name or first name. * A person's phone number. * A person's email address. * A person's address, location, or city. * Any credit card, bank account information, or passwords. By design, the Birdie solution does not rely on PII or sensitive information to work, therefore, all native connectors in Birdie are created to import only anonymized structured columns. It means, instead of importing user names and emails from your support ticket platform, Birdie connectors will only import user\_ids to match the records. More than structured columns, there may be PII or sensitive information within qualitative fields. In cases like that, there are two different directions to follow: {% stepper %} {% step %} ### PII & PHI anonymization handled by Birdie — PII & PHI never gets stored in Birdie's servers  * In this scenario, Birdie will handle PII anonymization within the initial step of data pipeline in GCP region: us-central-1. * Our anonymization process employs a hybrid system combining rigid pattern detection with an AI-based entity recognition model. This means that we have two layers of pattern matching for specific IDs to successfully remove most PIIs. * Any sensitive pattern such as: names, emails, addresses, card numbers, document ids will be \[REDACTED] to indicate the change in the original content. * PII anonymization is activated for all clients, ensuring that all incoming open-text fields (ticket comments, survey responses, call transcripts) will get checked and processed before Birdie stores any raw data in our servers. * This option can be used with any ingestion method (native connectors, S3 bucket, Birdie Rest API or CSV uploads). However, there is the need to send open PII to be anonymized. {% hint style="info" %} For the complete end-to-end flow applied to speech-to-text data (audio → transcription → anonymization → storage), the redaction techniques, and the evidence that the result meets the regulations like GDPR and LGPD, see [Data Anonymization Process — Speech-to-Text Pipeline](/admin-and-settings/security/data-anonymization-process-speech-to-text). {% endhint %} {% hint style="info" %} Note: For clients in Brazil, in compliance with the Lei Geral de Proteção de Dados (LGPD), this ingestion step runs in GCP region: southamerica-east-1 prior to final persistence at the global index in GCP region: us-central-1, Iowa. For clients outside Brazil, the whole process will remain running at our main infrastructure in the United States, GCP region: us-central-1, Iowa. {% endhint %} {% endstep %} {% step %} ### PII & PHI anonymization handled by Company — PII & PHI never reaches any of Birdie's services  * In this scenario, your company handles PII anonymization within your local infrastructure, running PII redaction scripts to replace names, emails, addresses, document IDs and whatever is considered sensitive by regulations in your industry/business. * To help running that task internally, we offer [Birdie AI Anonymizer](https://ask.birdie.ai/admin-and-settings/security/data-anonymizer-user-guide) project, available in the Google Cloud Marketplace * Once anonymized, data integration can be done via S3 bucket (parquet file) or Birdie Rest API: * [Cloud Object Import](https://ask.birdie.ai/integrations-and-data-ingestion/how-to-integrate-with/s3-azure-gcs) * [Birdie AI Anonymizer](https://ask.birdie.ai/admin-and-settings/security/data-anonymizer-user-guide) * [Ingestion API](/integrations-and-data-ingestion/ingestion-api) * By using this approach, your company makes sure Birdie never receives any PII or sensitive information. {% endstep %} {% endstepper %}
Types of PII/PHI currently anonymized by Birdie (expand to view full list)
***Personal Identifiers*** * Names (including doctor names) * NINs (National Identification Numbers) * Driver's License Numbers * Passport Numbers * Patient Account Numbers * Birth Dates * Admission/Discharge Dates * Vehicle Identifiers * Device Serial Numbers * URLs and IP Addresses * Biometric Identifiers * Voter Card IDs * Taxpayer Identification Numbers (TINs) ***Contact Information*** * Phone Numbers (including fax) * Email Addresses * Physical Addresses * ZIP Codes * Certificate/License Numbers ***Financial Information*** * Credit Card Numbers * Bank Account Numbers * Insurance Policy Numbers * Payment Details ***Healthcare Identifiers*** * Medical Record Numbers (MRN) * Insurance IDs and Group Numbers * Medicare/Medicaid Numbers * DEA Numbers * NPI (National Provider Identifier) * Health Plan Beneficiary Numbers * Device Identifiers and Serial Numbers * Laboratory Numbers ***Clinical Information*** * Diagnosis Codes (ICD-10) * Procedure Codes (CPT) * Medication NDC Codes * Test Results * Treatment Dates * Appointment DetailsCan I use SSO Groups and role/workspace claims together?
No. SSO Groups is an exclusive mode. Choose one approach per SSO integration.What happens if an IdP group does not match any Access Group?
Unmatched values are silently ignored. Only groups with a matching alias in Birdie are applied.Can I assign a user to an Access Group both manually and via SSO?
Yes. Manual assignments are independent from SSO. SSO login only syncs SSO-sourced memberships.How do I change the SSO attribute key for groups?
Contact the Birdie team to configure a custom attribute key for your organization.What is the technical architecture of the solution?
Birdie's platform is structured in layers, each performing distinct roles. The ingestion layer collects, receives, and validates customer data. The enrichment layer applies various models to identify patterns and extract insights. Finally, raw and enriched data are consolidated in the application layer, which the client exclusively interacts with. Public data traffic uses HTTPS, while internal communication between services occurs over a private network. Birdie’s infrastructure is hosted on Google Cloud Platform (GCP) - region: us-central-1 Iowa. For companies in Brazil, due to LGPD, **Ingestion and anonymization steps run in Google Cloud Platform (GCP) - region: southamerica-east-1** prior to final persistence at the global index in GCP region: us-central-1 Iowa.What is the recommended hosting option for the AI solution?
Birdie provides fully managed SaaS hosting, meaning clients access the Birdie application directly. We do not offer AI models as a service like OpenAI or similar companies.What support does Birdie provide for the AI solution?
Birdie offers SLAs to ensure platform availability and conducts training sessions to help clients maximize the solution’s potential. Note that Birdie’s solution operates independently of client business processes, so temporary service interruptions do not result in financial losses for the client.Is there a development roadmap for the AI solution?
Yes, Birdie’s system is continuously evolving, with clients directly influencing the roadmap. Currently, the focus is on refining the solution for Fintechs and related sectors, ensuring clients benefit from these developments.How scalable is Birdie’s AI architecture?
Birdie currently processes an average of 50 million feedbacks per month, with the capacity to handle hundreds of millions under load testing. Scalability is ensured by a combination of large language models (LLMs) and specific smaller models (SLMs) trained in-house for optimal processing power and cost efficiency.What are the integration requirements with existing client systems?
Birdie requires well-defined data sources for integration. We provide connectors to data lakes, APIs, and even web crawlers for data ingestion. Data enrichment results can be returned to the client's data lake if needed.How does Birdie manage infrastructure—cloud or on-premises?
Birdie operates on GCP with virtual separation of instances and offers physical separation at an additional cost, based on feedback volume. We use anonymized data, relying on IDs for analysis without handling PII. * Birdie currently operates with three databases: vector, text, and analytical. * The Birdie solution does not rely on the ingestion of PII (Personally Identifiable Information). We use anonymized records, cross-referencing only IDs to perform the necessary associations for segmented analyses without utilizing any sensitive data or risking client identification. * Data ingestion must remain PII-free, even in cloud deployments, which significantly mitigates any potential leaks. * Nonetheless, we implement security practices aligned with the best industry standards, as if we were handling data with PII. * An on-premises solution is possible but highly costly due to the complexity of the Birdie platform. * The recommendation is to consider this on-premises alternative only in a later implementation phase, particularly if ingesting sensitive data becomes necessary.What integrations and data sources are available?
Birdie supports [numerous integrations and crawlers](https://birdie.ai/integrations/) for feedback ingestion. For additional integrations outside the contracted scope, setup fees apply.  What authentication and access control measures are implemented? Is SSO available?
Authentication is via email/password or OAuth, with SSO available upon request. Each client manages user permissions within their organization. SSO incurs additional costs and must be negotiated with our commercial team. Does Birdie comply with data protection regulations like LGPD?
Yes, Birdie is SOC 2 Type 2 certified and adheres to local data regulations, including LGPD.Does Birdie follow compliance standards?
Yes, Birdie implements security measures comparable to handling sensitive data, verified through SOC 2 Type 2 audits.Will the solution require internal data sharing?
No sensitive data is required. Birdie uses anonymized user feedback and identifiers provided by the client to perform data segmentation.How is user management and permission control handled?
Birdie provides two user roles: * All Access (Admin): Full permissions, including inviting users and managing profiles. * View Only: Limited to viewing data, searching, filtering, exporting feedback, and using the Birdie Assistant.How does Birdie secure authentication for data access?
All web and API traffic is encrypted using HTTPS/TLS 1.2. API data ingestion is secured through API keys. We also support secure platform connectors and utilize IAM roles in GCP/AWS for secure data integration.How is the solution monitored for performance and security?
Birdie uses Google Cloud Logging for real-time alerts, a public status page, and audit logs. Security monitoring is enhanced with Vanta to track vulnerabilities and ensure timely patching. Multiple backup layers provide resilience and disaster recovery.What AI models are used in the solution?
Birdie employs a combination of LLMs and SLMs. Recent base models include: * Closed LLMs: GPT (OpenAI), Gemini (Google), Claude (Anthropic) * Open LLMs: Llama (Meta) * SLMs: DeBERTa, RoBERTaWhat is the data protection policy for external LLMs?
External LLMs comply with strict data protection agreements ensuring no customer data is used for model training. Providers include OpenAI, Google, and Anthropic, each with clear data governance policies.What AI techniques are applied?
Birdie leverages Machine Learning (ML), Text Mining (TM), and Natural Language Processing (NLP). Techniques include traditional algorithms like Random Forests and fine-tuning neural networks using ensemble methods and Retrieval-Augmented Generation (RAG) workflows.Does Birdie train models using client data?
No. Models are evaluated using client data, but neither Birdie nor third-party providers train on client data.GenAI Models Used
Birdie employs a combination of Generative AI models to ensure optimal performance and security in its solution. The currently integrated models include: * OpenAI GPT (via API) * Whisper (self-hosted) * Google Gemini (via API) * Meta LLaMA (self-hosted)Proprietary Models and Foundation Models
In addition to public models, Birdie also develops and uses proprietary models based on SLMs (Self-Hosted Language Models), such as: * DeBERTa ([documentation](https://huggingface.co/docs/transformers/en/model_doc/deberta-v2)) * RoBERTa ([documentation](https://huggingface.co/docs/transformers/en/model_doc/roberta)) These models are utilized for specific natural language processing tasks and to enhance the Birdie solution.GenAI Integration in the Solution
Generative AI technology is integrated into Birdie in various ways, including: * Data processing via data pipelines * Integration with RAG (Retrieval-Augmented Generation) in the application interfaceGenAI Use Cases in Birdie
Birdie’s Generative AI is mainly used for: * Data enrichment: Automatic classification and extraction of relevant information. * In-app assistant (RAG): Generating contextualized responses based on proprietary data.Data Usage Policy and Model Training
Birdie ensures that data used in tests (Proof of Concept - PoC) will not be used for refining or training AI models. The training process follows best practices, including: * Base model training only occurs with a trigger and human supervision. * Use of synthetic data for training. * Implementation of cross-validation techniques (10-fold cross-validation, train-validation-test). * Continuous LLM adaptation via RAG, allowing customization based on client feedback without affecting the global model.Security Measures and Guardrails
To ensure the safe use of Generative AI, Birdie implements several guardrails in its solution, including: * Prevention of Prompt Injection Attacks: using prompt engineering techniques to mitigate prompt injection and data cleaning/filtering to reduce indirect prompt injection. * Access Control and Privacy: limited data access by design; the LLM has no autonomy to apply arbitrary filters to data; sensitive data removal during ingestion so the LLM does not have access to confidential customer information. * Hallucination Reduction: guiding responses based on real data to minimize hallucinations and ensure accurate information.You can verify our active status for both frameworks by searching for "Birdie AI" on the [Data Privacy Framework List](https://www.dataprivacyframework.gov/list). *** ### UK Section #### How does Birdie AI handle my data under the UK GDPR? Birdie AI is an active participant in the UK Extension to the EU-U.S. Data Privacy Framework. This means we are legally recognized as providing a level of data protection essentially equivalent to that of the United Kingdom. Since 2023, the UK has recognized the EU-U.S. Data Privacy Framework (DPF) as a valid transfer mechanism when the UK Extension is applied. Birdie AI maintains an active certification under this extension. This acts as an "Adequacy Decision" for the organization, permitting the transfer of personal data from the UK to US-based cloud infrastructure without the friction of individualized Standard Contractual Clauses (SCCs). Adequacy via UK Extension: Since 11/20/2025, Birdie AI has maintained an active certification under the UK Extension to the EU-U.S. Data Privacy Framework. This allows for the seamless transfer of personal data from the UK to the US without requiring additional Standard Contractual Clauses (SCCs) in many instances, as the UK government recognizes this framework as providing "essentially equivalent" protection. #### Who is the independent recourse mechanism for UK residents? If a privacy complaint is not resolved by us within 45 days, UK residents have access to free, independent dispute resolution:\
* For HR Data: The UK Information Commissioner’s Office (ICO). * For Non-HR Data: JAMS (International Arbitration and Mediation Provider). *** #### Additional Sources * [Privacy Policy](https://birdie.ai/privacy-policy) * [Data Processing Agreement](https://birdie.ai/data-processing-agreement) * [Security Policy](https://birdie.ai/security-policy) * [Trust Center](https://trust.birdie.ai/) \
# Export / Import CSV {% tabs %} {% tab title="Export" %} Birdie provides four interrelated CSV files when exporting user feedback data. This document explains their structure, relationships, and common usage rules. ### feedbacks.csv — Main Feedback Export This file contains raw records of all feedback captured in your Birdie account, based on the filters applied at export time. Each row represents a unique piece of feedback. Feedback may or may not be mapped to any area or opportunity. Unmapped feedback is common and can include irrelevant or neutral comments. Key fields: * Ingested\_ID * Posted\_at * Text * Source * Rating * Account\_id * Language * ... (extra fields) ### areas.csv — Feedback to Area Relationships This file lists feedbacks that have been associated with one or more Areas configured in your Birdie account. A single feedback can be linked to multiple areas. Feedback not associated with any area will not appear in this file. Key fields: * Feedback Ingested ID * Area\_ID * Area\_Name * (Also may contain Feedback ID, Area ID, Area Name as additional fields) ### opportunities.csv — Relationship Between Feedbacks, Areas, and Opportunities This file lists cases where feedback has been mapped to both an Interest Area and a Business Opportunity. Feedbacks with positive sentiment or without friction typically do not generate opportunities, so they may appear in areas.csv but not in opportunities.csv. Key fields: * Feedback Ingested ID * opportunity\_id * opportunity\_name * (Also may contain Feedback ID, Area ID, Area Name, Signal Type) ### area\_opportunities.csv — Linking Areas and Opportunities This file defines the many-to-many relationship between Areas and Opportunities. Previously this relationship was included in opportunities.csv; it has been moved into its own file for clarity and flexibility. Each row represents a unique pairing between an area and an opportunity. Key fields: * area\_id * opportunity\_id ## Linking and Rules * All files use the field ingested\_id (in feedbacks.csv) and area\_id / opportunity\_id as linking keys between tables. * You can join them using the following logic: Examples: * Feedback → Areas\ feedbacks.ingested\_id = areas.ingested\_id\ Find all areas mentioned in feedback. * Feedback → Opportunities\ feedbacks.ingested\_id → areas.ingested\_id → area\_opportunities.area\_id → opportunities.opportunity\_id\ Trace which feedback generated specific opportunities. * Area ↔ Opportunity\ area\_opportunities.area\_id = areas.area\_id and area\_opportunities.opportunity\_id = opportunities.opportunity\_id\ Link opportunities to their respective areas. ## Typical Data Presence Rules * A feedback may appear only in feedbacks.csv if it hasn’t been mapped to any area or opportunity. * A feedback may appear in areas.csv but not in area\_opportunities.csv if no opportunity was identified in that area. * A feedback appears in all four files if it is linked to both an area and an opportunity. ## Additional Fields The following additional fields are present in the CSVs but are typically used for internal or metadata purposes: feedbacks.csv * ID, Batch ID, Ingested At, Updated At * Messages First Posted At, Messages Last Posted At, Total Messages * Accounts, Custom Fields, Channel, Kind Name * Source Alias, Status, Priority, Subject, Category, URL areas.csv * Feedback ID, Area ID, Area Name opportunities.csv * Feedback ID, Area ID, Area Name * Opportunity ID, Opportunity Name * Signal Type ## Diagram — Birdie CSV Data Export Structure Below is a conceptual diagram that illustrates the relationship between the CSVs: ``` +--------------------+ | feedbacks.csv | |--------------------| | ingested_id (PK) | | posted_at | | text | | source | | rating | | account_id | | language | | ... (extra fields) | +--------------------+ | | 1 |────────┐ | | 0..* | | 0..* +--------------------+ +-----------------------------+ | areas.csv | | area_opportunities.csv | |--------------------| |-----------------------------| | ingested_id (FK) | | area_id (FK) | | area_id (PK) | | opportunity_id (FK) | | area_name | +-----------------------------+ +--------------------+ | | 0..* | | 1 +---------------------------+ | opportunities.csv | |---------------------------| | opportunity_id (PK) | | opportunity_name | | signal_type | | ... (extra fields) | +---------------------------+ ``` {% endtab %} {% tab title="Import" %} Opening the exported CSV from Birdie in Excel can become a hassle. In order to properly import all the csv rows into a new Excel File, follow these steps: {% stepper %} {% step %} ### In a new Excel file, open the Data panel Click the Data tab in the toolbar. {% endstep %} {% step %} ### Choose Get Data Click the Get Data option.  {% endstep %} {% step %} ### In the Import wizard, choose Text/CSV Select the Text/CSV option in the import wizard.  {% endstep %} {% step %} ### Browse and select your CSV file Locate and select the CSV file you exported from Birdie.  {% endstep %} {% step %} ### Select the delimiter If Excel doesn't detect it automatically, select Comma as the delimiter. {% endstep %} {% step %} ### Load the data Click Load to import the CSV into Excel.  {% endstep %} {% endstepper %} {% endtab %} {% endtabs %} # Birdie MCP Server Birdie's MCP (Model Context Protocol) server connects AI assistants to your Customer Intelligence analytics platform. It lets LLMs query customer feedback, explore trends, and generate Customer Intelligence reports using natural language. It works with any MCP-compatible client — Claude, ChatGPT, Gemini, Cursor, and more. ## How It Works The MCP server exposes a set of tools that AI assistants can call to interact with your organization's feedback data. When you connect an MCP client to Birdie, the assistant can: * Identify your organization and personalize responses * Explore your taxonomy — areas, opportunities, segments, collections, and feedback sources * Query feedback with filters, grouping, and metrics * Read individual feedback items in detail You sign in with your Birdie account. Each request is scoped to your organization — the assistant only sees your data. ## How to setup ### Prerequisites * An MCP-compatible client (Claude, Cursor, Claude Code, Claude Desktop, etc.) * A Birdie account ### Client specific setup * [Claude Desktop](/integrations-and-data-ingestion/birdie-mcp-server/mcp-guide-claude-desktop) * [Claude.ai (web)](#claude.ai-web) * [Claude Code (CLI)](#claude-code-cli) * [Cursor](#cursor) * [Other MCP clients](#other-mcp-clients) * [Through Gateways and Proxies](#mcp-gateways-and-proxies) ## Day-to-Day Usage ### Getting Started Start by asking the assistant to learn about your organization: > *"What's our organization context and what data sources do we have?"* This triggers a couple of tools (`get_context` and `get_taxonomy`) that give the assistant the full picture before it runs any queries. ### Example Queries * *"What are the top 5 complaints this month?"* * *"Show me NPS trends over the last 6 months"* * *"Find negative feedback about onboarding from enterprise customers"* * *"Compare satisfaction scores across our data sources"* * *"How many feedbacks did we receive this quarter, grouped by segment?"* * *"What's the CSAT score for our support tickets last month?"* * *"Show me the impact score breakdown by area"* ## Technical Details ### Available Tools | Tool | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `get_context` | Get your organization's name and description. The assistant calls this first to personalize its responses. | | `get_taxonomy` | Discover your areas, opportunities, segments, collections, and feedback sources. Returns entity names and IDs needed for filtering. | | `get_schema` | Get available fields, metrics, and filter syntax. Returns exact field paths and valid values for querying. | | `query_feedback` | Query feedback with filters, grouping, and metrics. Supports sentiment breakdowns, time-based analysis, text search, and pagination. | | `get_feedback_detail` | Get full details for a specific feedback item — text, sentiment, labels, accounts, custom fields, and metadata. | Some organizations have additional tools enabled depending on their plan and configuration. These may not appear for every account: | Tool | Description | | ------------------------ | --------------------------------------------------------------------------------------------- | | `get_workspaces` | List the workspaces available to you. Returned only when workspaces are enabled for your org. | | `get_workspace_settings` | Get a workspace's behavior preferences, language, enabled modules, and blocklist. | #### Typical Workflow 1. `get_context` — learn who the organization is 2. `get_taxonomy` — understand the data landscape (what areas, segments, sources exist) 3. `get_schema` — discover available metrics, fields, and valid filter values 4. `query_feedback` — run queries with filters and grouping 5. `get_feedback_detail` — dive into individual feedback items ### Setup #### Claude Desktop * Follow [these instructions](/integrations-and-data-ingestion/birdie-mcp-server/mcp-guide-claude-desktop). #### Claude.ai (web) 1. Go to [claude.ai](https://claude.ai) and open **Settings > Connectors** 2. Click **Add Connector** and enter the MCP server URL: ``` https://app-api.birdie.ai/mcp ``` 3. You'll be redirected to the Birdie login page — sign in with your Birdie account 4. Once authenticated, the Birdie tools will appear in your chat That's it. Claude handles the OAuth flow automatically. #### Claude Code (CLI) ```bash claude mcp add birdie -- npx -y mcp-remote https://app-api.birdie.ai/mcp ``` On first use, a browser window will open for you to log in with your Birdie account. {% hint style="info" %} Requires Node.js installed (for `npx`). The `mcp-remote` package is downloaded automatically on first run. {% endhint %} #### Cursor Add this to your Cursor MCP settings (`.cursor/mcp.json`): ```json { "mcpServers": { "birdie": { "command": "npx", "args": [ "-y", "mcp-remote", "https://app-api.birdie.ai/mcp" ] } } } ``` On first use, a browser window will open for you to log in. #### Other MCP Clients Any MCP client that supports OAuth 2.1 can connect using the server URL: ``` https://app-api.birdie.ai/mcp ``` The server exposes standard OAuth discovery at `/.well-known/oauth-authorization-server`. #### MCP Gateways & Proxies If you connect through an MCP gateway or proxy (e.g. *Runlayer*), configure it as follows: * **Registration:** choose **Dynamic Client Registration** (DCR). Birdie publishes a `registration_endpoint`, so the client registers itself automatically — you do **not** enter a Client ID or Client Secret by hand. If your proxy is set to "Pre-registered Client" and asks for those values, switch it to Dynamic Client Registration. * **Client Secret:** leave it **blank**. Birdie MCP is a **public OAuth client** (`token_endpoint_auth_methods_supported: ["none"]`) and uses PKCE — there is no client secret. * **Scopes:** request `openid profile email offline_access`. * **Callback URL:** the gateway's hosted callback URL must be approved on Birdie's side before login will work (see the hint below). {% hint style="warning" %} Birdie only accepts OAuth callbacks from approved hosts. A hosted gateway's redirect/callback URL must be added to Birdie's allowlist first — otherwise the authorization request is rejected before the login screen appears. Send your gateway's callback URL to your Birdie contact to have its host approved. {% endhint %} ### Authentication Birdie MCP uses **OAuth 2.1 with PKCE** — you sign in with your regular Birdie account. * When you connect, you'll be redirected to the Birdie login page * After signing in, the MCP client receives an access token automatically * Your organization is resolved from your account, so you only see your own data * If you log out of Birdie, the MCP connection will disconnect and you'll need to re-authenticate * Sessions may expire periodically — your client will prompt you to re-authenticate when needed Birdie MCP is a **public OAuth client** and supports **Dynamic Client Registration** (RFC 7591), so MCP clients register themselves automatically — there is no client secret to configure. The scopes used are `openid profile email offline_access`. #### Tips * The assistant will call `get_schema` to understand available fields before querying — this is normal * For complex questions, the assistant may make multiple tool calls (schema → query → detail) * All queries are scoped to your organization automatically * Use `get_taxonomy` to discover available IDs for area, opportunity, segment, and collection filters * For large datasets, the assistant can paginate through results automatically * Text search (`text` filter) works across all feedback content ### Known Limitations * **Workspace filtering** — unless workspaces are enabled for your organization, the assistant sees all data in the organization regardless of workspace configuration. * **Session expiry** — sessions may expire periodically depending on token lifetime. Your client will prompt you to re-authenticate when needed. ### Troubleshooting #### Tools disappear or "Authentication required" appears mid-conversation Your session may have expired. Disconnect and reconnect the Birdie connector in your client settings, then sign in again. #### A gateway/proxy asks for a Client ID and Client Secret Birdie MCP uses **Dynamic Client Registration** and is a **public OAuth client**, so there is no client secret to provide. If your proxy (e.g. Runlayer) prompts for these values, its **Registration** is set to "Pre-registered Client" — switch it to **Dynamic Client Registration** and leave **Client Secret** blank. The client will register itself and obtain a Client ID automatically. #### "Callback URL mismatch" or "redirect\_uri not allowed" error This happens when the OAuth redirect URL isn't on Birdie's allowlist of approved callback hosts. * **Claude (claude.ai)**: Should work out of the box. If not, contact your Birdie admin. * **CLI tools (Claude Code, Cursor)**: These use `mcp-remote` which picks a random local port for the callback. Your Birdie admin may need to whitelist additional callback URLs. * **Gateways/proxies (e.g. Runlayer)**: The gateway's hosted callback URL must be added to Birdie's allowlist. Send the exact callback/redirect URL (or paste the URL shown in the error) to your Birdie contact to have its host approved. #### Login succeeds but the connection fails with a `401` The access token is most likely missing the `email` scope. Make sure your client or gateway requests `openid profile email offline_access` — Birdie resolves your account from the email claim, and without it the session can't be authorized. #### Connection drops or intermittent disconnects * Make sure you only have one MCP client connected to Birdie at a time (e.g., don't have both Claude Desktop and Claude web connecting simultaneously) * SSE connections may time out on long idle periods — the client should reconnect automatically # Claude Desktop Setup Connecting Birdie to Claude Desktop lets you pull your feedback data, run analyses, and explore your customers’ feedback directly inside any Claude chat. The setup takes about a minute. Here's how to do it. {% hint style="warning" %} Claude Desktop evolves very rapidly, and the screenshots below may be outdated by the time you read this guide. They are, however, representative of the steps needed to connect it to the Birdie MCP Server {% endhint %} > *Before you start* > > Make sure your Claude admin has already added Birdie's custom MCP connection to your workspace. If they haven't, share [this article](/integrations-and-data-ingestion/birdie-mcp-server#technical-details) with them. ## Step 1: Log into your Birdie account Head to
| Integration Method | Best For | Typical Use Case | Effort (Client) | Effort (Birdie) | Flexibility |
|---|---|---|---|---|---|
| Native Connectors | Standard API-based platforms | Feedback systems like Zendesk, Intercom, Salesforce, Qualtrics | Low | Medium | Low |
| Data Lake / File-based Ingestion | Centralized enterprise data management | Data joins, anonymization, compliance requirements | High | Medium | High |
| REST Ingestion API | Developer-led organizations | Software-driven ingestion pipelines | Medium–High | Medium | Very High |
| Custom Solutions (Professional Services) | Unique or multi-source architectures | Orchestration across multiple systems, unsupported APIs | Variable | High | Maximum |
Small (S) * Scope: Single data source or one new connector. * Complexity: Minimal transformation (renaming, basic filtering). * Effort: 20–40 hours. * Example: Ingesting a new CSV export into Birdie with standardized columns. Medium (M) * Scope: Two connected data sources or moderate transformation. * Complexity: Requires joins or conditional field normalization. * Effort: 40–80 hours. * Example: Matching Zendesk and Salesforce data using shared account\_id. Large (L) * Scope: Three or more source platforms or complex transformation logic. * Complexity: Involves multiple authentication layers or advanced orchestration (Kafka, VPN, custom endpoints). * Effort: 80+ hours. * Example: Integrating data from Genesys, Zendesk, and internal databases through custom scripts and mappings. ## Collaboration and Project Workflow When engaging with Birdie’s Professional Services for ingestion projects, the collaboration process typically follows these stages:
1. Discovery & Scoping * Define data sources, field mappings, and compliance constraints. * Identify ingestion method(s) and potential custom requirements. 2. Effort Estimation & Proposal * Birdie’s team estimates the complexity (S/M/L). * A detailed proposal and pricing estimate are shared. 3. Implementation & Validation * Connector or custom flow is built, configured, and validated with sample data. * Adjustments are made for transformation rules and data normalization. 4. Go-Live & Support * First ingestion run monitored jointly. * Birdie provides handover documentation and operational guidelines. ## Decision Flow Summary A visual decision flow can be included in your presentation deck or appended as a diagram: Start → Identify Source Platform * Is it a commercial platform with an open API?\ → Native Connector * Do you need to join or anonymize data?\ → Data Lake / File-based * Do you prefer developer control with API access?\ → REST Ingestion API * None of the above or multi-source orchestration required?\ → Custom Professional Service # Data Schema Definitions for Birdie Ingestion To ensure seamless data ingestion and high-quality insights, all data imported into Birdie—regardless of the source—must adhere to our standardized data schemas. Whether you are connecting via Cloud Storage (AWS S3, Azure Blob Storage, or Google Cloud Storage) or Cloud Data Warehouses (BigQuery, Snowflake, or Databricks), your source data must be structured to match these definitions. While Birdie offers robust ingestion capabilities, this process typically requires your data or engineering team to transform and map your internal records to these schemas to ensure compatibility. These schemas act as a blueprint, telling Birdie exactly how to interpret each record—whether it is a single customer review, a complex support thread, or a detailed user profile. *** ## 1. Requirements * Data Preparation: Your data team must ensure that source tables or files match the field names and types outlined in the tables below. * Storage/Database Access: Proper credentials (IAM roles, Service Accounts, or API keys) with read-access to the specific datasets. * File & Table Formats: Support for Parquet, CSV, or direct database table syncing. * Timestamp Precision: All date fields must follow the RFC 3339 format (e.g., `2023-10-25T14:30:00Z`) for accurate chronological analysis. *** ## 2. Understanding Record Types Birdie categorizes data into three primary record types ("Kinds"). Choosing the correct Kind during setup is crucial, as it determines how Birdie processes, analyzes, and presents your data. **Feedback:** Represents a single-point interaction — one person, one moment, one piece of input. A Feedback record typically contains a text comment, a numerical rating, and metadata. This Kind has two sub-types: `Review`, for general product or service reviews, and `NPS/CSAT`, optimized for structured survey responses where the rating is the primary signal and the text comment may be absent. > Examples: App Store reviews, Google Play reviews, NPS surveys, CSAT responses, star ratings. **Conversation:** Represents a multi-turn interaction. This Kind of record is denormalized — it groups multiple messages or events under a single `conversation_id`, capturing the full lifecycle of an exchange. A Conversation has four sub-types: `Support Ticket`, for customer service threads; `Complaint`, for grievance tracking and resolution workflows; `Social Media Post`, for public threads from platforms like Facebook, X, or Reddit; and `Issue`, for bug reports and development tasks from tools like Jira or GitHub. > Examples: Support tickets with several agent replies, complaint negotiations, social media threads, Jira issues. **Account:** Defines the "Who" behind the data. Account records contain customer profiles, behavioral attributes, or subscription data used for advanced segmentation and cross-referencing. Every Feedback and every Conversation record must be associated with exactly one Account, establishing the link between what was said and who said it.
Record Types Hierarchy
| Column Name | Type | Required | Description | Example | Impact |
feedback_id | STRING | Yes | Unique identifier for each review. | "rev-2024-abc123" | ❌ Ingestion fails. Duplicates overwrite silently. |
text | STRING | No | The actual text or comment posted by the user. May be null for rating-only feedbacks (e.g., star ratings without comments). | "Great app, deposits are instant!" | ⚠️ No Signals, Sentiment, Intentions, Keyword Search, Skye, or Opportunities. Only rating feeds Dashboard metrics. |
posted_at | STRING | Yes | When the feedback was posted (RFC 3339 timestamp format). | "2024-06-15T14:30:00Z" | ❌ Ingestion fails. Drives all time-series charts, date filters, and Initiative impact tracking. |
rating | FLOAT | Yes | A numerical rating or score associated with the feedback. | 4 | ❌ Ingestion fails. Drives Review AVG Rating and Satisfied/Unsatisfied counts in Dashboards. |
author_id | STRING | No | The author's email address, used as a unique identifier for cross-referencing across record types. | "author@example.com" | ⚠️ No per-author cross-reference with other record types. |
account_id | STRING | No | Unique identifier for the account the record belongs to. | "acct-abc123" | ⚠️ No cross-source analysis. Account-level Segments and Opportunity Prevalence Rate exclude this record. |
language | STRING | No | Language of the record expressed as a BCP 47 code. | "pt-BR" | ⚠️ Defaults to auto-detection. Sentiment, Intentions, and Signal accuracy degrade. Use BCP 47 codes only. |
title | STRING | No | The title of the feedback as provided by the author. | "Best banking app!" | ⚠️ No headline in Exploration UI. Not processed by NLP — no impact on Sentiment/Signals. |
category | STRING | No | The specific category the review belongs to. | "Finance" | ⚠️ Category-based filtering unavailable in Areas, Segments, Reasons, and Dashboards. |
owner | STRING | No | Indicates the entity owner, e.g., "Owner" or "Competitor". | "Nubank" | ⚠️ Cannot filter by product/brand or compare Owner vs. Competitor in Exploration and Dashboards. |
source | STRING | No | A user-customizable label used for grouping feedbacks (e.g., "G2", "App Store"). | "App Store BR" | ⚠️ Defaults to "api". Source filter, header metrics, and Dashboard/Area/Segment breakdowns by source lose meaning. |
| Column Name | Type | Required | Description | Example | Impact |
feedback_id | STRING | Yes | Unique identifier for each survey answer. | "nps-2024-q1-001" | ❌ Ingestion fails. Duplicates overwrite silently. |
posted_at | STRING | Yes | When the feedback was posted (RFC 3339 timestamp format). | "2024-03-10T09:00:00Z" | ❌ Ingestion fails. |
rating | FLOAT | Yes | The numerical score (e.g., NPS 0-10 or CSAT 1-5). | 9 (NPS) / 4 (CSAT) | ❌ Ingestion fails. Drives NPS Score, CSAT Score, Promoter/Detractor counts, and all survey Dashboard metrics. ⚠️ Wrong scale (e.g., NPS as 1–5): accepted, but all NPS metrics become meaningless. |
text | STRING | No | Qualitative comment or open-ended text posted by the user. | "I always recommend this service!" | ⚠️ Score metrics work, but no Signals, Sentiment, Intentions, Keyword Search, Skye, or Opportunities — you lose the "why" behind the score. |
author_id | STRING | No | The author's email address, used as a unique identifier for linking the response to a specific respondent. | "respondent@example.com" | ⚠️ Cannot link response to a specific respondent. |
account_id | STRING | Yes | Unique identifier for the account the record belongs to. | "acc-xyz" | ⚠️ No cross-source analysis (e.g., "tickets from NPS detractors"). Account-level Segments exclude this record. |
language | STRING | No | Language of the record expressed as a BCP 47 code. | "pt-BR" | ⚠️ Defaults to auto-detection. Sentiment and Signal accuracy degrade. |
title | STRING | No | The name or title of the survey. | "[NPS 2024-Q1] Recommendation Survey" | ⚠️ Cannot filter by survey wave in Exploration or Dashboards. |
source | STRING | No | A user-customizable label for grouping feedbacks. | "NPS Q1 2024" | ⚠️ Defaults to "api". Source filter and Dashboard breakdowns by source lose meaning. |
| Column Name | Type | Required | Description | Example | Impact |
conversation_id | STRING | Yes | Unique identifier for the entire conversation thread. | "ticket-2024-001" | ❌ Ingestion fails. |
message_id | STRING | Yes | Unique identifier for each specific message (must be unique at the account level). | "msg-001" | ❌ Ingestion fails. |
text | STRING | Yes | The actual content/text of the message. | "Hi, I can't log in since yesterday." | ⚠️ No Signals, Sentiment, Intentions, Keyword Search, Skye, Opportunities, or FI Criteria evaluation. HTML in text degrades NLP — strip before sending. |
posted_at | STRING | Yes | When the message was posted (RFC 3339 timestamp). | "2024-01-15T10:05:00Z" | ❌ Ingestion fails. Drives Conversation Features (Response Times, Duration), message ordering, and time-series charts. Identical timestamps = broken ordering. |
author_id | STRING | Yes | The author's email address. Must be an email to ensure proper agent recognition, FI evaluation, and cross-referencing within Birdie. | "agent@company.com" | ⚠️ FI Agent page empty — no per-agent Quality Score, Manual Evaluation, or Agent Feedback. Agent Handoffs unavailable. |
account_id | STRING | Yes | Identifier for the account the message belongs to. | "acc-xyz" | ⚠️ No cross-source analysis. Account-level Segments exclude this conversation. |
language | STRING | No | Language of the message as a BCP 47 code. | "pt-BR" | ⚠️ Defaults to auto-detection. Sentiment, Signal, and FI Criteria accuracy degrade. |
subject | STRING | No | The subject line of the support ticket. | "Can't reset my password" | ⚠️ No conversation title in Exploration. Not processed by NLP. |
status | STRING | No | Current status of the ticket (e.g., "open", "pending", "closed"). | "solved" | ⚠️ No status filter/breakdown in Dashboards, Areas, Segments, or Reasons. |
priority | STRING | No | Priority assigned to the ticket (e.g., "urgent", "low"). | "high" | ⚠️ No priority filter/breakdown in Dashboards, Areas, Segments, or Reasons. |
channel | STRING | No | Source channel of the ticket (e.g., "web", "email", "chat"). | "email" | ⚠️ No channel filter/breakdown in Dashboards, Areas, Segments, or Reasons. |
tags | REPEATED STRING | No | An array/list of tags applied to the ticket. | ["billing", "urgent"] | ⚠️ No tag-based filtering in Areas, Segments, or Reasons. |
author_type | STRING | Yes | The role of the author, specifically one of {"Bot", "Agent", "User"}. | "Agent" | ⚠️ Highest-impact optional field. All Conversation Features (50+ fields) = zero. FI Criteria produce false positives. FI Agent page broken. Values: Customer/User, Agent/Internal Person, Bot. |
survey_title | STRING | No | Title of the survey presented upon ticket closure. | "Post-call CSAT" | ⚠️ Survey name not displayed. No feature impact. |
survey_type | STRING | Yes | Type of the closing survey, specifically one of {"csat", "nps"}. | "csat" | ⚠️ TCSAT/TNPS Dashboard metrics cannot be calculated. Upload on one message per conversation only. |
rating | FLOAT | Yes | The numerical rating provided by the client for the support experience. | 8 | ⚠️ TCSAT/TNPS Dashboard metrics cannot be calculated. Upload on one message per conversation only. |
solved | STRING | Yes | Flag indicating if the ticket was resolved, specifically one of {"true", "false"}. | "true" | ⚠️ No resolution filter/breakdown in Dashboards. No native Resolution Rate metric — filter dimension only. |
source | STRING | Yes | A user-customizable label for grouping (e.g., "Zendesk", "Intercom"). | "Zendesk" | ⚠️ Defaults to "api". Source filter, header metrics, and all breakdowns by source lose meaning. |
agent_team | STRING | Yes | The name of the support agent's team. | "Billing Team" | ⚠️ No team-level filtering in FI or Dashboards. |
agent_company | STRING | Yes | The name of the support agent's company. | "Atento BPO" | ⚠️ No BPO vendor comparison in FI or Dashboards. |
agent_supervisor_id | STRING | Yes | The email address of the support agent's supervisor, used for supervisor-level rollups and FI reporting. | "supervisor@company.com" | ⚠️ Supervisor-level rollups unavailable in FI and Dashboards. |
agent_experience | STRING | Yes | The maturity or experience level of the agent (Enum). | "senior" | ⚠️ No seniority vs. quality correlation in FI or Dashboards. |
| Column Name | Type | Required | Description | Example | Impact |
conversation_id | STRING | Yes | Unique identifier for the specific complaint thread. | "complaint-2024-001" | ❌ Ingestion fails. |
message_id | STRING | Yes | Unique identifier for each message (must be unique at the account level). | "cmsg-001" | ❌ Ingestion fails. |
text | STRING | Yes | The actual content/text of the complaint message. | "My order hasn't arrived and it's been 15 days already." | ⚠️ No Signals, Sentiment, Intentions, Keyword Search, Skye, or Opportunities. |
posted_at | STRING | Yes | When the message was posted (RFC 3339 timestamp). | "2024-02-10T08:00:00Z" | ❌ Ingestion fails. Drives Conversation Features and time-series charts. |
author_id | STRING | No | The author's email address, used as a unique identifier for the complainant. | "customer@example.com" | ⚠️ Cannot identify complainant. No cross-reference. |
account_id | STRING | Yes | Identifier for the account the message belongs to. | "acct-456" | ⚠️ No cross-source analysis. Account-level Segments exclude this complaint. |
language | STRING | No | Language of the message expressed as a BCP 47 code. | "pt-BR" | ⚠️ Defaults to auto-detection. Sentiment and Signal accuracy degrade. |
category | STRING | No | A classification for segmenting complaints (e.g., "Support", "Shipping", "Billing"). | "Delivery" | ⚠️ No category filter in Areas, Segments, Reasons, or Dashboards. NLP topics still work from text. |
status | STRING | No | Current state of negotiations (e.g., pending, initiated, ongoing, or solved). | "resolved" | ⚠️ No resolution status filter/breakdown in Dashboards, Areas, or Segments. |
url | STRING | No | Direct link to the complaint if it originates from a public source. | "https://reclameaqui.com.br/complaint/12345" | ⚠️ No click-through to source. No analysis impact. |
rating | FLOAT | Yes | The score the client gave specifically to the complaint negotiation experience. | 3.0 | ⚠️ Complaint satisfaction score unavailable in Dashboards. |
author_type | STRING | Yes | The role of the author, specifically one of {"Internal Person", "User", "Bot"}. | "User" | ⚠️ All Conversation Features (50+ fields) empty. Cannot separate customer vs. company messages. FI broken. |
source | STRING | Yes | A user-customizable label for grouping (e.g., "Public Forum", "Direct Email"). | "Reclame Aqui" | ⚠️ Defaults to "api". Source filter and all breakdowns by source lose meaning. |
| Column Name | Type | Required | Description | Example | Impact |
conversation_id | STRING | Yes | Unique identifier for the post or thread. | "reddit-post-001" | ❌ Ingestion fails. |
message_id | STRING | Yes | Unique identifier for the specific post or comment. | "rmsg-001" | ❌ Ingestion fails. |
text | STRING | Yes | Content of the message. | "The new update broke the search feature." | ⚠️ No Signals, Sentiment, Intentions, Keyword Search, Skye, Opportunities, or Social Media Unsatisfied Count. |
posted_at | STRING | Yes | When the message was posted (RFC 3339 timestamp). | "2024-04-01T12:00:00Z" | ❌ Ingestion fails. |
author_id | STRING | No | The author's email address, used as a unique identifier for cross-referencing. | "user@example.com" | ⚠️ Cannot identify author. No cross-reference. |
account_id | STRING | No | Identifier for the account the message belongs to. | "acct-social-001" | ⚠️ No cross-source analysis. Account-level Segments exclude this post. |
language | STRING | No | Language of the message as a BCP 47 code. | "en" | ⚠️ Defaults to auto-detection. Sentiment and Signal accuracy degrade. |
title | STRING | No | Title of the original social media post. | "Search broken after update" | ⚠️ No headline in Exploration. Not processed by NLP. |
owner | STRING | No | Indicates the entity owner: Owner or Competitor. | "Owner" | ⚠️ Cannot distinguish owned vs. competitor mentions in Exploration or Dashboards. |
category | STRING | No | Segment or sub-grouping (e.g., a specific Subreddit name). | "r/BirdieApp" | ⚠️ No sub-group filter in Areas, Segments, Reasons, or Dashboards. |
url | STRING | No | URL of the social post. | "https://reddit.com/r/BirdieApp/post/001" | ⚠️ No click-through to source. No analysis impact. |
channel | STRING | No | The source platform (e.g., "facebook", "reddit"). | "reddit"" | ⚠️ No platform filter/breakdown in Dashboards, Areas, Segments, or Reasons. |
tags | REPEATED STRING | No | Array of tags applied to the post. | ["bug", "feature-request"] | ⚠️ No tag-based filtering in Areas, Segments, or Reasons. |
author_type | STRING | No | The role of the author, specifically one of {"Internal Person", "User", "Bot"}. | "User" | ⚠️ All Conversation Features (50+ fields) empty. Cannot distinguish brand vs. user posts |
upvotes | INTEGER | No | The number of likes or upvotes the message has received. | 22 | ⚠️ Engagement metrics unavailable. Cannot prioritize by popularity. |
source | STRING | Yes | A user-customizable label for grouping. | "Reddit" | ⚠️ Defaults to "api". Source filter and all breakdowns by source lose meaning. |
| Column Name | Type | Required | Description | Example | Issue |
conversation_id | STRING | Yes | Unique identifier for the issue thread. | "issue-001" | ❌ Ingestion fails. |
message_id | STRING | Yes | Unique identifier for each individual update or comment. | "imsg-001" | ❌ Ingestion fails. |
text | STRING | Yes | The content of the issue description or comment. | "Login button unresponsive on mobile Safari." | ⚠️ No Signals, Sentiment, Intentions, Keyword Search, Skye, or Opportunities. |
posted_at | STRING | Yes | When the record was created/posted (RFC 3339 timestamp). | "2024-03-15T09:00:00Z" | ❌ Ingestion fails. |
author_id | STRING | No | The author's email address, used as a unique identifier for cross-referencing. | "developer@company.com" | ⚠️ Cannot identify reporter. No cross-reference. |
account_id | STRING | No | Identifier for the account associated with the issue. | "acct-789" | ⚠️ No cross-source analysis. Account-level Segments exclude this issue. |
language | STRING | No | Language of the message as a BCP 47 code. | "en" | ⚠️ Defaults to auto-detection. Sentiment and Signal accuracy degrade. |
project_id | STRING | No | Unique identifier for the project or repository. | "birdie/platform" | ⚠️ Cannot segment by project in Areas, Segments, or Dashboards. |
project_name | STRING | No | Human-readable name of the project. | "Platform" | ⚠️ Shows raw ID only in Exploration — not user-friendly. |
title | STRING | No | The title or headline of the issue. | "Login button unresponsive on mobile" | ⚠️ No headline in Exploration. Not processed by NLP. |
status | STRING | No | Current status (e.g., "To Do", "In Progress", "Done"). | "in_progress" | ⚠️ No status filter/breakdown in Dashboards, Areas, or Segments. |
source | STRING | Yes | A user-customizable label for grouping. | "GitHub" | ⚠️ Defaults to "api". Source filter and all breakdowns by source lose meaning. |
Hello
`). | NLP processes HTML as text — Sentiment, Signal, and topic extraction accuracy degrade. | Strip all HTML tags before sending. Send plain text only. | | Text encoding is `latin-1` or `Windows-1252` instead of UTF-8. | Characters appear broken (`não` instead of `não`). NLP analysis produces garbage results. | Convert all files to UTF-8 before uploading. Common with Brazilian data exports. | | `account_id` values are inconsistent across record types (e.g., `"123"` in NPS but `"acct-123"` in tickets). | Cross-source analysis silently fails. Records exist as isolated silos — cannot correlate NPS detractors with their tickets. | Use the exact same `account_id` string across all Feedback, Conversation Message, and Account records. | | IDs are sequential integers reused across systems (e.g., Zendesk ticket `1` and Intercom ticket `1`). | Records overwrite each other (PUT semantics). Data loss. | Prefix IDs with the source system name: `"zendesk-1"`, `"intercom-1"`. | | Boolean fields use `"Sim"/"Não"`, `"Yes"/"No"`, or `"1"/"0"` instead of `true`/`false`. | Custom fields may be rejected or mistyped. `solved` field won't be recognized. | Convert to `true` / `false` before sending. | | `rating` uses wrong scale (e.g., NPS sent as 1–5 instead of 0–10, or CSAT as 0–100). | Record is accepted, but NPS Promoter/Detractor classification is wrong. All NPS/CSAT Dashboard metrics become meaningless. Code only logs a warning. | Confirm the expected scale: NPS = 0–10, CSAT = 1–5. Document the scale used in your source system. | | Conversation uploaded without any messages (or messages uploaded without a parent conversation). | Conversation is invisible in Birdie. Messages are orphaned. Neither appears in Exploration. | Always upload both Conversation and Message records together. Validate completeness before sending. | | `language` field uses full words (`"portuguese"`, `"english"`) instead of BCP 47 codes. | BCP 47 parsing fails. Falls back to auto-detection — NLP may use the wrong language model. | Use BCP 47 codes: `pt-BR`, `en`, `es`, `fr`, etc. | | `additional_fields` contain nested objects (e.g., `{"address": {"city": "SP"}}`). | ❌ Record is rejected. Only flat key-value pairs are accepted. | Flatten nested structures: `{"address_city": "SP"}`. | | `author_type` is missing on all messages. | All Conversation Features (50+ fields) = zero. FI Criteria produce false positives. FI Agent page is empty. | Set `author_type` on every message. This is the single most impactful optional field. | # Data Schema Definitions for Birdie Export ## Data Export Schema Definitions All data exported from Birdie—whether through manual CSV downloads or automated Data Forwarding—follows a standardized set of schemas. These definitions describe every file included in the export, its columns, data types, and expected values. Use this page as a reference when loading Birdie exports into your data warehouse, building dashboards, or integrating insights into downstream systems. *** ### 1. Overview Every Birdie export produces up to **eleven files**, organized into two groups based on their export behavior and loading strategy: **Full Export Files** (Truncate & Load) | File | Description | | --------------------------- | ------------------------------------------------------------ | | `collections.csv` | The complete list of Collections and their related entities. | | `workspace_collections.csv` | The list of Workspaces and the Collections they reference. | **Incremental Export Files** (Delete & Insert by key) | File | Delete Key | Description | | ------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------- | | `feedbacks.csv` | `ID` | The core feedback records (reviews, surveys, conversations). | | `opportunities.csv` | `Feedback ID` | Opportunities (Opps) detected within each feedback. | | `sentences.csv` | `Feedback ID` | Individual sentences extracted from feedback text, with NLP annotations. | | `messages.csv` | `Feedback ID` | Individual messages within conversation-type feedbacks. | | `areas.csv` | `Feedback ID` | Areas associated with each feedback. | | `area_opportunities.csv` | `opportunity_id` AND `area_id` | The many-to-many mapping between Areas and Opportunities referenced by exported feedbacks. | | `criteria.csv` | `Feedback ID` | Criteria labels associated with each feedback. Only present when there are matching labels. | | `reasons.csv` | `Feedback ID` | Reason labels associated with each feedback. Only present when there are matching labels. | | `segmentations.csv` | `Feedback ID` | Segmentation labels associated with each feedback. Only present when there are matching labels. | > **Note:** For incremental files, Birdie re-exports all child entities (opportunities, sentences, messages, areas, criteria, reasons, segmentations) whenever their parent feedback is updated. Always delete by the `Feedback ID` key before inserting to avoid duplicates. `area_opportunities.csv` is a junction table without a `Feedback ID` — delete by matching both `opportunity_id` and `area_id` from the new file. *** ### 2. Data Schemas #### feedbacks.csv The primary entity in Birdie's data model. Each row represents a single feedback record — a review, survey response, support ticket, complaint, or social media post. This file contains metadata, timestamps, ratings, and custom fields for every feedback processed by Birdie. | Column Name | Type | Description | | ------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | ID | STRING | Unique Birdie-generated identifier for the feedback (SHA-256 hash). | | Ingested ID | STRING | The original identifier from the source system, preserved as ingested. | | Source | STRING | The integration or connector that produced the record (e.g., `s3`, `api`). | | Source Alias | STRING | A user-customizable label for grouping feedbacks by origin (e.g., `nps`, `support_ticket`). | | Kind Name | STRING | The record type classification (e.g., `nps`, `csat`, `support_ticket`, `review`, `complaint`, `social_media`). | | Language | STRING | Language of the feedback text expressed as a BCP 47 code (e.g., `pt-BR`, `en`). | | Text | STRING | The primary text content of the feedback. For conversation-type records, this is typically the opening message or a consolidated view. | | Posted At | STRING | When the feedback was originally posted or submitted (RFC 3339 timestamp, e.g., `2025-05-04T00:24:27Z`). | | Batch ID | STRING | Identifier for the ingestion batch that brought this record into Birdie. | | Ingested At | STRING | When the record was first ingested into Birdie (RFC 3339 timestamp). | | Updated At | STRING | When the record was last updated within Birdie (RFC 3339 timestamp). | | Accounts | JSON ARRAY | A JSON array of account identifiers associated with this feedback (e.g., `["acc_hash_1", "acc_hash_2"]`). | | Total Messages | INTEGER | For conversation-type feedbacks, the total number of messages in the thread. Empty for non-conversation records. | | Messages First Posted At | STRING | Timestamp of the first message in the conversation thread (RFC 3339). Empty for non-conversation records. | | Messages Last Posted At | STRING | Timestamp of the last message in the conversation thread (RFC 3339). Empty for non-conversation records. | | Messages Users | STRING | Identifier or count of distinct users who participated in the conversation thread. | | Custom Fields | JSON OBJECT | A JSON object containing all custom fields configured for this record. Each key maps to an object with `description`, `type`, and `value` properties. | | Category | STRING | A classification label for segmenting feedbacks (e.g., product area, complaint type). | | Status | STRING | Current status of the feedback (e.g., `open`, `pending`, `closed`, `solved`). Primarily used for conversation-type records. | | URL | STRING | Direct link to the original feedback source, if available. | | Rating | FLOAT | A numerical score associated with the feedback (e.g., NPS 0–10, CSAT 1–5, or a review score). | | Author ID | STRING | Unique identifier for the author of the feedback. | | Author Name | STRING | Display name of the feedback author, if available. | | Title | STRING | The title or subject line of the feedback, as provided by the author or source system. | | Owner | STRING | Indicates the entity owner for competitive analysis (e.g., `Owner` or `Competitor`). | | Subject | STRING | The subject line of the support ticket or conversation, if applicable. | | Priority | STRING | Priority level assigned to the feedback (e.g., `urgent`, `high`, `medium`, `low`). Primarily used for support tickets. | | Channel | STRING | Source channel of the feedback (e.g., `web`, `email`, `chat`, `phone`). | *** #### messages.csv Contains the individual messages within conversation-type feedbacks (support tickets, complaints, social media threads). Each row represents a single message, linked to its parent feedback via `Feedback ID`. | Column Name | Type | Description | | ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | Feedback ID | STRING | The parent feedback identifier. References `ID` in `feedbacks.csv`. | | ID | STRING | Unique Birdie-generated identifier for this specific message. | | Ingested ID | STRING | The original message identifier from the source system. | | Source | STRING | The integration or connector that produced the record. | | Source Alias | STRING | A user-customizable label for grouping by origin. | | Kind Name | STRING | The record type classification (e.g., `support_ticket`). | | Language | STRING | Language of the message text as a BCP 47 code. | | Text | STRING | The actual content of the message. | | Posted At | STRING | When the message was posted (RFC 3339 timestamp). | | Batch ID | STRING | Identifier for the ingestion batch. | | Author ID | STRING | Unique identifier for the author of the message. | | Author Name | STRING | Display name of the message author, if available. | | Author Type | STRING | The role of the author within the conversation: `customer`, `agent`, or `bot`. | | Agent Supervisor ID | STRING | Identifier for the support agent's supervisor. Populated only when `Author Type` is `agent`. | | Agent Company | STRING | The company the support agent belongs to. Populated only when `Author Type` is `agent`. | | Agent Team | STRING | The team the support agent belongs to. Populated only when `Author Type` is `agent`. | | Agent Experience | STRING | The experience or seniority level of the agent (e.g., `junior`, `senior`). Populated only when `Author Type` is `agent`. | | Custom Fields | JSON OBJECT | A JSON object containing message-level custom fields, following the same structure as in `feedbacks.csv`. | | Ingested At | STRING | When the message was first ingested into Birdie (RFC 3339 timestamp). | | Created At | STRING | When the message record was created in Birdie's internal store (RFC 3339 timestamp). | | Updated At | STRING | When the message record was last updated within Birdie (RFC 3339 timestamp). | *** #### sentences.csv Contains the sentence-level NLP analysis produced by Birdie's processing pipeline. Each feedback text is broken into individual sentences, and each sentence is annotated with signal detection, sentiment, specificity, intentions, and product/service aspect tagging. | Column Name | Type | Description | | ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Feedback ID | STRING | The parent feedback identifier. References `ID` in `feedbacks.csv`. | | ID | STRING | Unique identifier for the sentence, formatted as `{Feedback ID}#{sequence_number}` (e.g., `abc123#0`, `abc123#1`). | | Language | STRING | Detected language of the sentence as a BCP 47 code. | | Sentence | STRING | The extracted sentence text. | | Signal | BOOLEAN | Whether the sentence contains a meaningful signal (`true` or `false`). Non-signal sentences (e.g., greetings, pleasantries) are marked `false`. | | Sentiment Value | STRING | The sentiment classification of the sentence. Possible values: `POSITIVE`, `NEGATIVE`, `MIXED`, `NEUTRAL`. | | Sentiment Intensity | STRING | The strength of the detected sentiment. Possible values: `LOW`, `MEDIUM`, `HIGH`. | | Specificity | STRING | How specific or actionable the sentence content is. Possible values: `LOW`, `MEDIUM`, `HIGH`. | | Intentions | JSON ARRAY | A JSON array of detected user intentions (e.g., `["REQUEST"]`, `["PROBLEM"]`, `["PRAISE"]`). | | Aspects Product | JSON ARRAY | A JSON array of product-related aspects or features mentioned in the sentence (e.g., `["máquina"]`, `["app"]`). | | Aspects Service | JSON ARRAY | A JSON array of service-related aspects mentioned in the sentence (e.g., `["atendimento"]`, `["suporte"]`). | *** #### opportunities.csv Maps feedbacks to Opportunities (Opps) — the insight clusters identified by Birdie's analysis. Each row represents a single feedback-to-opportunity association. One feedback may appear in multiple opportunities, and one opportunity groups many feedbacks. | Column Name | Type | Description | | -------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Opportunity ID | STRING | Unique identifier for the Opportunity (UUID). | | Opportunity Name | STRING | Human-readable name or description of the Opportunity. | | Feedback ID | STRING | The feedback identifier associated with this Opportunity. References `ID` in `feedbacks.csv`. | | Feedback Ingested ID | STRING | The original ingested identifier of the associated feedback. References `Ingested ID` in `feedbacks.csv`. | *** #### areas.csv Maps feedbacks to Areas — Birdie's thematic classification buckets. Each row represents a single feedback-to-area association. One feedback may belong to multiple areas. | Column Name | Type | Description | | -------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Area ID | STRING | Unique identifier for the Area (UUID). | | Area Name | STRING | Human-readable name of the Area (e.g., `Crédito \| Limite Extra`). | | Feedback ID | STRING | The feedback identifier associated with this Area. References `ID` in `feedbacks.csv`. | | Feedback Ingested ID | STRING | The original ingested identifier of the associated feedback. References `Ingested ID` in `feedbacks.csv`. | *** #### collections.csv Contains the definitions of Collections and their related entities. Collections are user-curated groupings used to organize Areas or other Birdie entities for monitoring and reporting. | Column Name | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------------------------- | | collection\_id | STRING | Unique identifier for the Collection (UUID). | | collection\_name | STRING | Human-readable name of the Collection (e.g., `Squads \| Beatriz & João`). | | collection\_type | STRING | The type of entity this collection groups. Possible values: `area_interest`. | | related\_id | STRING | The identifier of the related entity (e.g., an Area ID) that belongs to this Collection. | *** #### area\_opportunities.csv A junction table that maps the many-to-many relationship between Areas and Opportunities. Use this file to understand which Opportunities belong to which Areas referenced by feedbacks in the export window. | Column Name | Type | Description | | --------------- | ------ | -------------------------------------------------------------------------------------- | | opportunity\_id | STRING | The Opportunity identifier (UUID). References `Opportunity ID` in `opportunities.csv`. | | area\_id | STRING | The Area identifier (UUID). References `Area ID` in `areas.csv`. | *** #### criteria.csv Maps feedbacks to Criteria labels. Each row represents a single feedback-to-criteria association. The file is only produced when the export window contains feedbacks with matching criteria labels. | Column Name | Type | Description | | ------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Criteria ID | STRING | Unique identifier for the Criteria label (UUID). | | Criteria Name | STRING | Human-readable name of the Criteria label. | | Feedback ID | STRING | The feedback identifier associated with this Criteria. References `ID` in `feedbacks.csv`. | | Ingested ID | STRING | The original ingested identifier of the associated feedback. References `Ingested ID` in `feedbacks.csv`. | *** #### reasons.csv Maps feedbacks to Reason labels. Each row represents a single feedback-to-reason association. The file is only produced when the export window contains feedbacks with matching reason labels. | Column Name | Type | Description | | ----------- | ------ | --------------------------------------------------------------------------------------------------------- | | Reason ID | STRING | Unique identifier for the Reason label (UUID). | | Reason Name | STRING | Human-readable name of the Reason label. | | Feedback ID | STRING | The feedback identifier associated with this Reason. References `ID` in `feedbacks.csv`. | | Ingested ID | STRING | The original ingested identifier of the associated feedback. References `Ingested ID` in `feedbacks.csv`. | *** #### workspace\_collections.csv Maps Workspaces to the Collections they reference, including the filter definition of the workspace. One workspace may reference multiple collections. | Column Name | Type | Description | | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------- | | workspace\_id | STRING | Unique identifier for the Workspace (UUID). | | workspace\_name | STRING | Human-readable name of the Workspace. | | workspace\_filter | JSON OBJECT | A JSON object describing the workspace filter (e.g., custom field constraints, collection scope). | | collection\_id | STRING | The Collection identifier referenced by the workspace. References `collection_id` in `collections.csv`. | *** #### segmentations.csv Maps feedbacks to Segmentation labels. Each row represents a single feedback-to-segmentation association. The file is only produced when the export window contains feedbacks with matching segmentation labels. | Column Name | Type | Description | | ----------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Segmentation ID | STRING | Unique identifier for the Segmentation label (UUID). | | Segmentation Name | STRING | Human-readable name of the Segmentation label. | | Feedback ID | STRING | The feedback identifier associated with this Segmentation. References `ID` in `feedbacks.csv`. | | Ingested ID | STRING | The original ingested identifier of the associated feedback. References `Ingested ID` in `feedbacks.csv`. | *** ### 3. Data Types Reference | Type | Format | Example | | ------------------ | ------------------- | ----------------------------------------- | | STRING | UTF-8 text | `abc123`, `support_ticket` | | INTEGER | Whole number | `12`, `0` | | FLOAT | Decimal number | `5.0`, `8.5` | | BOOLEAN | Lowercase string | `true`, `false` | | JSON ARRAY | JSON-encoded array | `["value1", "value2"]` | | JSON OBJECT | JSON-encoded object | `{"key": {"type": "enum", "value": "X"}}` | | Timestamp (STRING) | RFC 3339 | `2025-05-04T00:24:27Z` | *** ### 4. Entity Relationships ``` feedbacks.csv (ID) ├── messages.csv (Feedback ID → feedbacks.ID) ├── sentences.csv (Feedback ID → feedbacks.ID) ├── opportunities.csv (Feedback ID → feedbacks.ID) ├── areas.csv (Feedback ID → feedbacks.ID) ├── criteria.csv (Feedback ID → feedbacks.ID) ├── reasons.csv (Feedback ID → feedbacks.ID) └── segmentations.csv (Feedback ID → feedbacks.ID) areas.csv (Area ID) └── area_opportunities.csv (area_id → areas.Area ID) opportunities.csv (Opportunity ID) └── area_opportunities.csv (opportunity_id → opportunities.Opportunity ID) collections.csv (collection_id) ├── related_id → areas.Area ID (when collection_type = area_interest) └── workspace_collections.csv (collection_id → collections.collection_id) ``` # Ingestion API The ingestion API can be used to upload data to Birdie directly. Clients upload data by making an HTTP PUT for each record they want to upload. The request must include a Birdie API key in an HTTP header in the form: Authorization: ApiKey {api-key} To generate an API key, you can reach out to the Birdie team and we will provide you one. Response status codes * 201 Created on success * 400 Bad Request if the request body is invalid (response body will be a JSON object with an error message) * 401 Unauthorized if the API key is missing or invalid * 503 Service Unavailable if too many requests are being made in a short amount of time {% hint style="danger" %} We suggest making up to 100 requests per second (6000 per minute) to the Birdie API to avoid 5XX errors. {% endhint %} ## JSON formats Most ingestion endpoints accept JSON payloads. Audio ingestion is the exception and uses `multipart/form-data` because it contains both structured metadata and binary recording content. Schema definitions for JSON payloads are available at:
| Section | Field | Required | Description |
|---|---|---|---|
| connection_details | host | Yes | Workspace URL, e.g. https://dbc-xxxx.cloud.databricks.com |
| connection_details | warehouse_id | Yes | Databricks SQL Warehouse ID. |
| connection_details.auth | method | Yes | Authentication mode: oauth (default) or pat. |
| connection_details.auth | client_id | OAuth | Service principal client ID. |
| connection_details.auth | client_secret | OAuth | Service principal client secret. |
| connection_details.auth | personal_access_token | PAT | Personal access token. |
| data_source | catalog | Yes | Unity Catalog name (optional for Hive Metastore). |
| data_source | schema | Yes | Schema or database name. |
| data_source | table | Yes | Table or view name. |
| data_source | partition_column | Yes | Column for incremental ingestion. Defaults to created_at |
| metadata | data_kind | Yes | The type(s) of data in the table, e.g. Support Ticket, NPS, CSAT, Review, Account. |