Contact Management

Contacts are the customer identity layer in RapiDesq. Every person who interacts with your organization — whether they chat, email, submit a form, or are imported from an external system — is represented by a contact record. Contacts aggregate all interactions across every channel into a single, unified profile, giving your agents complete context for every conversation.

Overview

A contact record is the central identity for a customer within your RapiDesq tenant. Rather than treating each conversation or ticket as an isolated event, RapiDesq links them all back to a single contact. This means:

• An agent handling a live chat can instantly see that the same customer emailed about a related issue last week.
• A supervisor reviewing ticket volume can see a customer's full history across chat, email, and web form submissions.
• Your team avoids asking customers to repeat themselves because all prior context is in one place.

Contact records are automatically created and matched as interactions arrive. RapiDesq uses email address as the primary deduplication key, so when the same person reaches out through different channels using the same email, everything is linked to one contact. For logged-in users on your website, identity authentication provides even stronger matching by verifying the visitor's identity via JWT.

How Contacts Are Created

Contacts enter RapiDesq through several sources. Each contact record tracks its origin, so you always know how a customer first reached you. The contact source is set automatically at creation and preserved for reporting and auditing.

Chat Widget (Anonymous)

When an anonymous visitor starts a chat on your website through the RapiDesq chat widget, a contact record is created once they provide identifying information. This typically happens in one of two ways:

• Pre-chat form — If you configure a pre-chat form on the widget (name, email, etc.), the contact is created from that data before the conversation begins. This is the recommended approach because it enables deduplication from the first message.
• During conversation — A conversation flow can collect the visitor's name and email mid-chat using collector steps, creating or matching a contact at that point.

Contacts created this way have source CHAT_WIDGET. Until the visitor provides an email address, they exist as an anonymous session without a linked contact record.

Authenticated Chat Widget

If your website uses identity authentication on the chat widget, the visitor's identity is verified via a JWT generated by your backend. RapiDesq reads the verified claims (email, name, user ID) from the token and either matches an existing contact by email or creates a new one automatically. No pre-chat form is needed because the identity is already known.

Contacts created or matched this way have source AUTHENTICATED_WIDGET. These contacts are marked as identity-verified in the agent's view, providing a higher level of trust. See Identity Authentication for setup details.

Inbound Email

When an email arrives at one of your connected email channels, RapiDesq extracts the sender's email address and display name. If a contact with that email address already exists, the inbound email (and its resulting ticket) is linked to that contact. If no match is found, a new contact is created with source EMAIL.

This means a customer who first chatted with you and later sends an email using the same address will see both interactions on the same contact record — no manual linking required.

Web Form Submissions

When a visitor submits a web form, RapiDesq uses the email field from the submission to match or create a contact. If the email matches an existing contact, the form submission and resulting ticket are linked to that contact. Otherwise, a new contact is created with source WEB_FORM.

Web form field mappings also allow you to populate custom fields on the contact from form data, so information like account number or product type flows directly into the contact profile.

API and Webhook

Contacts can be created programmatically through the RapiDesq API or from external webhook events. This is useful for:

• CRM synchronization — Push contacts from your CRM into RapiDesq so agents have customer data before the first interaction.
• Event-driven creation — Automatically create a contact when a user signs up in your application, when a subscription changes, or when any external event occurs that should be tracked.
• Third-party integrations — Connect tools like Zapier, Make, or custom middleware to create contacts from any source.

Contacts created via the REST API have source API. Contacts created from inbound webhook events have source WEBHOOK. In both cases, email-based deduplication applies — if the email already exists on a contact, the existing contact is returned rather than creating a duplicate.

Bulk Import

You can import contacts in bulk from a CSV file or from an external CRM. Navigate to Admin > Contacts > Import to upload a file. During import, RapiDesq matches each row by email address. Rows matching an existing contact update that record; rows without a match create new contacts with source IMPORT.

This is the fastest way to populate RapiDesq with your existing customer base when you first set up the platform.

Manual Creation

