Monday CRM

The Monday CRM Integration establishes an end-to-end, bi-directional, and real-time bridge between Supsis (where customer communication takes place) and Monday.com (where flexible business workflows, leads, and sales pipelines are managed). With this integration, incoming contacts from WhatsApp, WebChat, and other communication channels can be automatically created in Monday as a Contact, Lead, or Contact + Deal based on your selected forward mode.

The integration does not assume a fixed, rigid CRM schema for Monday. Since Contacts, Leads, and Deals in Monday are standard boards whose IDs and column configurations vary from account to account, an adaptable Board Mapping step is performed during setup. Support agents can view customer Monday records and update histories right from the live chat sidebar, adding new notes instantly without leaving the conversation. Furthermore, Monday events such as item creation, column/status changes, and deletions trigger Supsis automations to power instant customer notifications and tasks.

1- Overview of Monday CRM Integration

1.a – What is Monday CRM and What Does the Integration Solve?

Monday.com is a versatile work operating system that allows teams to build customized workflows, track sales pipelines, and manage customer relationships on visual boards.

In traditional workflows, sales and support teams converse with customers across messaging channels (WhatsApp, live chat, social media) and then manually copy contact details into Monday boards. This leads to wasted time, data entry errors, and missed opportunities. The Supsis Monday CRM Integration bridges this gap seamlessly.

The integration addresses three primary requirements:

1. Automatic Sync from Supsis to Monday: When a new customer reaches out via Supsis, an automated phone-based deduplication check is performed; if no match exists, a Contact, Lead, or Contact + Deal item is created in Monday.
2. In-Chat Live CRM View: Agents inspect customer Contact, Lead, or Deal records along with updates and notes history directly inside the chat panel, and can post new notes directly to Monday.
3. Event Streaming from Monday to Supsis Automations: Monday events such as item creation, status changes, item deletions, or new updates trigger Supsis automations in real time.

1.b – Two-Tier Architecture

The integration is built on a two-tier architecture. Understanding this distinction is essential during setup:

1.c – Monday CRM & Supsis Glossary

Key concepts used throughout the integration UI and documentation:

2- Setup and Connecting with API Token

2.a – Prerequisites and Required Information

Before setting up the Monday CRM integration, make sure you have prepared:

1. Monday CRM Boards: Prepare boards for Contacts, Leads, and Deals in your Monday account.
   • Contact and Lead boards must have a column of type Phone.
   • Optional Email and People columns should be created.
   • If Contact + Deal mode is used, the Deal board must have a column of type Connect Boards / Board Relation pointing to the Contacts board.
2. Personal API Token: The personal API access token generated from your Monday user account.

2.b – Steps to Obtain a Monday API Token

Monday connects via personal API tokens rather than standard OAuth flows. The token authorizes Supsis to manage boards, columns, items, and webhooks:

1. Log into your Monday.com account.
2. Click on your profile avatar and navigate to Developers (or visit Monday Developers).
3. If you are an account admin: Navigate to Administration > Connections > Personal API token.
4. In the Developer section, open Developer > API Token and copy your personal token.

2.c – Adding a Monday CRM Channel in Supsis

Once the token is copied, create the channel in Supsis:

1. In the Supsis management panel, go to Integrations > CRM from the left navigation.
2. Locate the Monday CRM card and click Add Channel.
3. In the modal dialog:
   • Channel Name: Optional; defaults to "Monday" if left blank.
   • API Token: Paste your personal Monday API token.
4. Click Connect to establish the integration.

2.d – Verification and Security

Upon creation, Supsis queries the Monday API to validate user and account details:

• Success: The channel is activated, showing a green "Setup OK" badge.
• Invalid Token: If authentication fails, creation is blocked and Monday's error message is displayed. If permissions lapse later, a yellow "Reconnection Required" badge appears.
• Security: Tokens are encrypted in storage, never logged in plaintext, and masked in the UI.

3- Channel Detail Tabs

