Connect Salesforce to Zaags

Setup guide for your Salesforce administrator · last updated September 2026 · about 15 minutes

The Zaags Assistant answers your customers on WhatsApp, email and your website, using your Salesforce as its source of truth, and hands the conversation to your team, inside Salesforce, whenever a human should take over. This guide walks you through connecting your org, and spells out exactly what Zaags is allowed to read and write there.

0What you need

A Salesforce user with the System Administrator profile (to create the app and the permission set).
An edition with API access: Enterprise, Unlimited, Performance or Developer. Professional works only with the paid API add-on. Essentials does not have API access.
Your Zaags account, signed in at zaags.app, with the 🤝 ZaagsForce Assistant tool open.
If you want the assistant to answer “how do I…” questions: Salesforce Knowledge enabled, with published articles.

You will copy two values from Salesforce into Zaags (a Consumer Key and a Consumer Secret), and one value from Zaags into Salesforce (a callback address). Nothing is installed in your org.

1Create an integration user (recommended)

Connect Zaags through a dedicated user rather than a person's login. It keeps the audit trail clean (“created by Zaags Assistant”), survives staff changes, and lets you cap what Zaags can do with a permission set, even a bug on our side could then not exceed it.

Setup → Users → New User.
First name Zaags, last name Assistant, a mailbox you control (for example zaags-integration@yourcompany.com).
User License: Salesforce (or Salesforce Integration if your org has that licence, it is cheaper and made for this). Profile: Minimum Access – Salesforce (or Minimum Access – API Only Integrations with the Integration licence).
Tick Knowledge User if your org uses Salesforce Knowledge and the licence allows it. Save.
Set the password from the activation email, and enable the org's usual two-factor method.

Skipping this step? You can connect with your own admin account. Zaags will still only perform the operations listed in section 7, but the ceiling would then be your account's permissions, not the narrow set below.

2Grant exactly the right permissions

Create one permission set and assign it to the integration user. This is the complete list, nothing else is needed, and we recommend granting nothing else.

Setup → Permission Sets → New. Label Zaags Assistant. Licence: leave None. Save.
System Permissions: tick API Enabled. Nothing else.
Object Settings, set per object:

Object	Read	Create	Edit	Delete	Why
Accounts	✓	,	,	,	Identify who a customer belongs to
Contacts	✓	,	,	,	Recognise a customer by phone or email
Leads	✓	✓	,	,	Recognise a known lead; add a new prospect (if you enable it)
Cases	✓	✓	,	,	Show a verified customer their own case status; open a case when a human is needed
Case Comments	✓	✓	,	,	Keep the conversation on the case Zaags opened
Tasks (Activities)	✓	✓	,	,	Log a finished conversation on the contact (if you enable it)
Opportunities	✓	,	,	,	Alert your team faster for high-value accounts. Never shown to customers.
Knowledge (articles)	✓	,	,	,	Ground answers in your published articles

Field-level security: give Read on the standard fields of those objects. Zaags reads only standard fields unless you explicitly add a custom field by API name in the Zaags settings.

Manage Assignments → Add Assignment → pick the Zaags Assistant user. Done.

Do not grant

Modify All Data, View All Data, Edit or Delete on any object, Author Apex, Customize Application. Zaags does not use them and will work correctly without them.

3Create the app in Salesforce

This is where the two values Zaags needs, the Consumer Key and Consumer Secret (Salesforce's name for the app's passkeys; elsewhere called client id / client secret), come from. Salesforce lets outside software connect through an External Client App (newer orgs) or a Connected App (older orgs). Either works. Use the one your Setup offers.

Finding your way (first time in Salesforce?)

Everything happens in Setup: click the gear ⚙ icon at the top right of any Salesforce page → Setup. A new tab opens.
On the left is a Quick Find search box. You never browse the menu tree, type what you need (e.g. App Manager, Permission Sets, Users) and click the result.
Type App Manager → open it → the buttons are at the top right of the list: New External Client App and New Connected App.
Don't see “New External Client App”? Type External Client App Settings in Quick Find and switch ON “Allow creation of External Client Apps”, brand-new orgs (including free Developer orgs) sometimes ship with it off. If it still isn't there, simply use New Connected App (Option B below) it works identically for Zaags.

Option A, External Client App (recommended if available)