Agents and admins can create contacts directly in the UI. Navigate to Admin > Contacts and click New Contact. Fill in the contact's name, email, phone, and any custom fields, then save. Manually created contacts have source MANUAL.

This is useful when an agent is on a phone call or receives information through an offline channel and wants to ensure a contact record exists before the customer reaches out digitally.

Email-Based Deduplication

Email address is the primary deduplication key for contacts within a tenant. Whenever an interaction arrives that includes an email address — whether from an inbound email, a chat widget pre-chat form, a web form submission, an API call, or an import — RapiDesq checks whether a contact with that email already exists.

• If a match is found, the interaction (conversation, ticket, form submission) is linked to the existing contact. No duplicate is created.
• If no match is found, a new contact is created with the provided email and any other available details.

This automatic matching is the foundation of the unified contact profile. Consider this scenario:

1. A customer named Sarah visits your website and starts a chat. The pre-chat form collects her email: sarah@example.com. A contact is created with source CHAT_WIDGET.
2. Two days later, Sarah sends an email to your support address from sarah@example.com. RapiDesq matches the sender to the existing contact. The email ticket is linked to Sarah's record.
3. A week later, Sarah submits a web form using the same email. Again, the form submission is linked to her existing contact.

The result is a single contact for Sarah with a complete timeline of all three interactions across three different channels. Her agent can see the full picture without any manual effort.

Contact Profiles

Every contact has a profile that serves as the central record for that customer. The profile contains:

Agents see the contact profile in the right panel when handling a conversation or ticket. This gives them immediate access to the customer's identity, history, and any custom data your team has captured — without leaving the conversation view.

Custom Fields

Custom fields extend contact profiles with data specific to your business. They are stored using flexible JSONB storage, which means you can define any number of fields without schema changes. Custom fields appear on the contact profile alongside standard fields, and agents can view and edit them during conversations.

Defining Custom Fields

To create custom fields, navigate to Admin > Contacts > Custom Fields:

1. Click Add Field.
2. Choose a field type:
   • Text — Free-form text input for names, identifiers, or descriptions.
   • Number — Numeric values for quantities, scores, or IDs.
   • Dropdown — A predefined list of options for standardized data entry (e.g., subscription tiers, regions).
   • Date — A date picker for renewal dates, contract start dates, or other temporal data.
   • Checkbox — A boolean toggle for yes/no attributes (e.g., VIP status, opted into beta).
   • URL — A clickable web address for linking to external profiles or dashboards.
3. Enter a display name and optional description for the field.
4. For dropdown fields, define the list of available options.
5. Save the field. It immediately becomes available on all contact profiles.

Populating Custom Fields

Custom fields can be populated through several mechanisms:

• Manually by agents — Agents can edit custom field values directly on the contact profile during or after a conversation.
• Web form mappings — Map web form fields to contact custom fields so that form submissions automatically populate the contact record. For example, map a "Company size" form field to a "Company size" custom field on the contact.
• Conversation flows — Use the SET_VARIABLE and UPDATE_TICKET actions in conversation flows to collect information during a chat and write it to the contact's custom fields.
• API — Set custom field values when creating or updating contacts via the REST API.
• Bulk import — Include custom field columns in your CSV import file to populate fields for many contacts at once.

Example Custom Fields

Here are some commonly used custom fields by business type:

• Account number (Text) — Link the contact to your internal customer ID for quick lookups.
• Subscription tier (Dropdown: Free, Pro, Enterprise) — Helps agents understand the customer's service level at a glance.
• Region (Dropdown) — Track geographic region for routing, reporting, and timezone awareness.
• Preferred language (Dropdown) — Ensure agents communicate in the customer's preferred language.
• Contract renewal date (Date) — Proactively flag contacts approaching renewal.
• VIP (Checkbox) — Mark high-value contacts for priority handling.

Identity Authentication

Identity authentication lets you verify the identity of visitors who use the chat widget on your website. When a logged-in user on your site opens the chat widget, your backend generates a JWT containing the user's identity (email, name, user ID). RapiDesq verifies the JWT and links the chat session to the verified contact. This eliminates the need for a pre-chat form for known users and provides a stronger guarantee of the visitor's identity.