The Monday channel settings are divided into 5 configuration tabs:

3.a – Detail Tab

Displays connection status and general details:

• Channel Name: Editable display name.
• Connected Account: The Monday organization/account name (read-only).
• Connected User: Name and email of the token owner.
• API Token: Masked field. If updating the token, enter the new key and click Update.

3.b – Board Mapping Tab

Because Contacts, Leads, and Deals are customized boards in Monday, this screen maps your boards and columns to their CRM meanings in Supsis. Selecting a board dynamically loads its available groups and columns from Monday.

Mapping fields:

1. Contacts Board:
   • Contacts Board: The board used for customer contacts.
   • Group (Optional): Target group for newly created items.
   • Phone Column (Required): Column of type Phone (used for deduplication).
   • Email Column: Column of type Email.
   • Owner Column: Column of type People.
2. Lead Board:
   • Lead Board: The board used for inbound leads.
   • Group (Optional): Target group for new leads.
   • Phone Column (Required): Column of type Phone.
3. Deal Board:
   • Deal Board: The board used for sales deals.
   • Group (Optional): Target group for new deals.
   • Contact Relation Column: Column of type Connect Boards / Board Relation. Links the deal item directly to the contact item.

3.c – User Mapping Tab

Compares Supsis agents with Monday users based on their email addresses (case-insensitive matching):

• Matching rows display the Monday user's name, email, and mapping type ("Email").
• Unmatched rows display "-" in the Monday column.
• Read-Only Verification Table: This tab is informational; it verifies whether support agents have corresponding Monday accounts for ownership assignments.

3.d – Webhooks Tab

Allows Supsis to receive real-time updates when records change in Monday. Webhooks are registered directly from Supsis without manual URL copying.

Available Monday event types:

1. create_item: New item created
2. change_column_value: Any column value updated
3. change_status_column_value: Status column changed
4. change_specific_column_value: A designated column changed
5. change_name: Item title changed
6. item_deleted: Item deleted
7. create_update: New update or comment posted

3.e – Visibility Tab

Controls which departments and support agents have access to view and manage this Monday CRM channel.

4- CRM Forwarding from Source Channels

After completing channel setup and Board Mapping, configure how incoming contacts from channels like WhatsApp or WebChat are forwarded to Monday:

1. Navigate to the source channel settings (e.g., Settings > Channels > WhatsApp).
2. Open the CRM Forward section and select the Monday tab.
3. Toggle on Forward new contacts to Monday.

4.a – Export Modes

Choose the creation mode that fits your pipeline:

• Contact: Creates a new item in the mapped Contacts board.
• Lead: Creates a new item in the mapped Lead board.
• Contact + Deal: First creates a contact item in the Contacts board, then creates a deal item in the Deal board and links the deal to the contact if a relation column is mapped.

4.b – Phone Format Selection

Ensure compatibility with how phone numbers are formatted in your Monday boards:

4.c – Default Owner

Select an assigned Monday user from the dropdown. If an owner column of type People is configured in Board Mapping, newly created items will be assigned to this user.

4.d – Field Mapping

Map additional Supsis contact attributes to Monday columns:

• Status, Color, and Dropdown columns allow selecting from predefined labels in Monday.
• Text and informational columns support static text or dynamic Supsis variables (e.g., {{contact.phone}}, {{contact.name}}).
• Click Update to save your forward configuration.

4.e – Deduplication (Dedup) Logic

To prevent duplicate records, Supsis checks existing records before creating an item:

5- In-Chat Monday Live CRM Widget

When a Monday channel is active, a dedicated Monday Information tab is added to the customer info sidebar in the live chat screen:

5.a – Inspecting Records

Agents view linked Monday records without leaving the conversation:

• Contacts: Looked up first by registered Monday item ID, then by phone number in the Contacts board.
• Leads: Looked up first by lead item ID, then by phone number in the Lead board.
• Deals: Looked up by registered deal item ID (deals are not queried by phone directly).