Setup → App Manager → New External Client App.
Name Zaags Assistant, API name auto-fills, contact email = your admin address. Distribution state: Local.
Open API (Enable OAuth Settings) → tick Enable OAuth.
Callback URL, paste exactly:
https://zaags.app/sf/callback
OAuth Scopes, add these four and no others:
- Manage user data via APIs api
- Perform requests at any time refresh_token, offline_access
- Access the identity URL service id, profile, email, address, phone
- Access unique user identifiers openid
Flow Enablement: tick Enable Authorization Code and Credentials Flow. Leave Device Flow, JWT and Client Credentials off.
Security: tick Require Proof Key for Code Exchange (PKCE), Require secret for Web Server Flow, Require secret for Refresh Token Flow. Save.
After saving, open Policies → OAuth Policies: Permitted Users Admin approved users are pre-authorized → then under Permission Sets add Zaags Assistant. IP Relaxation: Relax IP restrictions (Zaags calls from cloud addresses). Refresh Token Policy: Refresh token is valid until revoked. Save.

Option B, Connected App (if your Setup has no “External Client App”)

Setup → App Manager → New Connected App. Same name and contact email.
Tick Enable OAuth Settings, paste the same Callback URL above, add the same four scopes.
Tick Require Proof Key for Code Exchange (PKCE) and Require Secret for Web Server Flow and Require Secret for Refresh Token Flow. Save. Salesforce says it may take up to 10 minutes to activate.
Manage → Edit Policies: Permitted Users Admin approved users are pre-authorized, IP Relaxation Relax IP restrictions, Refresh Token Policy valid until revoked. Save. Then Manage Permission Sets → add Zaags Assistant.

4Copy the Consumer Key & Secret

External Client App: Setup → Quick Find App Manager → click your app's name → Settings tab → open OAuth Settings → button Consumer Key and Secret. Connected App: App Manager → find the app in the list → click the little ▾ at the end of its row → View → button Manage Consumer Details.
Salesforce will ask you to verify your identity (code by email or authenticator).
Copy the Consumer Key and the Consumer Secret. Treat the secret like a password, paste it straight into Zaags, do not email it.

5Connect in Zaags

In Zaags open 🧰 Tools → 🤝 ZaagsForce Assistant → 1 · Connect Salesforce.
Paste the Consumer Key and Consumer Secret.
Login URL: leave https://login.salesforce.com for production, use https://test.salesforce.com for a sandbox, or paste your My Domain address (for example https://yourcompany.my.salesforce.com) if your org requires it.
Click Authorize. Salesforce opens: sign in as the integration user (not as yourself), review the four permissions, click Allow. You are returned to Zaags.
Zaags runs a connection check and shows a checklist: who is connected, which objects and fields are reachable, whether Knowledge has published articles, your remaining daily API requests, and any picklist values it could not find (see next section). Green across the board means you are done.

What we hold, and what we never see

We never see your password. You sign in on Salesforce's own page; Salesforce hands Zaags a token. What Zaags does hold is the Consumer Key and Secret you created and that token, every integration that must work while you are offline holds the same, including Salesforce's own connectors. They are encrypted at rest with a key that is not stored in our database, never logged, never shown again in full, never shared with other Zaags customers, and limited to the four permissions above. You can cut them off at any moment from Salesforce itself, without asking us (section 8).

6Picklists & Knowledge

Two small things make the records Zaags creates fit your org neatly:

Case Origin. Zaags stamps the channel on each case it opens. Setup → Object Manager → Case → Fields → Case Origin: add the values WhatsApp, Email and Web Chat if you do not have equivalents, or tell Zaags which of your existing values to use. If a value does not exist, Zaags simply leaves Origin blank rather than failing.
Lead Source (only if you enable lead capture). Same idea: add Zaags Assistant or map to an existing value.
Case assignment. By default Zaags lets your assignment rules route new cases. Alternatively pick a specific queue or user in the Zaags settings.
Knowledge. Zaags reads published (“Online”) articles only, in your org's default language, refreshed daily. Drafts and archived articles are never read. Articles restricted by data category are only visible if the integration user can see them.
Validation rules. If a rule on Case or Lead requires a field Zaags does not fill (for example a mandatory custom “Product” field), Zaags's write will be refused by Salesforce. Zaags shows you the exact message and still alerts your team through every other channel nothing is lost, but you may want to exempt the integration user from that rule.

7What Zaags reads, and the complete list of what it writes

This is a promise, not a summary. The Zaags software has no code path for anything outside these tables.

Reads

Object	Fields	Used for
Contact	name, email, phone, mobile, account, owner, last activity	Recognise the customer
Lead	name, email, phone, company, status, owner, converted?	Recognise a known lead; avoid duplicates
Account	name, owner, type, industry	Context for your team
Case	number, subject, status, priority, origin, dates, contact, owner; description (team alert only)	A customer sees only cases linked to their own contact record
Opportunity	name, stage, amount, close date, account, owner	Internal only, prioritises alerts for high-value accounts. Never shown to a customer.
User	name, email of record owners	Address the alert to the right colleague
Knowledge	published articles: title, summary, body	Grounded answers