How It Works

1. Enable identity authentication on your chat widget configuration in Admin > Chat Widget > Identity Authentication. This generates a shared secret key.
2. Generate a JWT on your backend when a user is logged in to your website. The JWT payload must include the user's identity claims (email, name, and optionally a user ID). Sign the JWT using the shared secret with the HS256 algorithm.
3. Pass the JWT to the chat widget when initializing it on the page. The widget sends the token to RapiDesq with each session.
4. RapiDesq verifies the JWT using the shared secret. If the token is valid, RapiDesq reads the claims and either matches an existing contact by email or creates a new contact with source AUTHENTICATED_WIDGET.
5. The chat session is linked to the verified contact. The agent sees the contact's full profile and a verification badge indicating the identity is confirmed.

Why It Matters

• Prevents impersonation — Without identity authentication, anyone can type any email address into a pre-chat form. With identity auth, the email comes from a signed JWT that your backend generated, so the identity is cryptographically verified.
• Seamless experience for known users — Logged-in users skip the pre-chat form entirely. Their identity is already verified, so the conversation starts immediately with full context.
• Automatic contact matching — The verified email from the JWT is used for deduplication, so returning customers are automatically matched to their existing contact record and see their conversation history.
• Agent confidence — Agents can see that the contact is identity-verified, giving them confidence to discuss account-specific details without additional verification steps.

Merging Contacts

Despite automatic deduplication, duplicate contacts can still occur. For example, a customer may have chatted anonymously (without providing an email) and later sent an email, resulting in two separate contact records. Contact merging lets you unify these duplicates into a single record.

When to Merge

Common scenarios where merging is needed:

• A customer chatted anonymously (no email collected) and later contacted you via email. Two records exist: one with no email (from chat) and one with an email (from email).
• A customer used two different email addresses across interactions (e.g., a personal and a work email).
• Contacts were imported from an external system that had its own duplicates.
• A typo in an email address during a previous interaction created a separate record.

Merge Process

1. Navigate to the contact you want to keep as the primary record. This is the contact whose name, email, and other profile details will be preserved.
2. Click Merge Contact in the contact profile actions.
3. Search for and select the duplicate contact to merge into the primary.
4. Review the merge preview, which shows exactly what will happen:
   • The primary contact retains its name, email, phone, and other profile fields.
   • All tickets, conversations, and interaction history from the duplicate are transferred to the primary contact.
   • The duplicate contact's status is set to MERGED.
5. Confirm the merge.

What Happens After a Merge

• The primary contact now has a unified timeline that includes interactions from both records.
• The merged (duplicate) contact's record is preserved with status MERGED and a reference to the primary contact. This provides a complete audit trail — you can always trace back which records were merged and when.
• Any open tickets or conversations that belonged to the duplicate are now associated with the primary contact. Agents working on those tickets will see the primary contact's profile going forward.

Contact Statuses

Every contact has a status that reflects its current state in the system:

Soft Deletes and Data Retention

When you delete a contact, RapiDesq performs a soft delete: the deletedAt timestamp is set, but the record and its associated data are retained in the database. The contact is immediately removed from all normal views, search results, and reports.

This approach supports two important requirements:

• GDPR and compliance — Before a contact's data is permanently removed, you can export it for the data subject (fulfilling data portability requirements). The soft-deleted record is retained for a configurable retention period, during which export and audit operations remain possible.
• Audit trail — The retained record provides a history of when the contact existed and when it was deleted, which is important for compliance auditing.

After the retention period expires, a scheduled process performs a hard deletion, permanently removing the contact record and associated data from the database. This ensures that data is not retained indefinitely after a deletion request.

Interaction History

The interaction history is one of the most valuable features of the contact profile. It provides a unified, chronological timeline of every conversation and ticket associated with the contact, across all channels.

What the Timeline Shows

