Salesforce

Overview

The Salesforce integration keeps your leads in sync between Kraya and Salesforce in both directions. Your counselors keep working leads in Salesforce, while Kraya handles WhatsApp follow-ups, AI qualification and stage-based automations.

• Salesforce → Kraya: a Salesforce Flow sends a lead to Kraya whenever the fields it watches change. Kraya creates or updates the matching lead and moves it to the right pipeline and stage.
• Kraya → Salesforce: when a linked lead's stage, pipeline, notes, name, email, phone or a mapped attribute changes in Kraya, Kraya updates the Salesforce lead about 30 seconds later. New Kraya leads are created in Salesforce automatically.

The connection is organization-wide: one Salesforce org links to your whole Kraya organization. An administrator connects it from the Integrations Hub, and your Salesforce admin does a one-time setup on the Salesforce side.

What you can do

• Connect Salesforce with an External Client App (Consumer Key and Consumer Secret)
• Receive new and updated Salesforce leads in Kraya within seconds of a change
• Keep Kraya Stage, Kraya Pipeline and Kraya Notes in Salesforce up to date with each lead's Kraya stage, pipeline and notes
• Send name, email and mobile changes made in Kraya to Salesforce
• Create a Salesforce lead for every new Kraya lead, or link it to a Salesforce lead that already has the same phone
• Sync custom attributes both ways once Kraya support maps them
• Update your credentials, pipeline or default country code, and disconnect at any time

How it works

Two modes

Every organization uses standard mode unless you ask Kraya to switch you to Sub-Status mode. The settings page shows the sample request for your mode.

An old value never undoes a Kraya change (standard mode). Your Flow sends all the watched fields whenever any of them changes. Say a lead moves to a new stage in Kraya and, before Kraya's update reaches Salesforce, a counselor edits the lead's phone. The Flow then sends the old Kraya Stage. Kraya recognises that the value is unchanged since the last sync and ignores it. Only a value that was actually changed in Salesforce is applied.

Salesforce → Kraya: how incoming leads are handled

Every valid request is saved and processed in the background, usually within a few seconds.

• Matching: Kraya looks for the lead by its Salesforce Lead Id first, then by phone. Phones without a country code get your Default country code. If a lead matched by Id has a new phone in Salesforce, Kraya takes the new phone, unless another Kraya lead already has that number.
• No match: Kraya creates a new lead with source Salesforce.
• Stage: Kraya compares the stage value with stage names in the pipeline, ignoring upper/lower case and surrounding spaces. Default view stages, hidden stages and the Deleted stage never match.
  • An existing lead in the same pipeline keeps its stage when nothing matches.
  • A new lead, or a lead moving in from another pipeline, goes to the pipeline's first stage when nothing matches.
  • Sending the stage a lead is already in changes nothing, so automations don't run twice.
