# RevCent Notes Overview This document provides a broad overview of Notes in RevCent: what they are, how they are created, what can create them, how they can be retrieved, how they can be queried, and why they are useful for ecommerce businesses. This is not only an operation guide. It explains Notes as a RevCent system capability. Sources: - RevCent operation schema for `CreateNote` - RevCent operation schema / documentation for `BigQueryRunQuery` - RevCent operation schema guidance for `GetBigQueryTables` - RevCent item detail behavior, such as `GetCustomer` returning a `notes` array --- # What Are Notes in RevCent? Notes are short, human-readable pieces of context attached to specific RevCent items. A note is useful when a human, AI workflow, support team, or automation needs to leave a concise explanation of something that happened. Examples: ```text Customer requested callback tomorrow afternoon. Support explained refund policy; customer accepted. Voice call: customer will retry payment Friday. Shipping address corrected after customer confirmation. Renewal failed; customer plans to update card after payday. ``` Notes help create a readable history of customer support, sales review, shipping issues, subscription activity, renewal follow-up, and AI/human interactions. --- # Why Notes Exist Ecommerce businesses often need a simple way to preserve human-readable context. A customer may contact support several times. A sale may need review. A subscription renewal may require follow-up. An AI Assistant or AI Voice Agent may learn something important from a customer. A Function may route an item to manual review. Notes give RevCent users and automation systems a way to save this context directly on the relevant item. Conceptually: ```text Customer/service/business interaction happens ↓ Important short context is summarized ↓ A note is created on the relevant RevCent item ↓ Humans, AI, Functions, BigQuery, and support workflows can use that context later ``` --- # What Items Can Have Notes? The `CreateNote` operation supports notes on these item types: ```text sale customer product_sale shipping subscription subscription_renewal ``` Examples: | Item Type | Example Note Use | |---|---| | `customer` | General support history, customer preferences, callback requests, escalation context. | | `sale` | Purchase-specific review, refund discussion, payment concern, order clarification. | | `product_sale` | Product-specific concern within a sale, replacement request, product issue. | | `shipping` | Address correction, delivery concern, tracking issue, fulfillment follow-up. | | `subscription` | Subscription preference, cancellation discussion, pause/continue context. | | `subscription_renewal` | Renewal failure follow-up, retry timing, payment update plan. | Use the item type that best reflects where the context belongs. --- # Note Text Length Limit Note text is limited to: ```text 255 characters ``` This limit encourages Notes to be short, readable, and operationally useful. Good note: ```text Customer requested callback tomorrow afternoon to update payment card. ``` Poor note: ```text A full transcript of the customer conversation with every statement, internal reasoning, multiple paragraphs, and detailed analysis. ``` If the content is too long, create a concise note and store detailed content elsewhere, such as: ```text Transcript system Document External CRM Support platform Internal log Metadata for structured outcome ``` --- # Notes Should Summarize Interactions, Not Create Play-by-Play Noise When creating notes from a customer interaction, try to summarize the complete interaction in one concise note. Do not create play-by-play notes during an active conversation. Avoid: ```text Customer said hello. Customer asked about refund. Customer paused. Customer asked another question. Customer sounded upset. Customer said maybe. ``` Better: ```text Customer asked about refund policy, declined refund for now, and requested email follow-up. ``` Notes should usually be created after the interaction reaches a meaningful stopping point. This keeps customer history readable and makes BigQuery reporting cleaner. --- # When Multiple Notes Are Appropriate Multiple notes are appropriate when they represent separate meaningful events. Example: ```text Monday: Customer requested callback Friday to update card. Friday: Customer updated card and asked to resume subscription. ``` That is useful because each note represents a separate interaction. Multiple notes are less useful when they are just fragments of the same live conversation. --- # What Can Create Notes? Notes can be created through several paths. ## 1. RevCent Web App Users Human users can create notes manually in RevCent. Examples: ```text Support agent adds a note after a customer call. Supervisor adds a review note on a sale. Operations user adds a note on a shipping issue. ``` This creates a human-readable audit trail for teams. --- ## 2. MCP Clients MCP clients can create notes by calling the `CreateNote` operation. This is useful when an MCP workflow has the right item context and the user asks to add a note. Example: ```json { "item_type": "customer", "item_id": "XXXXXXXXXXXXXXXXXXXX", "text": "Customer requested callback tomorrow afternoon." } ``` MCP should create notes only when: ```text The target item is known. The note is useful. The note is concise. The note is under 255 characters. The user requested it or the workflow clearly needs it. ``` --- ## 3. AI Assistants AI Assistants can create notes when an assistant interaction produces a concise outcome worth preserving. Examples: ```text Assistant resolved billing question and customer requested follow-up email. Assistant detected refund concern and escalated to support. Assistant confirmed customer wants to keep subscription and update card Friday. ``` AI Assistants should avoid creating play-by-play notes during a conversation. Preferred pattern: ```text Complete the assistant interaction or reach a meaningful stopping point. Create one concise note summarizing the interaction. Use metadata separately if structured reporting or automation is needed. ``` --- ## 4. AI Voice Agents AI Voice Agents can create notes when a voice call produces a useful call summary or customer-service outcome. Examples: ```text Voice call: customer requested callback tomorrow afternoon. Voice call: customer will retry payment after payday. Voice call: customer declined renewal and asked not to be called again. Voice call: customer confirmed corrected shipping address. ``` Voice Agents should not create one note for every turn in the call. A single concise call-summary note is usually best. --- ## 5. Functions Functions can create notes as part of automation. Examples: ```text Function routed renewal to manual review: high-value decline. Function synced shipment to warehouse and received confirmation. Function detected high-risk sale and notified support. Function processed chargeback evidence workflow. ``` Functions should use notes for human-readable context. For structured reporting, idempotency, and automation decisions, Functions should use metadata instead of or in addition to notes. --- ## 6. Direct API Calls and External Systems External systems can create notes through API workflows. Examples: ```text CRM creates note after support escalation. External AI agent creates note after reviewing customer history. Warehouse system creates note after delivery exception. Chargeback tool creates note after representment evidence update. ``` This can connect RevCent with other systems while keeping short operational context inside RevCent. --- # Notes vs Metadata Notes and metadata are both useful, but they are different. | Feature | Best For | |---|---| | Note | Short human-readable context. | | Metadata | Structured name/value data for search, reports, BigQuery, segmentation, and automation. | Example note: ```text Customer requested callback tomorrow afternoon. ``` Example metadata: ```json { "name": "ai_voice_outcome", "value": "callback_requested" } ``` Best practice: ```text Use notes for humans. Use metadata for structured reporting and automation. Use both when both human context and structured analysis are needed. ``` --- # Notes vs Key Values Notes are item-specific. Key Values are account-wide. | Feature | Scope | |---|---| | Note | Attached to one item. | | Key Value | Account-wide value accessed by key. | Use Notes for: ```text Customer support context Sale review comments Shipping issue summaries Subscription follow-up details ``` Use Key Values for: ```text support_email active_payment_profile daily_report_cursor vip_ltv_threshold feature flags ``` --- # Retrieving Notes To retrieve notes, retrieve the details of the item the notes are attached to. For example: ```text To retrieve customer notes, call GetCustomer. The GetCustomer response includes a notes array containing notes associated with the customer. ``` Conceptual flow: ```text User asks: "Show me notes for this customer." ↓ MCP identifies the customer_id. ↓ MCP calls GetCustomer. ↓ MCP reads the notes array. ↓ MCP presents the notes to the user. ``` The same principle applies to other item types: ```text To retrieve notes for a sale, retrieve the sale details. To retrieve notes for a subscription, retrieve the subscription details. To retrieve notes for a subscription renewal, retrieve the subscription renewal details. To retrieve notes for shipping, retrieve the shipping/shipment details. To retrieve notes for a product sale, retrieve the product sale details. ``` --- # Notes and BigQuery Notes can also be queried using `BigQueryRunQuery`. RevCent BigQuery includes a note table: ```sql `revcent.user.note` ``` The note table contains notes created using the API or within the web app. Use `BigQueryRunQuery` when the user wants: ```text Search across notes. Reports on notes. Counts or aggregations. Customer-service analysis. Support activity reports. Note content parsing. Timeframe analysis. ``` Use item detail retrieval when the user wants notes for one specific item. --- # Searching Notes With BigQuery BigQuery can search note text across many notes. Examples: ```text Find notes mentioning refund. Find notes mentioning callback. Find notes mentioning chargeback. Find notes mentioning cancellation. Find notes mentioning shipping address. Find notes mentioning angry or upset customers. ``` Conceptual SQL: ```sql SELECT id, text, created_date_unix FROM `revcent.user.note` WHERE LOWER(text) LIKE '%refund%' ORDER BY created_date_unix DESC LIMIT 100 ``` Important: ```text Use GetBigQueryTables first to confirm the exact note table fields before writing final SQL. ``` --- # Reporting on Notes Notes can support customer-service and operations reporting. Possible reports: ```text Notes created per day. Notes created per support user. Customers with the most notes. Notes by related item type. Notes containing refund-related terms. Notes containing cancellation-related terms. Average number of notes per customer. Customers with notes over a long support timeframe. ``` Conceptual daily note count: ```sql SELECT DATE(TIMESTAMP_SECONDS(created_date_unix)) AS note_date, COUNT(*) AS note_count FROM `revcent.user.note` GROUP BY note_date ORDER BY note_date DESC ``` --- # Customer-Service Timeframe Analysis Notes can help answer: ```text How long has this customer been interacting with customer service? ``` Conceptual approach: ```text Find all notes related to the customer. Find the first note date. Find the last note date. Calculate the number of days between them. Count total notes. ``` Conceptual SQL: ```sql SELECT customer_id, MIN(TIMESTAMP_SECONDS(created_date_unix)) AS first_note_at, MAX(TIMESTAMP_SECONDS(created_date_unix)) AS last_note_at, TIMESTAMP_DIFF( MAX(TIMESTAMP_SECONDS(created_date_unix)), MIN(TIMESTAMP_SECONDS(created_date_unix)), DAY ) AS support_interaction_days, COUNT(*) AS note_count FROM `revcent.user.note` WHERE customer_id = 'XXXXXXXXXXXXXXXXXXXX' GROUP BY customer_id ``` Important: ```text The actual customer-related field may not be named customer_id. Use GetBigQueryTables to confirm the note table schema. ``` --- # Customer-Service Performance Analysis Notes can help ecommerce businesses understand support load and support quality. Possible metrics: ```text Number of notes per support user. Number of customer interactions per day. Customers with repeated support issues. Most common support topics. Refund-related note volume. Shipping issue note volume. Callback request note volume. Average support history length per customer. ``` These reports can help businesses understand: ```text Which issues are increasing? Which customers require the most support? Which support topics lead to refunds or cancellations? Which products or campaigns create more support needs? How long do support issues remain active? Which support workflows need improvement? ``` --- # Sentiment and Content Parsing Notes can be used for simple keyword-based analysis or exported/queried for AI-based sentiment analysis. Examples: ```text Count notes mentioning angry, upset, frustrated, happy, resolved, refund, cancel, callback, or replacement. Classify notes into support topics. Track negative note volume over time. Identify customers with repeated negative support notes. Analyze support outcomes from note text. ``` Simple keyword-based example: ```sql SELECT DATE(TIMESTAMP_SECONDS(created_date_unix)) AS note_date, COUNT(*) AS total_notes, SUM(IF(REGEXP_CONTAINS(LOWER(text), r'angry|upset|frustrated|mad'), 1, 0)) AS negative_keyword_notes, SUM(IF(REGEXP_CONTAINS(LOWER(text), r'happy|resolved|thank'), 1, 0)) AS positive_keyword_notes FROM `revcent.user.note` GROUP BY note_date ORDER BY note_date DESC ``` This is not full sentiment analysis, but it can provide useful directional insights. For deeper sentiment analysis, an AI workflow or external analytics pipeline can parse note content. --- # Notes and Customer Support Teams Notes are highly valuable for support teams. They help support staff understand: ```text What happened previously. What the customer requested. What was promised. Whether the issue was escalated. Whether the customer needs follow-up. Whether the customer is frustrated or satisfied. ``` This creates better customer support because a support agent or AI system does not need to start from scratch. --- # Notes and AI Workflows Notes are useful for AI Assistants and AI Voice Agents because they provide short human-readable context. Examples: ```text AI Assistant checks prior customer notes before responding. AI Voice Agent receives prior notes before making an outbound call. A Function parses note.created events to trigger follow-up workflows. An external AI agent monitors notes for urgent support issues. ``` Notes can also be used alongside metadata. Example: ```text Note: "Voice call: customer requested callback tomorrow afternoon." Metadata: ai_voice_outcome = callback_requested ``` The note helps humans understand the context. The metadata helps reports and automation. --- # Notes and Automation A note can be an operational signal. A `note.created` event can trigger workflows such as: ```text Function execution. AI Assistant workflow. AI Voice Agent workflow. External webhook or endpoint. Third-party AI agent monitoring. Support escalation. Customer follow-up. ``` Example: ```text Note created: "Customer requested callback tomorrow afternoon." ↓ Function parses note. ↓ Function inserts structured metadata. ↓ AI Assistant or support team follows up. ``` For automation-heavy workflows, use notes carefully and consistently. If the automation depends on exact outcomes, metadata is usually better than free-form note text. --- # Notes for Ecommerce Businesses Notes help ecommerce businesses improve: ```text Customer support continuity. Revenue recovery. Subscription retention. Shipping issue resolution. Refund/chargeback handling. AI workflow context. Customer-service reporting. Operational accountability. Customer history visibility. ``` Examples: ## Revenue Recovery ```text Renewal failed; customer will retry after payday. Customer requested new card link. Customer asked for callback before retry. ``` ## Shipping Support ```text Customer confirmed corrected shipping address. Replacement shipment requested. Customer reported package missing. ``` ## Refund and Chargeback Support ```text Customer asked for refund policy clarification. Support explained chargeback evidence process. Customer disputes subscription renewal. ``` ## Subscription Support ```text Customer wants to pause subscription for one month. Customer wants to keep subscription and update card Friday. Customer asked about renewal date. ``` --- # Best Practices ## 1. Keep Notes Short Notes are limited to 255 characters. Use concise summaries. ## 2. Summarize Complete Interactions Do not create play-by-play notes. Create one note that summarizes a meaningful interaction. ## 3. Use Metadata for Structured Outcomes If the business needs reports or automation, use metadata. ## 4. Avoid Sensitive Data Do not store: ```text Full card numbers CVV Passwords API keys Private credentials Sensitive payment data ``` ## 5. Avoid Internal AI Reasoning Do not store AI chain-of-thought or internal reasoning traces. Use the final human-readable outcome only. ## 6. Use Consistent Language Consistent notes make BigQuery search and parsing more useful. ## 7. Use BigQuery for Cross-Note Analysis Use `BigQueryRunQuery` and the `note` table for searching/reporting across notes. ## 8. Use Item Detail Retrieval for One Item Use operations such as `GetCustomer` when retrieving notes for one customer or item. --- # MCP/AI Guidance When handling notes, MCP/AI should: 1. Determine whether the user wants to create a note or retrieve notes. 2. Use `CreateNote` only for creating notes. 3. Retrieve item details to view notes for a specific item. 4. Use `BigQueryRunQuery` for cross-note search/reporting. 5. Keep note text under 255 characters. 6. Condense customer interactions into one concise note whenever possible. 7. Avoid play-by-play notes. 8. Avoid full transcripts or long summaries. 9. Use metadata for structured reportable outcomes. 10. Use `GetBigQueryTables` before writing note-table SQL. 11. Avoid secrets, credentials, raw payment data, and internal AI reasoning. 12. Write notes that will help future humans, AI systems, or workflows. --- # Summary Notes in RevCent are short, human-readable records attached to specific items. They can be created by: ```text Humans in the RevCent web app MCP clients AI Assistants AI Voice Agents Functions Direct API calls External systems ``` They are useful for: ```text Customer support history Sale review Shipping follow-up Subscription retention Renewal salvage AI workflow context Support escalation Customer-service reporting BigQuery note analysis ``` The most important concepts are: ```text Notes are limited to 255 characters. Notes should summarize interactions, not create play-by-play logs. CreateNote creates notes. Item detail operations retrieve notes for a specific item. BigQueryRunQuery can query the note table for search and reporting. Metadata should be used for structured reportable outcomes. Notes should be concise, useful, and safe. ``` Used well, Notes make RevCent a stronger customer history, support, AI, and operations system for ecommerce businesses. --- Document Parent Directory * [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.