• Chat conversations — Full chat transcripts from the chat widget, including any bot interactions from conversation flows.
• Email threads — Complete email conversations, including agent replies and customer responses.
• Web form submissions — The form data submitted and the resulting ticket.
• Ticket details — Each entry shows the ticket status, assigned agent or team, priority, and resolution information.
• Channel indicator — Each interaction is labeled with its channel, so you can see at a glance whether the customer reached out via chat, email, or web form.

Filtering the Timeline

For contacts with many interactions, you can filter the timeline to find what you need:

• By channel — Show only chat conversations, only email threads, or only form submissions.
• By date range — Narrow to a specific time period to find interactions from last week, last month, or any custom range.
• By ticket status — Show only open tickets, only resolved tickets, or only tickets in a specific state.

Using History During Conversations

When an agent is handling a live conversation or working on a ticket, the contact's interaction history is displayed in the right panel. This gives the agent immediate context:

• Has this customer contacted us before? How many times?
• What was the last issue about? Was it resolved?
• Are there any open tickets for this customer that might be related?
• Which channels has this customer used in the past?

This context helps agents provide faster, more personalized support without asking the customer to repeat information from previous interactions.

Searching and Filtering Contacts

The contact list in Admin > Contacts provides tools to find and segment your contacts:

Search

The search bar matches against multiple fields simultaneously:

• Name — First name, last name, or full name.
• Email address — Exact or partial email match.
• Phone number — Exact or partial phone match.
• Custom field values — Search finds matches in custom field data as well, so you can search by account number, company name, or any other custom field.

Filters

Use filters to narrow the contact list by specific criteria:

• Source — Filter by how the contact was created (Chat Widget, Email, Web Form, API, Import, Manual, etc.).
• Status — Filter by contact status (Active, Merged, Deleted).
• Date range — Filter by contact creation date or last updated date.
• Custom fields — Filter by custom field values, such as all contacts in a specific region or with a specific subscription tier.

Sorting

Sort the contact list by:

• Name (alphabetical)
• Most recent interaction — Contacts who interacted most recently appear first.
• Creation date — Newest or oldest contacts first.
• Ticket count — Contacts with the most tickets appear first, useful for identifying high-touch customers.

Export

Export your contact list (or a filtered subset) for external reporting, analysis, or compliance purposes. Exported data includes all standard fields and custom fields for each contact in the result set.

Tips & Best Practices

Maximize Deduplication Accuracy

• Always collect email early — Configure a pre-chat form on your chat widget that includes an email field. This ensures that even anonymous chat visitors are matched to existing contacts from their very first message.
• Require email on web forms — Make the email field required on all web forms to ensure every submission can be deduplicated.
• Use identity authentication for logged-in users — If visitors to your website are logged in, enable JWT-based identity authentication on the chat widget. This provides automatic, verified contact matching with no pre-chat form needed.

Maintain Data Quality

• Review and merge duplicates regularly — Periodically review your contact list for potential duplicates and merge them. Duplicates are most likely when contacts are created from anonymous chat sessions (no email) and later matched to a known customer.
• Keep profiles up to date — Encourage agents to verify and update contact details during interactions. A phone number or name may have changed since the last interaction.
• Clean up on import — When importing contacts from external systems, clean and normalize email addresses before import to avoid creating duplicates due to formatting differences.

Make the Most of Custom Fields

• Align fields with your business data — Define custom fields that reflect the data points your agents actually need during conversations (account number, subscription tier, contract status).
• Automate field population — Use web form mappings and conversation flow actions to populate custom fields automatically rather than relying on agents to enter data manually.
• Use dropdowns for standardized data — When possible, use dropdown fields instead of free text to ensure consistent data entry and enable reliable filtering.

Optimize Agent Workflow

• Leverage interaction history — Train agents to check a contact's history before responding. Context from previous interactions leads to faster resolutions and better customer experiences.
• Use search and filters for proactive outreach — Filter contacts by custom fields (e.g., all Enterprise-tier contacts in a specific region) to identify groups for targeted follow-ups or announcements.
• Export for reporting — Use contact export to analyze customer data externally, create reports for stakeholders, or synchronize with your CRM.