Custom fields are read only if you add them yourself, one by one, in the Zaags settings.

Writes, the complete list

What	When	Fields set	Your control
Create a Case	A conversation needs a human	Subject, Description (transcript + why), Origin, Priority (if mapped), Contact (only when identified with certainty, otherwise the “Supplied” name/email/phone fields), Owner (only if you chose one; else your assignment rules)	On / off
Add a Case Comment	Each new message after hand-over	Comment body, only on the case Zaags itself created for that conversation	On / off
Create a Lead	A new prospect shows buying intent and matches no existing Contact or Lead	First/last name, company, email, phone, Lead Source (if mapped), Description	Off · Ask me first (default) · Automatic
Create a Task	A conversation with an identified customer ends	Subject, summary, status Completed, linked to the contact/lead and account	Off (default) / on

Zaags never

Updates any record, no status changes, no owner changes, no closing cases, no “correcting” a contact's phone or email.
Deletes anything.
Creates or changes Contacts, Accounts, Opportunities, Knowledge articles or users. New people become Leads, never Contacts.
Converts leads, merges cases, changes sharing, runs Apex, uses bulk or metadata tools, or posts to Chatter.
Uploads customer files into Salesforce, attachments stay in Zaags and are linked.
Shows a customer anything about another customer, or anything from Opportunities.

Every write attempt successful or refused, is listed in the Zaags Activity tab with its payload and Salesforce's response, and can be exported. A retried message can never create a duplicate case or lead.

8Revoking access

From Zaags: 🤝 ZaagsForce Assistant → Settings → Disconnect. Tokens are deleted immediately.
From Salesforce (works even if you cannot reach Zaags): Setup → Connected Apps OAuth Usage → Zaags Assistant → Revoke, or simply deactivate the integration user. Zaags stops on its next call and notifies you that the connection needs attention.

9Troubleshooting

You see	Cause	Fix
`redirect_uri_mismatch`	Callback URL differs by one character	Paste exactly `https://zaags.app/sf/callback`, https, no trailing slash
`invalid_client_id` right after creating a Connected App	Salesforce is still activating it	Wait up to 10 minutes and retry
`OAUTH_APP_ACCESS_DENIED` / “user is not admin approved”	Policy is “Admin approved” but the permission set is not attached to the app	Section 3, last step: add the Zaags Assistant permission set under the app's policies
`invalid_grant` later on	Token revoked, user deactivated, password policy expired the session, or IP restriction	Re-authorize from Zaags; check IP Relaxation is “Relax”
“API is not enabled for this user / org”	Missing API Enabled or an edition without API	Section 2, step 2, or see edition note in section 0
Connection check: “Knowledge: 0 articles”	Knowledge off, nothing published, or user lacks Knowledge access	Publish articles; tick Knowledge User on the integration user; check data-category visibility
A case was refused: `REQUIRED_FIELD_MISSING` / `FIELD_CUSTOM_VALIDATION_EXCEPTION`	A validation rule or required custom field	Exempt the integration user in the rule, or make the field optional. Your team was still alerted.
“Approaching daily API limit”	Your org's shared daily request budget is nearly used up (by all integrations)	Zaags pauses lookups and answers from its article cache until the rolling 24-hour window frees up

10Questions

Does Zaags copy my Salesforce data? No. Customer records are read live, used for the answer or the alert, and not stored beyond the alert itself and the conversation transcript. Published Knowledge articles are cached for up to 24 hours so answers stay fast.

Where do the conversations live? With you. Connect your own Google Drive (zero setup) or your own Supabase project in Zaags and every conversation is archived there, plus, escalated conversations are already in Salesforce as Cases. Zaags keeps a working copy only while a conversation is open and for 7 days after it closes, then deletes it (90 days if you connect no storage of your own). The one thing we keep longer is the log of what Zaags wrote to your org, 13 months, as your audit trail.

Who is the data processor? Zaags is operated by RUDLU Unipessoal Lda (Lisbon, Portugal) and acts as your processor under the GDPR. See our Privacy Policy and Terms.

Can I try it on a sandbox first? Yes, create the app in the sandbox, use https://test.salesforce.com as the login URL, then repeat in production when you are happy.

Will this count against my API limits? A little. Zaags makes at most three calls per customer message and caches what it can. Typical support volumes use a small fraction of an Enterprise org's daily budget. Zaags shows your remaining requests in the connection check.

Need help? Write to contact [at] zaags.app with a screenshot of the connection check.