How can we help you?

1. Overview & System Requirements

The Gravity Forms Crisp Chat Integration bridges your WordPress forms with the powerful Crisp Shared Inbox customer messaging platform. In high-velocity customer support and sales operations, visitors often submit complex contact requests, technical support tickets, quote inquiries, or return requests through structured forms. With this integration, every form submission immediately creates a new conversation or appends a message to an existing customer thread in Crisp.

Beyond simple message passing, the add-on syncs customer profile details—including full name, phone number, company role, avatar, custom metadata attributes, and segments—directly into the visitor’s Crisp sidebar. When your support representatives or sales agents respond from the Crisp web app or mobile app, they have full context without switching tabs or searching separate email threads. This eliminates communication silos, reduces response times, and delivers a unified customer experience across web chat, email, and contact forms.

2. Authentication & Crisp API Credentials Setup

The integration authenticates securely with the Crisp REST API using an encrypted Token Identifier and Secret Key pair:

Generating Your Crisp API Token

1. Log in to your Crisp Dashboard at app.crisp.chat.
2. Navigate to Settings → Workspace Settings → Integrations or visit marketplace.crisp.chat.
3. Click New Plugin or API Tokens to generate a private integration token.
4. Under required scopes, ensure you enable permissions for website:conversation:initiate, website:conversation:messages, and website:people:profile.
5. Copy your Website ID (UUID format), Identifier Token, and Key Secret.

Configuring Plugin Settings in WordPress

1. In WordPress, navigate to Forms → Settings → Crisp.
2. Enter your Website ID, Identifier Token, and Key Secret into the respective fields.
3. Click Test Connection. The system performs an authenticated ping to verify access against your Crisp inbox. Upon success, a confirmation checkmark will appear.
4. Click Save Settings to store your credentials securely in the WordPress database.

3. Feed Configuration & Field Mapping

With credentials validated, configure a dedicated feed for each form to manage how entries map to Crisp conversations and profiles:

Customer Profile & Conversation Mapping

• Customer Identification: Map the Work Email and Full Name fields. Crisp uses the email address as the primary unique customer key to locate existing chat sessions.
• Phone & Location: Map international phone number, country, and city fields into the Crisp contact profile.
• Initial Message Body: Construct the conversation message using Gravity Forms merge tags (e.g. Support Request: {Subject:2} - Details: {Message:4}).
• Custom Data Attributes: Map custom fields such as Order ID, Subscription Plan, or License Key directly into the Crisp contact custom data object.
• Segment Assignment: Assign targeted tags or segments (e.g. lead, vip-customer, urgent-bug) to organize conversations in the Crisp inbox.

Conditional Logic & Inbox Routing

Leverage Gravity Forms conditional logic to control when conversations are initiated in Crisp:

• Departmental Triage: Route inquiries with category “Billing” to a dedicated billing feed tagged with finance, while “Technical Issue” feeds are tagged with tier-2-support.
• Spam & Inquiry Filtering: Prevent unsolicited automated spam or vendor pitches from cluttering your live support inbox by screening out specific submission flags.

4. Advanced Workflows & Unified Messaging Architecture

Deploying Crisp with Gravity Forms unlocks unified multi-channel workflows for customer-facing teams:

• Seamless Omnichannel Support: If a customer previously engaged on live chat and later submits a formal warranty claim form, the submission is automatically appended to their existing conversation history.
• Automated Agent Assignment: Based on the form subject or selected department, Crisp routing rules can instantly assign incoming conversations to specialized team members.
• VIP Priority Escalation: High-value clients submitting enterprise onboarding forms can be automatically flagged with urgent status to trigger push notifications on agents’ mobile devices.
• File Attachment Sync: User-uploaded files (such as screenshots, invoices, or error logs) are embedded as secure links within the initial Crisp message body.

5. Troubleshooting & Diagnostic Error Matrix

When message delivery or profile sync encounters issues, consult the following diagnostic matrix:

6. Developer Extensibility & Filter Hooks

Developers can programmatically tailor Crisp conversation payloads or attach contextual custom data before submission:

/**
 * Filter: gform_crisp_conversation_payload
 * Purpose: Dynamically modify the conversation initiation payload prior to sending to Crisp.
 * 
 * @param array $payload The formatted API request body for Crisp conversation.
 * @param array $feed    The Gravity Forms Crisp feed configuration.
 * @param array $entry   The submitted Gravity Forms entry object.
 * @param array $form    The active form object.
 * @return array Modified payload array.
 */
add_filter( 'gform_crisp_conversation_payload', function( $payload, $feed, $entry, $form ) {
    // Append client IP address and user agent to internal metadata
    $payload['meta']['user_agent'] = rgar( $entry, 'user_agent' );
    $payload['meta']['ip_address'] = rgar( $entry, 'ip' );

    // If submitted by a logged-in user, tag with user role
    if ( is_user_logged_in() ) {
        $user = wp_get_current_user();
        $payload['segments'][] = 'registered-user';
        $payload['segments'][] = implode( '-', $user->roles );
    }

    return $payload;
}, 10, 4 );

/**
 * Action: gform_crisp_post_message_sent
 * Purpose: Store Crisp session ID or conversation URL in Gravity Forms entry metadata.
 * 
 * @param array $response HTTP response returned from Crisp REST API.
 * @param array $entry    The active Gravity Forms entry.
 */
add_action( 'gform_crisp_post_message_sent', function( $response, $entry ) {
    $body = json_decode( wp_remote_retrieve_body( $response ), true );
    if ( ! empty( $body['data']['session_id'] ) ) {
        $session_id = sanitize_text_field( $body['data']['session_id'] );
        gform_update_meta( $entry['id'], '_crisp_session_id', $session_id );
        
        // Add private entry note with direct link to Crisp conversation
        $note = sprintf( 'Crisp conversation created. Session ID: %s', $session_id );
        GFFormsModel::add_note( $entry['id'], 0, 'Crisp Add-on', $note );
    }
}, 10, 2 );

7. Frequently Asked Questions