5.b – Item Detail Modal and Posting Notes (Updates)

Clicking a record name opens the detail modal:

• Displays all Monday column values, statuses, and assignees.
• Updates Timeline: Shows previous comments, author, and timestamp.
• Add Note: Agents can type a note directly into the input area and submit it to Monday's item timeline in real time.

6- Monday Webhooks and Automation Triggers

6.a – Webhook Configuration

Set up webhooks from the Webhooks tab inside your Monday channel:

1. Select a mapped Contact, Lead, or Deal board.
2. Select the event type to listen to (create_item, change_status_column_value, etc.).
3. Click Create Webhook.
4. Supsis automatically responds to Monday's challenge verification request to finalize registration.

6.b – 10 Monday Automation Triggers

Supsis Automation Designer includes 10 event triggers for Monday:

7- Automation Action Blocks

Four ready-to-use action blocks are available in the Automation Designer under the Monday Actions group:

7.a – Action Block Specifications

Each block provides Success and Failure output paths. For example, if a phone number in Find Item By Phone is shorter than 8 digits, execution follows the failure branch.

8- Advanced JavaScript SDK Usage

For developers writing scripts in Automation or Chatbot code blocks, the supsis.monday namespace provides direct API helper methods:

// Example: Search contact by phone and log an update
const phone = context.contact.phone;
const contact = await supsis.monday.findContactByPhone(phone);

if (contact) {
    // Add update to existing item
    await supsis.monday.createUpdate(contact.id, "Customer returned via automated chatbot.");
} else {
    // Create new lead item
    await supsis.monday.createItem("123456789", "group_leads", context.contact.name, {
        phone: { phone: phone, countryShortName: "US" }
    });
}

8.a – SDK Method Reference

9- Where to Find in Panel

Navigation paths and direct URLs for all Monday CRM features:

10- Usage Steps and Scenarios

10.a – Step-by-Step Setup Flow

1. Prepare Boards: Set up Contact, Lead, and Deal boards in Monday with Phone, Email, and Connect Boards columns.
2. Obtain API Token: Copy your personal token from your Monday profile or Administration area.
3. Create Channel: Open Integrations > CRM > Monday CRM in Supsis, click Add Channel, and paste the token.
4. Map Boards: Configure your Contacts, Lead, and Deal boards along with their phone and relation columns.
5. Inspect User Mapping: Verify email alignment between Supsis agents and Monday users.
6. Set Up Webhooks: Subscribe to relevant Monday events for automated event routing.
7. Configure Source Channel: Open your WhatsApp or WebChat settings, enable CRM Forward under the Monday tab, and set field mappings.
8. Test Flow: Send a message from a new phone number to verify item creation in Monday and live chat widget synchronization.

10.b – Practical Scenarios

• Automated WhatsApp Lead Capture: Incoming leads from WhatsApp are placed directly into the Monday Lead board, complete with campaign tags and source tracking.
• Simultaneous Contact + Opportunity Creation: An inbound inquiry creates both a contact and an opportunity deal, connected via board relations.
• Deduplication: Repeat customer inquiries bring up existing Monday records in the chat sidebar rather than creating duplicate items.
• Agent Ownership Assignment: Channel defaults assign newly created leads to specific Monday team members automatically.
• In-Chat Deal Updates: Agents record quote and meeting notes directly to Monday items during live conversations.
• Deal Stage Triggered WhatsApp Message: A status change to "Contract Sent" in Monday triggers an automated WhatsApp message with delivery details.

10.c – Business Value

• Eliminates Manual Data Entry: Real-time data transfer removes tedious copy-paste tasks between applications.
• Accelerated Response Times: Instant lead forwarding ensures sales reps connect with prospects when intent is highest.
• Native Alignment: Respects custom Monday workspace setups without imposing rigid schemas.
• Informed Conversations: Live chat agents access full CRM context and timelines in one screen.

11- Troubleshooting and Critical Notes