Google Sheets

Overview

Google Sheets Integration allows you to automatically create or update leads in Kraya when rows are added or updated in a Google Sheet. You authorize specific sheet URLs, get a secure Webhook URL, and install a lightweight Google Sheets add-on to send data to Kraya.

In the add-on, you also map each sheet column to the right Kraya field (name, phone, email, stage, pipeline, or a custom attribute), including workbooks with more than one tab.

This integration is useful when you have data in Google Sheets (e.g., from forms, exports, or manual entry) and want to sync it automatically with Kraya without manual imports.

What you can do

Connect one or more Google Sheets to automatically sync lead data
Automatically create new leads or update existing leads based on phone number matching
Set pipeline and stage for leads by matching names (optional)
Sync custom attributes that match your organization's default attributes
Configure default country code for phone number normalization
Paste and save your Webhook URL in the add-on, run Test/Ping, and Save Mapping so Kraya reads columns the way you intend
Map columns to Kraya fields (including Other with the exact custom attribute name) and see Sample values when data exists under the header row
Test the connection before syncing data

How it works (user-facing)

Setup in Kraya Dashboard:
- Navigate to Integrations → Google Sheets Integration
- Add one or more Google Sheet URLs that are allowed to send data
- Set a Default Country Code (recommended) for phone number normalization
- Save to generate a unique Webhook URL (contains a slug and secret)
Install Google Sheets Add-on:
- In your Google Sheet, install the "Kraya AI SheetsSync" add-on from the Google Workspace Marketplace
- Open the add-on (Extensions → Kraya AI SheetsSync → Webhook)
- Paste your Webhook URL from Kraya and save
Map columns (recommended):
- Use Map the Google Sheet Headers in the add-on side panel
- Each row links one Sheet column to one Kraya field (or Other plus the exact custom attribute name in Kraya)
- Kraya treats row 1 on every tab as the header row; empty header cells are skipped
- In a single-tab workbook, the column list usually shows header names only (for example, Phone)
- In a multi-tab workbook, if the same header appears on more than one tab, the list shows which tab each option belongs to so you do not pick the wrong column; unique names may still show as the header alone
- Click Save Mapping after you change headers, rename tabs, or change how columns map to Kraya
- Saving the Webhook URL turns on the add-on behavior needed for Kraya to process sheet activity according to your setup
Test the connection:
- Use the "Test/Ping" feature in the add-on to validate your sheet structure
- The test checks that required columns (Phone) are present and that your mapping meets what Kraya expects for a successful check (it does not send a full lead row the same way a live row update does)
- If validation succeeds, you're ready to sync
Sync data:
- When rows are sent from the add-on, Kraya processes each row
- Phone numbers are normalized using your default country code
- Leads are matched by phone number (normalized)
- If a lead exists: It's updated with new data
- If no lead exists: A new lead is created
- Pipeline and stage are assigned if provided and valid
- Custom attributes are saved if they match your default attributes

Prerequisites & basics

Access to the Kraya Dashboard (admin permissions required for configuration)
A Google account with access to the Google Sheets you want to connect
The "Kraya AI SheetsSync" add-on installed in your Google Sheet
Understanding of your organization's pipeline names, stage names, and custom attributes (must match exactly)

Step-by-step guide