• Name: updated from Salesforce, except when it is "Not provided" or just the phone number (those are Kraya's own placeholders for a lead with no name).
• Email: saved when one is sent. A blank email never clears the one in Kraya.
• Attributes: saved through your attribute mapping (or by matching the Kraya attribute key, ignoring case). Values that are empty or don't fit the attribute's type are skipped.
• Long notes: Kraya can hold about 65,000 bytes of notes. Longer Kraya Notes are trimmed to fit instead of being rejected.
• Moving to a stage from Salesforce runs your Smart Triggers and "stays in stage" rules as usual.

Kraya → Salesforce: updates to linked leads

About 30 seconds after a change, Kraya updates the Salesforce lead. Several quick changes go out as one update.

• Always sent: Kraya Stage, Kraya Pipeline and Kraya Notes.
• Sent only when they changed in Kraya: First Name / Last Name, Email and Mobile. This way a stage change never overwrites a counselor's newer name edit. Kraya doesn't send a name that is empty or just the phone number, or an email that isn't valid. Changes that came from Salesforce are not sent back.
• Mapped attributes: sent when they change.
• Never changed: Status and Owner. Kraya never runs Salesforce assignment rules on updates, so a lead's owner never changes because of Kraya.
• Sub-Status: never written in Sub-Status mode. In standard mode, Kraya writes it only if Kraya support maps an attribute to it.
• Updates pause while the connection shows Error, and resume once it is Connected again.

Kraya → Salesforce: new leads

About 30 seconds after a new lead is added in Kraya (WhatsApp, lead forms, marketplaces, imports, the API and so on):

1. Kraya searches Salesforce for an unconverted lead with the same phone in Phone or Mobile, in common formats (with or without +, country code or a leading 0), including numbers stored with spaces or dashes.
2. Found: Kraya links the Kraya lead to that Salesforce lead and fills in its Kraya fields. No duplicate is created.
3. Not found: Kraya creates a Salesforce lead with:
   • First / Last Name from the Kraya name. A lead with no name (or whose name is just its phone) is filed under its phone number as Last Name, e.g. +919876543210, so counselors can still recognise it. "Not provided" is only used when there is no phone at all
   • Company "Not provided"
   • Mobile, and Email if valid
   • Lead Source "Other", only if "Other" is in your Lead Source picklist
   • Kraya Stage, Kraya Pipeline, Kraya Notes and mapped attributes that have a value
4. Salesforce assignment rules run on create, so the new lead goes to the right counselor or queue. Status is never sent, so Salesforce applies its default.
5. If a Salesforce duplicate rule blocks the create and points to an existing lead, Kraya links to that lead.

Kraya does not create Salesforce leads for:

• Leads without a phone
• Leads imported from Zoho, teleCRM, Neodove or GoHighLevel
• Leads that already existed before you connected (there is no backfill)

Attribute mapping (set up by Kraya support)

Kraya support can pair a Kraya custom attribute with a Salesforce Lead field (one attribute → one field). There is no dashboard screen for this. Send support the attribute names and the Salesforce field API names (for example Course__c). Mapped values sync both ways.

These fields can never be mapped: Lead Status, Owner, First/Last Name, Company, Email, Phone, Mobile, Kraya Stage, Kraya Pipeline, Kraya Notes. Sub-Status can't be mapped in Sub-Status mode.

Kraya skips a mapped value that doesn't fit the field (wrong type, not in a restricted picklist, too long) and still sends the rest of the update.

Prerequisites & basics

• You must be an administrator in Kraya. Salesforce is a paid-plan feature. On the free plan, the page shows an upgrade prompt.
• A Salesforce org with API access and a My Domain URL (Setup → My Domain), for example https://yourcompany.my.salesforce.com. Sandbox and Developer Edition URLs work too.
• A Salesforce admin to complete the setup below.

Step-by-step guide

1. Salesforce: create the three Kraya fields

In Setup → Object Manager → Lead → Fields & Relationships, create:

Kraya Notes must be exactly this type and size, or setup fails.

2. Salesforce: create or choose the integration user

This is the account Kraya signs in as. Everything Kraya writes to Salesforce is recorded against it.

Use a dedicated account, never a person's. Both Flows in step 7 ignore changes made by the integration user, so Kraya's own writes don't bounce back. That exclusion applies to whoever the account is — so if you point it at a counselor's login, every lead that counselor creates or edits by hand stops reaching Kraya, silently. Name it something obviously non-human, such as Kraya Integration.

First check which licence you have. Go to Setup → Company Information → User Licenses and look for a Salesforce Integration row with Remaining of 1 or more.

The Salesforce Integration licence comes with Enterprise, Unlimited and Performance orgs. Trials and lower editions often don't have it. If it isn't listed, it will not appear in the User License dropdown at all, however long you look.

Option A — Salesforce Integration licence

1. Setup → Users → New User.
2. Set User License to Salesforce Integration before choosing a profile. The Profile list is filtered by the licence, and changing the licence resets whatever profile you picked.
3. Set Profile to Minimum Access - API Only Integrations.
4. Use an email inbox you control — Salesforce sends an activation link there.
5. Save and activate. API Enabled comes with this profile.

Option B — no Integration licence available

1. Setup → Users → New User, User License Salesforce, Profile Minimum Access - Salesforce.
2. This profile has no API access, so Kraya cannot sign in with it on its own. The Kraya permission set in step 3 must grant the API Enabled system permission.
3. Save and activate.

This option uses a full Salesforce licence, and the account must still be one nobody works leads with.

3. Salesforce: create the Kraya permission set and assign it to the integration user

Create the set

1. Setup → Permission Sets → New.
2. Label: Kraya Integration. The API Name fills itself in.
3. Leave License as --None--. Choosing one here limits the set to users on that licence and can stop you assigning it to the integration user.
4. Save. You land on the permission set's own page — everything below is on that page.

Grant the access

Object Settings sits inside the permission set, not in the Setup menu. On the permission set page, under the Apps heading, click Object Settings, then Leads, then Edit.

Object permissions and field permissions are both on that one screen:

• Object Permissions (near the top): Read, Create, Edit.
• Field Permissions (scroll down the same page):
  • Edit on Kraya Stage, Kraya Pipeline and Kraya Notes
  • Edit on Mobile, Read on Phone
  • Optional: Edit on Email and Lead Source (without them, Kraya creates leads without these values)
  • Edit on any field Kraya support will map

Save, then go back to the permission set page for the rest:

• Option B users only (integration user on a Minimum Access - Salesforce profile): open System Permissions and turn on API Enabled. Without it the setup check fails with "does not have API access".
• If your Lead sharing is Private: also View All and Modify All on Lead. Otherwise Kraya can't see or update leads owned by others.
• If you use converted leads: the View and Edit Converted Leads permission.

Assign it

On the permission set page, click Manage Assignments → Add Assignment, tick the integration user, and click Assign.

If your integration user's profile already grants Lead access (a System Administrator profile in a Developer org, for example), the connection works without this permission set. Create it anyway for any org where the integration user is on a restricted profile.

4. Salesforce: create the External Client App

1. Setup → External Client App Manager → New External Client App.
2. Enable OAuth and turn on Client Credentials Flow.
3. Set the Run As user to the integration user.
4. Copy the Consumer Key and Consumer Secret.
5. Wait about 10 minutes before connecting, because Salesforce changes take time to apply.

Enable Client Credentials Flow is the setting that matters. Without it, Kraya cannot sign in and the setup check fails with a credentials error.

5. Kraya: connect Salesforce

1. Open Integrations Hub → CRM & Data Sync → Salesforce.
2. Fill in:
   • My Domain URL (required): must start with https:// and end in .my.salesforce.com
   • Consumer Key and Consumer Secret (required)
   • Pipeline for Salesforce leads (required): where new leads land when no pipeline is named
   • Default country code (defaults to 91): used when a Salesforce phone has no country code
3. Click Connect Salesforce. The status shows Checking setup while Kraya signs in and checks the Lead fields and permissions. The page refreshes itself.
4. When the status turns Connected, the Endpoint for your Salesforce team card shows the Endpoint URL, the Header Token and a sample request. Share these with your Salesforce admin for the next steps.

Treat the Endpoint URL and Header Token like a password. Anyone holding both can send leads into your Kraya account.

6. Salesforce: External Credential and Named Credential (for Salesforce → Kraya)

1. Setup → Named Credentials → External Credentials → New:
   • Authentication Protocol: Custom
   • Add a Principal with an Authentication Parameter named Token, value = the Kraya Header Token
   • Add a Custom Header: name X-Kraya-Webhook-Token, value {!$Credential.<ExternalCredentialName>.Token}
2. Named Credentials → New:
   • URL: the Kraya API host (the start of the Endpoint URL, before /api/webhooks/...)
   • External Credential: the one above
   • Allow Formulas in HTTP Header: on
   • Generate Authorization Header: off
3. Give External Credential Principal Access (in a permission set) to every user who edits leads. The Flow runs as the user who made the change.

7. Salesforce: the two record-triggered Flows

You need two Flows on Lead, and both must be Active:

Why two and not one. "Is Changed" is always false at the moment a record is created, so a Flow that relies on it never fires for a brand-new lead. A Flow set to run on "created and updated" cannot use Is Changed either. Splitting them is the only way to get both. A Flow can have many versions but only one version active at a time — that limit is per Flow, so two separate Flows can both be active together.

Both Flows are after save, and the callout goes on the asynchronous path so a slow response never blocks the user saving the record.

The Created Flow

• Start when: A record is created.
• Entry condition: Created By ID does not equal the integration user, so leads Kraya itself creates in Salesforce are not sent straight back.

The Updated Flow

• Start when: A record is updated.
• Conditions: use Custom Condition Logic with one Is Changed row per field, joined with OR, plus Last Modified By ID does not equal the integration user joined with AND.
• Standard mode fields: Kraya Stage, Kraya Pipeline, First Name, Last Name, Phone, Mobile, Email.
• Sub-Status mode fields: Sub-Status and Status.

The callout, in both Flows

• An HTTP Callout action: method POST, the Named Credential from step 6, and the path is the rest of the Endpoint URL (/api/webhooks/salesforce/<your code>).

Body

• Standard mode: salesforce_id, name, phone, email, kraya_stage, kraya_pipeline, notes, attributes.
• Sub-Status mode: salesforce_id, name, phone, email, status, sub_status, attributes.

Flow Builder tips

• Paste the sample request from Kraya as the HTTP Callout's sample JSON. In Flow Builder, keys with underscores show up as u5f. For example, salesforce_id appears as salesforceu5fid. That is expected.
• The Name field isn't available in record-triggered flows. Use a formula such as {!$Record.FirstName} & " " & {!$Record.LastName} for name.
• Use field API names as keys inside attributes (for example Course__c).
• The sample JSON lives in Setup → External Services → your service. Opening Edit there reopens the callout wizard; if you only want to look, press Cancel rather than saving, because saving can regenerate the action and unset the mappings in both Flows.

Updating settings

• Connected: change the pipeline or country code and click Save settings. Click Update credentials to enter a new Consumer Key/Secret (leave either blank to keep the current one). New credentials restart the setup check.
• Error: the error message appears at the top. Fix the problem in Salesforce, re-enter the Consumer Key and Secret, and click Save credentials to check again.

Disconnecting

Click Disconnect and confirm. Syncing stops, the Endpoint URL stops working, and the stored secrets are removed. Leads stay in Kraya.

Reconnecting creates a new Endpoint URL and token, so your Salesforce admin must update the Named Credential path and the External Credential token.

Connection status

• Checking setup: Kraya is checking your credentials, fields and permissions. It usually clears within a minute.
• Connected: syncing in both directions.
• Error: setup failed or Salesforce refused an update. The message says what to fix. While in Error, Salesforce → Kraya requests are still accepted, but Kraya → Salesforce updates pause.

Request reference (Salesforce → Kraya)

POST <Endpoint URL> with headers X-Kraya-Webhook-Token: <Header Token> and Content-Type: application/json.

Fields that don't apply to your mode are ignored.

Responses

Role-based behavior

• Admins: can connect, update, disconnect, and see the Endpoint URL and token.
• Members: don't see the Integrations Hub.

Limits and quotas

• One Salesforce connection per Kraya organization.
• Paid plans only.
• Kraya → Salesforce updates arrive about 30 seconds after a change.
• No backfill: leads that existed before connecting are only linked once Salesforce sends them.

Troubleshooting

Setup errors (shown on the settings page)

After fixing the cause, re-enter the Consumer Key and Secret and click Save credentials.

Salesforce → Kraya request errors

• 401: the token in the External Credential doesn't match the Header Token in Kraya, or the custom header name/formula is wrong. It must be X-Kraya-Webhook-Token.
• 404: the Endpoint URL is wrong or old (for example, after a disconnect and reconnect). Copy the current URL from Kraya.
• 400: the response lists the bad fields. Usually phone is empty or "N/A", name is missing, or email is invalid.
• 422: select a pipeline on the Kraya settings page and save.

Leads from Salesforce aren't arriving

• In Salesforce, check Setup → Paused and Failed Flow Interviews and the flow error emails for the callout's response.
• Check the Flow's start conditions. A new lead may need one edit before it syncs.
• Make sure the user who edited the lead has External Credential Principal Access (step 6).

New Salesforce leads are owned by the integration user

• No Lead assignment rule is active. Create one in Setup → Lead Assignment Rules.

Some leads don't update in Salesforce, or duplicates appear

• Your Lead sharing is Private and the integration user can't see leads owned by others. Add View All and Modify All on Lead to the Kraya permission set.
• Converted, locked or deleted Salesforce leads are skipped.

A mapped field isn't updating

• The value didn't fit the Salesforce field (type, picklist value or length), or the field was created after you connected. Ask Kraya support to check the mapping and refresh the field list.

FAQs

• Which mode am I in? Standard mode, unless Kraya set up Sub-Status mode for you. The sample request on the settings page shows kraya_stage for standard mode and sub_status for Sub-Status mode.

• Will Kraya change a lead's owner or Status? No. Kraya never writes Owner or Status and never runs assignment rules on updates. Assignment rules run only when Kraya creates a new lead.

• Will Kraya create duplicates in Salesforce? Kraya searches by phone first and links to an existing lead instead of creating one. It also links when a duplicate rule blocks the create.

• Do my existing Kraya leads get created in Salesforce? No. Only leads added after you connect are created. Existing leads are linked when Salesforce sends them to Kraya.

• Can a blank value from Salesforce erase Kraya data? No. A blank email, blank notes or empty attribute never clears Kraya's value.

• How fast is the sync? Salesforce → Kraya: a few seconds after the Flow runs. Kraya → Salesforce: about 30 seconds.

• What happens to my leads if I disconnect? They stay in Kraya. Only syncing stops.

Tips and best practices

• Use the same stage and pipeline names in Salesforce values and in Kraya.
• Always skip the integration user in your Flow's start condition.
• Keep the Header Token private. If it leaks, disconnect and reconnect to get a new one.

Related features

• Integration Hub — where you open every integration, including Salesforce
• Zoho Integration — two-way CRM sync with Zoho
• teleCRM Integration — two-way lead sync with teleCRM
• Smart Triggers — automations that run when leads change stage
• Auto Followups — WhatsApp sequences for your leads

Screenshots still to add

The images already in this guide sit under the step they belong to. These five are still missing, with the state each one needs to be captured in:

The last two only appear when no connection exists or a connection has failed, so they have to be captured during a fresh setup rather than on a working one.

Before committing any screenshot, blur the Endpoint URL, the Header Token, the Consumer Key and Secret, and any real lead names or phone numbers.