Contact Association

Contact association enables you to track interactions with specific users across multiple conversations, tasks, and API calls. The platform supports two primary patterns for contact association: referencing existing contacts by ID, or automatic contact creation and retrieval using fingerprint-based identification.

Using Contact IDs

When you already have a contact record in the platform, you can reference it directly using its unique identifier. This approach requires the contact to exist before making the API call:

If the specified contact ID does not exist or you don't have access to it, the API will return an error. This pattern is ideal when you're managing contacts separately and have already created them through the contact management APIs.

Using Contact Fingerprints (Automatic Creation)

The fingerprint-based approach provides a powerful way to ensure contacts exist without requiring separate API calls. Instead of providing a contact ID, you provide a contact object with a unique fingerprint that identifies the user:

How Fingerprint-Based Contact Creation Works:

1. Lookup: The platform searches for an existing contact with the provided fingerprint in your account.

2. Return Existing: If a contact with that fingerprint exists, it's retrieved and used for the interaction. The contact's existing data is preserved.

3. Create New: If no contact exists with that fingerprint, a new contact is automatically created with the provided information and associated with the interaction.

This approach eliminates the need for separate "check if contact exists, then create if needed" logic in your application code. You can make a single API call and trust that the contact will be handled appropriately.

Creating Effective Fingerprints

The fingerprint is a unique identifier that represents the user across all interactions. The recommended approach is to use UUID v5 (namespace-based) hashing to create deterministic, collision-resistant fingerprints from user identifiers.

Email-Based Fingerprints (Recommended for Known Users):

Important: Always normalize email addresses by converting to lowercase and trimming whitespace before hashing to avoid creating duplicate contacts for the same user.

Internal User ID Fingerprints (Recommended for Integrated Systems):

This approach is ideal when integrating with existing systems that have their own user identification schemes. It ensures consistency between your system and ChatBotKit contacts while keeping the actual user ID private.

Session-Based Fingerprints (for Anonymous Users):

Useful for tracking anonymous users across a session before they're identified. Once the user provides identifying information, you can create a new contact with a more stable fingerprint based on their email or user ID.

Composite Fingerprints (for Multi-Tenant Systems):

This pattern ensures contacts are unique within tenant boundaries in multi-tenant applications while maintaining deterministic fingerprint generation.

Why UUID-Based Hashing?

Using cryptographic hashing to create fingerprints offers several advantages:

• Deterministic: The same input always produces the same fingerprint
• Collision-resistant: Extremely unlikely to generate duplicate fingerprints
• Privacy-friendly: The original identifier cannot be reverse-engineered
• Consistent length: All fingerprints have the same length regardless of input
• Error-proof: No string concatenation issues or special character handling

Benefits of Fingerprint-Based Contact Management

Eliminates Pre-Flight Requests:

Without fingerprints, you'd need to make separate API calls to check if a contact exists and create it if needed. With fingerprints, this happens automatically in a single request:

Improves Performance and Reliability:

Reducing API calls means faster response times and fewer opportunities for network failures or race conditions. Your application becomes more resilient and responsive.

Simplifies Integration Code:

You don't need complex contact management logic in your application. The platform handles contact lifecycle management automatically based on fingerprints.

Prevents Duplicate Contacts:

As long as you use consistent, normalized fingerprints, the platform ensures you won't create duplicate contacts for the same user, even if making concurrent requests.

Common Use Cases

Customer Support Integration:

Track all support interactions for a specific customer by their email:

SaaS Application Integration:

Associate conversations with users from your application:

Task Execution with User Context:

When running background tasks, maintain user context:

Contact Data Fields

When providing a contact object with a fingerprint, you can include:

• fingerprint (required): Unique identifier for the contact
• name (optional): Display name for the contact
• description (optional): Additional description or notes
• email (optional): Email address
• phone (optional): Phone number
• nick (optional): Nickname or short identifier
• meta (optional): Custom metadata object for storing additional information

All fields except fingerprint are optional. On subsequent requests with the same fingerprint, the existing contact data is used, and the provided fields are not updated. If you need to update contact information, use the dedicated contact update API endpoints.

Important Considerations

Fingerprint Uniqueness:

Fingerprints must be unique within your account. Using the same fingerprint for different users will result in interactions being associated with the same contact record.

Fingerprint Stability:

Choose fingerprints based on stable identifiers. Avoid using session tokens or temporary IDs that change frequently, as this will create many separate contact records instead of consolidating interactions under a single contact.

Normalization:

Always normalize your fingerprint inputs to ensure consistency:

Privacy Considerations:

Be mindful of including personally identifiable information (PII) in fingerprints and contact data. Ensure compliance with privacy regulations like GDPR and CCPA when storing user information.

Concurrent Requests:

The platform handles concurrent requests with the same fingerprint gracefully. If multiple requests attempt to create a contact with the same fingerprint simultaneously, only one contact will be created, and all requests will use that contact.

Endpoints Supporting Contact Association

The contactId parameter (supporting both ID and fingerprint patterns) is available in various API endpoints:

• Conversation APIs: /api/v1/conversation/complete, /api/v1/conversation/{conversationId}/complete
• Task APIs: Task creation and execution endpoints
• Other interaction endpoints: Any endpoint that supports user context tracking

The behavior is consistent across all endpoints: provide either a string ID for existing contacts, or a contact object with fingerprint for automatic creation.

Best Practices

1. Use fingerprints for new integrations: Unless you have a specific need to manage contacts separately, use the fingerprint pattern for simpler code and better performance.

2. Choose stable identifiers: Base fingerprints on user IDs, email addresses, or other identifiers that remain constant across sessions.

3. Normalize all inputs: Always normalize emails, trim whitespace, and handle case sensitivity consistently.

4. Include useful metadata: Use the meta field to store additional context that helps with analytics and reporting.

5. Document your fingerprint format: Establish and document a consistent fingerprint format across your application to avoid confusion and errors.

6. Test with real data: Ensure your fingerprint generation logic works correctly with real user data, including edge cases like special characters in emails.