Configure in Kraya Dashboard
- Navigate to https://kraya-ai.com/dashboard/google-sheets (or Integrations → Google Sheets Integration)
- Click "Add URL" to add Google Sheet URLs (one at a time)
- Enter the full Google Sheet URL (format: https://docs.google.com/spreadsheets/d/{SHEET_ID}/...)
- Set Default Country Code (e.g., "91" for India, "1" for US) - this is used to normalize phone numbers that don't include a country code
- Click "Save" to generate or retrieve your Webhook URL
- Copy the Webhook URL (you'll need it for the add-on)
Install the Google Sheets Add-on
- Open your Google Sheet
- Go to Extensions → Add-ons → Get add-ons
- Search for "Kraya AI SheetsSync" and install it
- Grant necessary permissions when prompted
Configure the Add-on
- In your Google Sheet, go to Extensions → Kraya AI SheetsSync → Webhook
- Paste the Webhook URL you copied from Kraya Dashboard
- Click "Save" to store the webhook URL
Map columns and save mapping
- Follow Column mapping in the add-on below: map at least Phone (and other fields you need), then click Save Mapping
- Do this after you change header text, rename tabs, or add new columns you want Kraya to use
Test the connection
- In the add-on, click "Test/Ping" to validate your sheet
- The test checks that your sheet and mapping meet Kraya’s requirements (including Phone)
- If validation succeeds, you'll see a success message
- If validation fails, check that Phone is mapped and present, the Sheet URL is allowed in Kraya, and your Webhook URL is correct
Start syncing
- Use the add-on to send rows from your sheet to Kraya
- Each row is processed individually
- Leads are created or updated based on phone number matching

Column mapping in the add-on (Map the Google Sheet Headers)

Use this after the sheet URL is allowed in the Kraya Dashboard and you have saved the Webhook URL in the add-on (step 3 above). If you have not pasted the URL yet, do that first in Set Your Webhook URL, then click Save.

Open the panel

Open an allowed Google Sheet.
Open the Kraya add-on side panel (for example, Extensions → Kraya AI SheetsSync → Webhook, or the Kraya menu entry your workspace shows).
Confirm you see Set Your Webhook URL, Test, Save, and Map the Google Sheet Headers.

Add mapping rows

Under Map the Google Sheet Headers, click Add Row if you need more than one mapping.
Under Sheet column, choose the column from your sheet. On multi-tab files, pick the line that matches the correct tab when several tabs share similar header text.
Under Kraya field, choose Name, Phone, Email, Stage, Pipeline, or Other.
If you chose Other, type the exact custom attribute name as it appears in Kraya (a short hint is shown in the panel).
Optionally check Sample to confirm you selected the intended column when there is data below the header.
Repeat for each column you need mapped.

Save mapping

When every row has both a sheet column and a Kraya field (and the custom name filled for Other where needed), click Save Mapping.
Wait for the success message. If a validation message appears, fix incomplete rows and save again.

Notes

Mapping rows are independent; remove a row with the trash control if you no longer need that mapping.
Default country code is set in the Kraya Dashboard, not inside the add-on; it still affects how phone numbers are normalized when rows are processed.

Webhook URL and authentication

Webhook URL format: https://kraya-ai.com/api/google-sheets/{webhook_slug}/{webhook_secret}
- webhook_slug: 12-character random string (unique per organization)
- webhook_secret: 12-character random string (used for authentication)
Generation: Webhook URL is generated automatically when you first save the Google Sheets configuration
Regeneration: The slug and secret remain the same unless you delete and recreate the configuration (contact support if you need to rotate)
Security:
- Webhook secret is encrypted at rest using KMS
- Both slug and secret are required for authentication
- Only authorized sheet URLs can send data (validated on each request)
Rate limiting:
- Webhook endpoint: 100 requests per minute
- Ping/test endpoint: 10 requests per minute
- If you hit rate limits, wait briefly and retry

Sending data from your sheet

Required columns:

Phone (case-insensitive): Must be present and contain a valid phone number
- Include country code or ensure Default Country Code is set in Kraya
- Phone numbers are normalized automatically (non-digit characters are removed)
- Example formats accepted: 91-9876543210, (91) 9876 543 210, 919876543210, 9876543210 (if default country code is "91")

Optional columns:

Name: Lead's name
Email: Lead's email address (must be valid email format if provided; invalid emails are silently skipped)
Pipeline: Pipeline name to assign (case-insensitive match, must exist in your organization)
Stage: Stage name to assign (case-insensitive match, must belong to the specified pipeline)
Custom attributes: Any additional columns that match your organization's default attributes (case-insensitive matching)

Row handling:

New leads: If a lead with the given phone number doesn't exist, a new lead is created
- If pipeline/stage are provided and valid, the lead is assigned to them
- If pipeline/stage are not provided or don't match, the lead is added to your default "Leads" pipeline's "New Lead" stage
- Pipeline/stage matching logic:
  - Both provided: Both must match exactly; if either doesn't match, defaults are used
  - Only pipeline provided: Pipeline must match; stage defaults to "New Lead" in that pipeline
  - Only stage provided: Stage must exist in default pipeline; otherwise defaults are used
  - Neither provided: Defaults to "Leads" pipeline, "New Lead" stage
Existing leads: If a lead with the given phone number exists, it's updated
- Name, email, and custom attributes are updated
- Pipeline/stage updates follow specific rules:
  - Both provided: Both must match exactly; if either doesn't match, no pipeline/stage update occurs
  - Only pipeline provided: Pipeline must match AND current stage name must exist in the new pipeline; otherwise no update
  - Only stage provided: Stage must exist in the lead's current pipeline; otherwise no update
  - Neither provided: No pipeline/stage update (lead stays in current pipeline/stage)
- Special handling: For specific organizations, if neither pipeline nor stage is provided, existing leads are moved back to "Leads" pipeline and "New Lead" stage

Phone number normalization

Process: Phone numbers are normalized using your Default Country Code if no country code is present
- Non-digit characters are removed first (e.g., spaces, dashes, parentheses)
- If the resulting number doesn't have a country code, the default country code is prepended
- Example: If default country code is "91" and phone is "9876543210", it becomes "919876543210"
Matching: Leads are matched by normalized phone number
- This prevents duplicates from different phone formats
- Both normalized and non-normalized formats are checked to find existing leads
Validation: Invalid phone numbers (empty after normalization) return an error

Custom attributes handling

Matching: Custom attributes are matched case-insensitively against your organization's default attributes
- Column names in your sheet are compared (case-insensitive) to attribute names in Kraya
- Only attributes that exist in your default attributes are saved
- Attributes not in default attributes are silently ignored (no error)
Updating: Custom attributes are merged with existing lead attributes
- New values override existing values
- Attributes not provided in the sheet remain unchanged
Limitations: You cannot create new custom attributes via Google Sheets integration; they must exist in your organization's default attributes first

Limits & behavior

Available on all plans: No plan restrictions for this integration
Rate limiting:
- Webhook endpoint: 100 requests per minute
- Ping/test endpoint: 10 requests per minute
- If you hit limits, wait briefly and retry
Sheet URL authorization:
- Only sheet URLs added in Kraya Dashboard can send data
- Sheet ID is extracted from the URL and validated on each request
- Multiple sheet URLs can be authorized per organization
Phone number matching:
- Leads are matched by normalized phone number
- Phone numbers are normalized using default country code if no country code present
- Invalid phone numbers return an error
Pipeline/Stage matching:
- Names must match by value but matching is case-insensitive (e.g., "sales" matches "Sales")
- Stage must belong to the specified pipeline
- For new leads: Partial matches use defaults
- For existing leads: Partial matches skip pipeline/stage updates (other fields still update)
Email validation:
- Email is validated silently (invalid emails are skipped, webhook still succeeds)
- Invalid emails are logged but don't cause the webhook to fail
Custom attributes:
- Only attributes in your default attributes are accepted
- Matching is case-insensitive
- Attributes not in default attributes are silently ignored

Common edge cases and how to handle them

Invalid or missing Phone column
- Validation fails during ping/test
- Fix the column header to "Phone" (case-insensitive) and retry
- Ensure the Phone column contains valid phone numbers
Sheet not allowed
- Sending from a non-authorized Sheet URL is rejected with "Sheet not allowed" error
- Add the Sheet URL in Kraya Dashboard under "Allowed URLs" and save again
- Verify the Sheet URL format is correct (must start with https://docs.google.com/spreadsheets/d/)
Pipeline/Stage not found or not updating
- For new leads: Lead is created but may not move to the specified pipeline/stage if names don't match
- For existing leads: Pipeline/stage update is skipped if names don't match (other fields still update)
- Verify spelling and that the stage belongs to the specified pipeline
- Check that pipeline and stage names match a real name in your org (matching is case-insensitive, but the name must otherwise exist)
- For existing leads: Ensure stage exists in the lead's current pipeline if only stage is provided
Duplicate URLs
- Avoid adding the same Sheet URL multiple times
- Each Sheet ID is stored once in the allowed sheets list
Webhook URL leaked/rotated
- If webhook URL is compromised, contact support to regenerate
- The slug and secret remain the same unless configuration is recreated
- Update the add-on with the new webhook URL if regenerated
Phone number normalization issues
- If phone numbers aren't normalizing correctly, check your default country code setting
- Phone numbers with country codes are normalized correctly
- Phone numbers without country codes use the default country code
- Invalid phone numbers (empty after normalization) return an error
Custom attributes not saving
- Only attributes that exist in your organization's default attributes are accepted
- Check your default attributes in the Dashboard to see which attributes are available
- Attributes not in default attributes are silently ignored (no error)
- Matching is case-insensitive, but attribute names must exist in your default attributes
Email not updating
- Invalid email formats are silently skipped (webhook still succeeds)
- Check that email is in valid format (e.g., user@example.com)
- Invalid emails are logged but don't cause the webhook to fail
Existing lead not updating
- Verify the phone number matches exactly (after normalization)
- Check that you're using the correct organization's webhook URL
- Ensure the lead exists in the same organization
- Pipeline/stage updates may be skipped if names don't match (other fields still update)
Renamed tab or header (column mapping)
- Old mappings may no longer match the column list
- Open the add-on, open the Sheet column dropdown again to refresh choices, update mappings, then click Save Mapping
Same header text on two tabs
- The column list shows which tab each option belongs to so you pick the correct tab
- Always choose the line that matches the tab you intend
Empty first row on a tab
- That tab may not show headers until row 1 has names
- Put header text in row 1, reopen the panel if needed, then Save Mapping again

Troubleshooting

Ping/test fails

Check the Webhook URL: copied correctly (no extra spaces or characters)?
Confirm required columns: the sheet must have a "Phone" column (case-insensitive match)
Confirm Phone is mapped in Map the Google Sheet Headers and you clicked Save Mapping
Verify the Sheet URL is added under "Allowed URLs" in Kraya Dashboard and saved
Check rate limiting: wait briefly if you've hit the 10 requests/minute limit for ping
Verify webhook URL format: should be https://kraya-ai.com/api/google-sheets/{slug}/{secret}

Save Mapping does nothing or shows validation

Cause: A row is missing the sheet column or Kraya field, or Other is missing the custom attribute name
Fix: Complete every row, then click Save Mapping again. Reload the sheet if the panel seems stuck

Sample always shows “--” in the add-on

Cause: No data under that column yet, or the header was renamed after you selected it
Fix: Add a sample data row under the header, or re-select the column after fixing headers

Test passes but lead data looks wrong

Cause: A column is mapped to the wrong tab or field, or a custom attribute name for Other does not match Kraya
Fix: Review each mapping row, fix Other names to match Kraya exactly, click Save Mapping, then try again with a test row

Leads don't appear

Phone numbers must include a country code or have Default Country Code set in Kraya
Verify phone number format is valid (non-digit characters are removed, but number must be valid)
Check if an existing lead with the same phone was updated instead of created (search by phone in Dashboard)
Verify the webhook request succeeded (check add-on logs or Kraya logs)
Try with a minimal row (just Phone and Name) to isolate the issue

Pipeline/stage not updating

For new leads: Ensure both Pipeline and Stage are provided and match a real name in your org (matching is case-insensitive; the stage must belong to the pipeline)
For existing leads: Pipeline/stage updates require both names to match; partial matches skip the update
Confirm the Stage belongs to the specified Pipeline
Check that pipeline and stage names exist in your organization
For existing leads with only stage provided: Ensure the stage exists in the lead's current pipeline

Custom attributes not saving

Verify attribute names match your default attributes exactly (case-insensitive)
Check your default attributes in the Dashboard to see which attributes are available
Attributes not in default attributes are silently ignored (no error)
Ensure attribute values are provided in the sheet data

Rate limiting errors

Webhook endpoint: 100 requests per minute
Ping/test endpoint: 10 requests per minute
Wait briefly and retry if you hit limits
Consider batching requests or reducing frequency

Webhook authentication fails

Verify the webhook URL is correct (slug and secret must match)
Check that the webhook URL hasn't changed (slug and secret remain the same unless recreated)
Ensure no extra spaces or characters in the webhook URL
Contact support if you need to regenerate the webhook URL

Short decision tree

Ping failing → verify Webhook URL → map Phone and click Save Mapping → confirm Phone column exists in the sheet → ensure Sheet URL is allowed → check rate limits → retry
Lead missing → check phone formatting/country code → search by phone to see if it was updated → try with a minimal row → verify webhook succeeded
Pipeline/stage not applied → verify names and relationship → check if lead is new or existing (different rules apply) → remove then re-add the correct values
Custom attributes not saving → verify attribute names match default attributes → check default attributes in Dashboard → ensure values are provided in sheet

FAQs

Can I add multiple sheets?
- Yes. Add each Sheet URL under "Allowed URLs" in Kraya Dashboard. Each sheet can use the same webhook URL.
Do I need to include the country code in phone numbers?
- Recommended. If not, set Default Country Code in Kraya. Phone numbers without country codes will use the default country code for normalization.
Will rows update existing leads?
- Yes, if the phone number (normalized) matches an existing lead. The lead is updated with new data. Pipeline/stage updates follow specific rules (see "Sending data from your sheet" section).
Are there plan restrictions?
- No specific plan restrictions for this integration. Available on all plans.
How does pipeline/stage assignment work for new vs existing leads?
- New leads: Partial matches use defaults (e.g., if pipeline matches but stage doesn't, uses pipeline's "New Lead" stage)
- Existing leads: Partial matches skip pipeline/stage updates (e.g., if pipeline matches but stage doesn't, no update occurs; other fields still update)
What happens if I provide only pipeline or only stage?
- New leads:
  - Only pipeline: Uses that pipeline's "New Lead" stage
  - Only stage: Uses that stage if it exists in default pipeline; otherwise uses defaults
- Existing leads:
  - Only pipeline: Updates only if current stage name exists in the new pipeline
  - Only stage: Updates only if stage exists in lead's current pipeline
Can I create new custom attributes via Google Sheets?
- No. Custom attributes must be created in the Dashboard first. The integration can only set values for attributes that already exist in your default attributes.
What happens if email is invalid?
- Invalid emails are silently skipped (webhook still succeeds). The email field is not updated, but other fields are processed normally. Invalid emails are logged for debugging.
How are phone numbers normalized?
- Non-digit characters are removed first
- If no country code is present, the default country code is prepended
- Example: "9876543210" with default "91" becomes "919876543210"
Do I need to click Save Mapping after every cell edit?
- No. Save mapping when you change which column maps to which Kraya field, rename tabs or headers, or add new columns you want Kraya to use. Normal data entry in existing columns does not require a new save unless mapping changed.
Can I map two sheet columns to the same Kraya field?
- Avoid duplicate mappings for the same Kraya field unless you understand how values override each other. Prefer one column per Kraya field.
Can I use the same webhook URL for multiple sheets?
- Yes. The same webhook URL can be used for all authorized sheets. Each sheet is validated separately based on its URL.
What's the rate limit?
- Webhook endpoint: 100 requests per minute
- Ping/test endpoint: 10 requests per minute
- If you hit limits, wait briefly and retry
How do I regenerate the webhook URL?
- The webhook URL (slug and secret) remains the same unless the configuration is recreated. Contact support if you need to rotate the webhook URL for security reasons.
What happens if a sheet URL is removed from allowed URLs?
- The sheet can no longer send data to Kraya. Requests from that sheet will be rejected with "Sheet not allowed" error. Re-add the URL to restore access.

Tips and best practices

Dedicated sync sheet: Keep a dedicated "export"/"sync" sheet that the add-on submits to Kraya, rather than syncing your main working sheet
Clear column names: Use clear, consistent column names (Phone, Name, Email, Pipeline, Stage) to avoid mapping issues
Test first: Test with a single row before bulk updates to ensure everything works correctly
Consistent naming: Keep pipeline/stage names matching those in Kraya to avoid mismatches (matching is case-insensitive, but the name must otherwise be correct and the stage must belong to the pipeline)
Default country code: Set Default Country Code in Kraya if your phone numbers don't include country codes
Custom attributes: Ensure custom attribute column names match your default attributes (case-insensitive)
Phone format: Use consistent phone number format (with or without country code) across your sheet
Error handling: Monitor webhook responses and handle errors appropriately in your workflow
Rate limiting: Be aware of rate limits (100 requests/minute) when sending large batches
Row 1 headers: Keep row 1 as a clear header row on every tab you sync from; save mapping again after structural changes
Test after changes: Run Test/Ping after you change the Webhook URL or mapping

Lead Import (CSV/Sheet) - Manual import from CSV/Excel files
Connect Kraya API - Programmatic lead creation/updates via HTTP API
Pipelines and Stages - Managing your lead organization structure
Dashboard - Viewing and managing imported leads
Integrations overview - Other available integrations