Build with

Overview

Connect your Salesforce org with OAuth, then use Voiceflow’s built-in tools to create or update Contacts, Leads and Cases, or add a CaseComment. Voiceflow manages authorization for these tools; you can configure their inputs and capture their results directly in Agent studio.

The manual also covers additional workflows: standalone contact lookup through a separately authorized API tool, approved public articles for Knowledge, and Service Cloud messaging through a hosted relay. Set up those connections only for the workflow you need.

Studio

Use a test project and Salesforce administrator who can authorize the intended org and its object/field access. Start with Salesforce in the tool picker after connecting. The standalone-lookup and messaging sections explain their additional setup locally.

Code

Use Voiceflow APIs or CLI to configure and execute the same built-in Salesforce tools with the project’s OAuth connection. Browser authorization remains required. Additional API-tool, Knowledge and messaging recipes have their own prerequisites.

Connecting Salesforce actions

Authorize the org and prepare the CRM actions your workflow needs.

Use a project you can edit and a CRM account authorized for the objects and fields the agent will access. A CRM administrator must approve the connection and any account-specific required fields. OAuth acts through the connected account; it does not authenticate the customer chatting with the agent.

Available Salesforce tools

These seven tools use the Salesforce org connected below. They do not require a separate Salesforce API token or an API tool.

Authorize and prepare actions

Studio

1

Open the CRM connection

Open your project in Agent studio. In the left sidebar, expand More, select Integrations, then choose Connect on Salesforce. Check which connection slot you are editing before authorization.

2

Authorize the intended account

Enter the subdomain requested by Subdomain URL, not a full URL. The authorization host is https://SUBDOMAIN.my.salesforce.com; obtain the correct subdomain from your Salesforce administrator. Complete authorization in the provider’s browser window. Return to Voiceflow and check the connected account before configuring actions.

Authorize the intended Salesforce account before using CRM actions. Photo:
3

Choose and test an action

Return to Agent → Global tools → +, choose Salesforce, and select the required action. Write its Trigger, review the named inputs and configure Capture response for values needed later. Alternatively use an Integration step in a Workflow when the action must occur at a fixed point. Test in a dedicated project with records you can inspect; a Connected badge alone does not verify a write.

Code

The Code path also requires browser OAuth. Open Agent studio, select the project matching PROJECT_ID, open More → Integrations → Salesforce → Connect, and authorize the intended account. Enter the subdomain requested by Subdomain URL, not a full URL. The authorization host is https://SUBDOMAIN.my.salesforce.com; obtain the correct subdomain from your Salesforce administrator. Return to the project and check the connection before resuming the commands below. The generic Connect integration API does not replace this OAuth flow.

Authorize the intended Salesforce account before using CRM actions. Photo:

Use a Voiceflow bearer credential with access to this project and test Environment. Keep it on your backend and set:

Install the Voiceflow CLI if you choose CLI; these commands read VF_TOKEN and request JSON output.

Read the available tools[].toolName, inputs and integrationToolID:

Use the standalone action examples in the following sections to test the connected account. For conversation use, follow Use CRM tools in an agent before opening the detailed attachment commands.

  • connected reports stored credential keys, not provider acceptance. A Draft-only connection can run while this flag reads false.
  • Standalone calls use the selected Environment’s Draft and the project’s Draft integration slot, falling back to its Published slot.
  • The literal-input boundary and provided-field alternative are described in Use CRM tools in an agent.

The connected account belongs to the project, rather than an independently isolated account per Environment. Use a dedicated test project when testing another CRM account. API-tool and support-relay credentials are configured only for those additional workflows.

Use CRM tools in an agent

Start with an agent that already handles a Draft conversation in the selected test Environment. Keep its existing Playbooks or Workflows registered while adding these tools.

Native input binding can interpret brace-shaped strings in agent arguments as well as standalone requests. JSON quoting and backslashes do not escape them. The nativeCRMInputs guard validates backend-prepared literal fields; a per-turn proxy cannot sanitize model arguments after the agent generates them. Use the provided-field Workflow path for untrusted text requiring enforced literal-data validation.

Studio

1

Choose where the action is available

In Agent → Global tools → + → Salesforce, add the action the agent needs. For a task limited to one Playbook, use that Playbook’s tool picker. Use an Integration step in a Workflow for a fixed sequence such as confirmation → write → result check.

2

Explain when to call it and bind its inputs

Open the attached tool and set its Trigger to the customer job, such as “Create a contact after the customer confirms a sales enquiry.” Let the agent collect the named customer details. Bind record IDs and administrator-approved routing values as provided inputs; require the agent to ask for confirmation. A Trigger guides the model; use the guarded Workflow sequence below when confirmation must be enforced before the action.

3

Use the current result in the answer

Use Capture response for values needed later. Return to Agent and use Run to start a conversation; the individual tool’s Run is a separate request test. Ask “Can I arrange a demo for 25 people?”, supply the missing details and confirm the request. Inspect the actual tool call and CRM record before the agent says it was saved. A failed call must use the support fallback.

Code

Attach each saved catalog action to target: {"global":true}, or to {"playbookID":"YOUR_PLAYBOOK_ID"} when it belongs to one Playbook. The attachment’s description supplies the invocation guidance shown as Trigger in Studio. Use the action-specific guidance below; creating or executing a catalog action does not make it available in a conversation.

Let the model collect customer details through declared required inputs with null defaults. Supply authorized record IDs and approved routing values through provided defaults. This direct attachment uses model instructions for conversational confirmation; a per-turn proxy cannot intercept its native tool call. For enforced confirmation, use the guarded Workflow sequence below instead of exposing the raw write. Compile the Draft and send a conversation to check actual selection, inputs and response. The full attachment commands are in Attach a connected CRM tool to an agent below.

Send “Can I arrange a demo for 25 people?” with missing details, then complete and confirm the request. Inspect the selected tool and current CRM result before the agent acknowledges capture. Repeat with a rejected write: the agent must explain that the request was not saved.

For built-in Capture response, use Id for the returned record, and fields such as Phone after an update. These paths start inside native data; standalone calls use output.data.*. Keep Contact, Lead, Case and CaseComment IDs in separate variables.

For a fixed confirmation/validation sequence, create salesforce_write_confirmed and salesforce_action_result_id in More → Variables, with empty defaults (Code uses the variable-creation pattern in Recognizing customers). Have the developer provide a variable for each confirmed action input, such as salesforce_confirmed_FirstName / salesforce_confirmed_LastName / salesforce_confirmed_Company for Lead capture; use each selected action’s exact field names. The backend validates these fields with nativeCRMInputs and sets the approval variable to yes only for that server-recorded request; it clears approval before other turns.

At Workflow entry, clear salesforce_action_result_id. Add a Condition requiring salesforce_write_confirmed is yes; its Else path returns to confirmation without a write. On the matching path, run the Integration step with every input provided from its confirmed field or authorized ID/routing variable. Demonstrate that each variable is populated before testing the action.

Capture the current action’s ID into salesforce_action_result_id, using the capture path listed in this setup. Follow the Integration step with a Condition checking that result is not empty. Only a current ID proceeds to the capability’s saved-field check; the other path reports failure or an unverified outcome and reconciles before retry. Integration steps have no separate Failure path. Include the result variable as a real reference in the agent’s instructions so it can distinguish the outcome.

Attach that Workflow to the agent with a Trigger for the customer job, keeping the raw action off Global/Playbook tool lists. The direct attachment example below uses conversational model guidance; its Trigger does not enforce this gate.

Code

For the guarded path, create the graph through Workflow creation and attach its returned ID through Create tool as type: "workflow". Keep the confirmation variable provided by the backend, outside model-collected inputs. Standalone backend execution can check approval before calling execute; that check does not intercept calls from a directly attached native tool.

Capture paths are relative to the tool’s current response, not the standalone output envelope. Captures can retain an earlier value after a failure or missing field; a retained ID alone is not a success check. Use the current result and the capability’s completion check before answering, and clear retained outputs before a new attempt when your workflow relies on them.

Code

Attach a connected CRM tool to an agent

Prepare catalog selection, input bindings and Draft compilation.

These examples add salesforce_create_contact to an agent. Choose another discovered toolName for a different built-in action. This is separate from testing an action independently.

  1. Add the catalog action using API or CLI below; keep its returned integrationToolID.
  2. Save salesforce-attachment.json using this payload, replacing YOUR_RETURNED_INTEGRATION_TOOL_ID with that returned ID:
  1. Create the attachment, resolve unresolvedReferences, compile the Draft and test an agent conversation. Publishing remains a separate reviewed step.

Save {"toolName":"salesforce_create_contact"} as salesforce-catalog.json, then add it:

Keep the returned ID and fill the attachment file above before continuing:

Inspect tool selection and the saved CRM record before publishing the reviewed Environment. Compilation does not publish.

Reconnect or stop using the account

Manage the connection without changing saved customer records.

Open More → Integrations, manage the provider’s connection and use Disconnect only when you intend to stop tools using that slot. Authorize the intended replacement account through the browser and rerun one controlled action. Disconnecting does not delete contacts, leads, tickets or cases already created. Review provider-side app access separately. Do not use disconnect as an automatic response to an action or validation error.

Capturing enquiries

Create the Contact or Lead appropriate to your CRM process.

Choose Contact for an existing customer relationship or Lead for an unqualified sales enquiry, according to your team’s CRM process. These actions create different Salesforce objects; neither converts a Lead or creates an Opportunity. Apply qualification rules and confirm the information before writing.

Capitalization matters. An admin must confirm object Create and Read access, field access, required custom fields and duplicate rules. Both actions create the object and retrieve it again; a failed read after a write can leave the record created even though the overall action failed.

In the conversation: Set the create tool’s Trigger to saving the customer’s confirmed sales enquiry. Let the agent collect the action’s required name and company details, plus approved optional contact fields; select Contact or Lead deliberately. Retain the current created record ID and acknowledge the saved enquiry; a rejected write must not produce a success message. Test an incomplete enquiry followed by confirmation, and verify one record of the selected object type.

Save the confirmed enquiry

These illustrative inputs write to the connected account. Replace them with confirmed test data.

Studio

1

Add the create lead tool

In Agent → Global tools → + → Salesforce, choose Create lead. Use an Integration step in a Workflow when the action must run after a fixed confirmation or qualification gate.

2

Set the confirmed inputs

Use the field names and worked values above. Bind customer and record identifiers to your authorized application values; omit unrelated optional fields.

Configure the create lead inputs before testing the saved record. Photo:
3

Run and capture the result

Use Run to exercise the action. Inspect data.Id in the result and retain the record ID with Capture response. Open that record in Salesforce and compare the saved values before reporting success.

Code

Save this confirmed request as salesforce-action.json before running it:

Require success: true, error: null and truncated: false. Keep output.data.Id from the result. Voiceflow HTTP success alone does not establish a successful CRM write.

Open that same record in the CRM and compare the saved values. Retain its ID with the customer and request. After an ambiguous timeout, reconcile the CRM record before retrying creation; these actions are not an idempotent upsert.

For a Contact, run salesforce_create_contact with FirstName, LastName and Email; add Phone or Title only when confirmed and needed. Inspect output.data.Id and the actual Contact. Do not pass Lead-only Company, AccountId, OwnerId or custom properties to this Contact action: use the action’s discovered schema. Your org’s default assignment or other automation can affect the saved record, so inspect its final state rather than promising a particular owner.

Updating customer records

Change supported Contact or Lead fields on the existing record.

Use the existing record ID mapped to the authenticated customer. Confirm the proposed fields before writing. A Contact ID and a Lead ID refer to different objects; use the matching action rather than creating another record.

The integration passes only these schema fields; an arbitrary Salesforce field is not accepted simply because the provider API supports it. The administrator must grant Update and Read access and approve the changed fields. Omit values that should remain unchanged.

In the conversation: Run Update contact or Update lead after the customer confirms the exact proposed change. Let the agent collect the changed text; provide the matching object’s authorized Id and keep confirmation enforced by the backend or Workflow. Compare the current returned ID and saved fields before answering; reconcile an uncertain response instead of creating another record. Test an unconfirmed change and a confirmed phone change, then inspect the same existing record.

Change the confirmed phone

These illustrative inputs write to the connected account. Replace them with confirmed test data.

Studio

1

Prepare the authorized Contact ID

In More → Variables, create salesforce_contact_id with an empty default. Have your application developer populate it from the authenticated customer mapping on every turn and resume, retaining runtime credentials server-side and rejecting client identity overrides. Alternatively, authorize the record inside a backend tool on every operation.

2

Add the update contact tool

In Agent → Global tools → + → Salesforce, choose Update contact. Use an Integration step in a Workflow when the action must run after a fixed confirmation or qualification gate.

3

Set the confirmed inputs

Click the Id input row and set Default value to salesforce_contact_id using Variables. Click outside to save and check Value provided. Configure the other confirmed fields above; leave unrelated optional fields omitted. The switches control field inclusion, not its value.

Update only the confirmed phone on the existing Contact. Photo:
4

Run and capture the result

Use Run to exercise the action. Inspect data.Id in the result and retain the record ID with Capture response. Open that record in Salesforce and compare the saved values before reporting success.

Code

Save this confirmed request as salesforce-action.json before running it:

Require success: true, error: null and truncated: false. Keep output.data.Id from the result. Voiceflow HTTP success alone does not establish a successful CRM write.

Open that same record in the CRM and compare the saved values. Retain its ID with the customer and request. After an ambiguous timeout, reconcile the CRM record before retrying creation; these actions are not an idempotent upsert.

These actions update then retrieve the object, returning its saved fields under data. Compare output.data.Phone and the unchanged ID with the customer’s confirmed number. Read the same Contact using the lookup recipe, or inspect it in Salesforce, to verify persistence after an uncertain response. A timeout or failed readback can occur after the update succeeded; reconcile before retrying.

For a Lead, execute salesforce_update_lead with its mapped Id and only the approved changed fields. The Contact lookup above must not be pointed at a Lead; use /services/data/v65.0/sobjects/Lead/{lead_id} with the corresponding field access and trusted Lead mapping when preparing that read.

Recording follow-up

Create a Case, update its details and retain useful support context.

Create a Case for a confirmed support request. Have your Salesforce administrator supply an authorized Contact ID and an allowed Origin. The action sets Status: New, then retrieves the saved Case.

  • Priority is optional. Omit it to use the org’s default. When supplied, the connector accepts only low, normal or high; the administrator must verify that the org accepts that API value. A display label such as Medium is not a substitute.
  • If the org requires another priority value, use an administrator-prepared API or Function request with that verified value.
  • Org validation and automation can affect acceptance and routing. Inspect the final Case and owner.

In the conversation: Set Create case to a confirmed support request; use Update case or Add comment to a case only for that authorized Case. Let the agent collect the issue or comment; provide Contact/Case IDs and the administrator-approved Origin and routing policy. Retain the current Case ID separately from a new CaseComment ID and acknowledge saved work, not a delivered public reply. Test creating a Case and adding context to that same Case; a failed action must not be reported as completed.

Record the case

These illustrative inputs write to the connected account. Replace them with confirmed test data.

Studio

1

Prepare the authorized Contact ID

In More → Variables, create salesforce_contact_id with an empty default. Have your application developer populate it from the authenticated customer mapping on every turn and resume, retaining runtime credentials server-side and rejecting client identity overrides. Alternatively, authorize the record inside a backend tool on every operation.

2

Add the create case tool

In Agent → Global tools → + → Salesforce, choose Create case. Use an Integration step in a Workflow when the action must run after a fixed confirmation or qualification gate.

3

Set the confirmed inputs

Click the ContactId input row and set Default value to salesforce_contact_id using Variables. Click outside to save and check Value provided. Configure the other confirmed fields above; leave unrelated optional fields omitted. The switches control field inclusion, not its value.

Configure the create case inputs before testing the saved record. Photo:
4

Run and capture the result

Use Run to exercise the action. Inspect data.Id in the result and retain the record ID with Capture response. Open that record in Salesforce and compare the saved values before reporting success.

Code

Save this confirmed request as salesforce-action.json before running it:

Require success: true, error: null and truncated: false. Keep output.data.Id from the result. Voiceflow HTTP success alone does not establish a successful CRM write.

Open that same record in the CRM and compare the saved values. Retain its ID with the customer and request. After an ambiguous timeout, reconcile the CRM record before retrying creation; these actions are not an idempotent upsert.

Origin: Web is illustrative: use the value your org allows. Inspect the Case’s Contact, Status, content and actual owner. OwnerId and Status are not inputs to the Create/Update case actions. If your org routes Cases automatically, the administrator must configure and test that route; do not assume a REST create invokes a particular assignment rule.

Update the same case or add context

Studio

  • Change the Case: choose Update case, set Id to the saved Case ID and supply only the supported fields you intend to change.
  • Add a note: choose Add comment to a case, set ParentId to the same Case ID and enter CommentBody.
  • Check the result: inspect the saved record in Salesforce, including the CaseComment’s visibility. The comment action has no IsPublished input and does not establish delivery of a public reply.

Code

Execute salesforce_update_case with the saved Id and a subset of ContactId, Origin, Subject, Description, Priority. Execute salesforce_add_comment_to_case with ParentId and CommentBody. Use the same /v1/stable/integration/salesforce/execute request/CLI procedure above, check the execution envelope and retain output.data.Id for the returned record. A comment’s ID differs from its parent Case ID.

If explicit ownership is required, use a separately authorized request to the approved org’s /services/data/v65.0/sobjects/Case/CASE_ID with PATCH body {"OwnerId":"APPROVED_USER_OR_QUEUE_ID"}. The API principal needs the applicable record/field/transfer permissions, and the queue must support Cases. Then GET the same Case and verify OwnerId. The downloadable request builders show this focused request using existing API/function primitives. A direct provider HTTP 204 has no record body; it is different from Voiceflow’s native action response. The CRM OAuth grant is not exposed as a token for that request.

Creating a Case, adding a CaseComment and exchanging live messages are separate tasks. Use Human agent hand-off when the customer needs a live Service Cloud rep, and preserve the verified customer-to-Case mapping for later status reads.

Recognizing customers

Retrieve the Contact authorized for the signed-in customer.

For a standalone Contact lookup, configure the API tool in this section. The built-in Salesforce catalog does not expose a standalone read action. Its create/update tools retrieve the written record as part of their execution; they can use an already-authorized record ID without this lookup.

Studio

1

Obtain the authorized customer mapping

Have your application developer map the signed-in customer to the correct Salesforce Contact ID and account. A typed email or record ID is not proof of access.

2

Keep the mapping protected

The developer must supply the authorized ID on every turn and resumed session, prevent client identity overrides and retain runtime credentials server-side. Alternatively, a backend tool must authorize each operation. Ask them to demonstrate a later-turn override test before exposing customer data.

Code

Enforce the customer-to-record relationship on your backend for every operation. Keep the Voiceflow session userID separate from the CRM record ID.

  • Retain runtime session credentials on a trusted backend proxy; accept only permitted customer actions.
  • Discard client-supplied variables, state, user IDs and session keys. Rebuild the CRM ID from the authenticated customer/tenant map on every forwarded turn and resumed session.
  • Do not expose direct browser runtime access. Alternatively, enforce the same record authorization inside each backend tool.

An initial launch binding alone is insufficient: later runtime requests can replace session variables. A tool Trigger does not enforce authorization.

A CRM administrator must provision a separate API credential for this request. Use an OAuth access token for the same Salesforce org with API access and Read permission on Contact and the requested fields. Obtain the org instance URL from the OAuth response. A developer must maintain token refresh on their backend; copying a short-lived token into a Secret does not refresh it.

In the conversation: Set the lookup’s Trigger to questions about the signed-in customer’s saved profile. Provide the Contact ID from the authenticated application; the agent must not collect it from chat. Use only approved fields from the current matching Contact; a missing mapping or failed lookup uses general help. Test “What phone number do you have for me?” and a foreign Contact request; the answer must use only the authorized record.

Prepare the contact lookup

Studio

1

Prepare the trusted inputs

In More → Secrets, create salesforce_api_token with the administrator’s test token. Creating a default also sets Main’s Published value, so use a test project; set an override for the intended Environment/version when needed. In More → Variables, create salesforce_contact_id with an empty default. Your backend proxy supplies the authorized record ID on every interaction and prevents direct client access to the runtime credentials. Have the application developer demonstrate a later-turn variable-override test before exposing this lookup to customers.

2

Configure the API request

Open Agent → Global tools → + → API. Create Find Salesforce customer, select GET, and enter https://YOUR_INSTANCE.my.salesforce.com/services/data/v65.0/sobjects/Contact/{contact_id}?fields=Id,FirstName,LastName,Email,Phone. Replace YOUR_INSTANCE.my.salesforce.com with the instance host approved for your org; keep that host fixed in the tool. Add Authorization: Bearer {token} and Accept: application/json.

3

Bind the credential and customer ID

Save the request and return to Agent → Global tools. Click the lookup tool, then the token row under Input variables. Set Default value to salesforce_api_token using the Secrets picker. Open the contact_id row and select salesforce_contact_id from Variables. Click outside to save. The contact_id row should show Value provided; reopen token to check its Secret reference.

Bind the CRM lookup to the customer ID verified by your application. Photo:
4

Test permitted records

Run with one authorized test record. Inspect Id, FirstName, Email and Phone and capture only the fields the customer may see. Test a missing mapping and a record belonging to someone else; neither may expose another customer. A provider 404 is not permission to create a replacement contact automatically.

Code

Use the Voiceflow credential and test Environment from Connecting CRM actions. Set CRM_CONTACT_ID to a record your backend has authorized. Use a fixed approved provider host; do not accept an arbitrary URL from the conversation.

Save salesforce-lookup.json with this definition after replacing the Salesforce instance host:

In a dedicated test project, create the credential and identity variable before binding them. These calls use the same Voiceflow bearer header as above:

Secret creation writes the project default and Main’s Published value. Save secret.id; use Secret value configuration to set the intended Draft and Published overrides separately. The connection used by native CRM actions does not expose a token for this API request.

Save apiTool.id as API_TOOL_ID, then inspect inputs and execute:

Require success: true, error: null, truncated: false, provider output.status: 200 and the expected output.body record. Check Id, FirstName, Email and Phone. An HTTP 200 from Voiceflow alone is not a successful contact read.

For an agent attachment, list variables[] above and match each name to its id. Save the following as salesforce-lookup-attachment.json, replacing all three IDs:

POST it to /v2/stable/tool with the same query and bearer header, or run vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --output-format json < salesforce-lookup-attachment.json. Resolve unresolvedReferences before testing. Creating an API tool alone does not attach it.

Your backend proxy supplies variables: {"salesforce_contact_id":"AUTHORIZED_CRM_CONTACT_ID"} on the initial launch and every subsequent turn, using the authenticated application session’s server-side mapping. Do not forward a browser-supplied mapping or runtime session key. The trustedCustomerTurn helper accepts only launch/text for this workflow, discards client overrides and rebuilds protected variables; its fixture tests exercise a later-turn override. Integrate it behind your existing application authentication, keep runtime credentials server-side, and send only its returned action/variables through the Chat interaction contract. Reject missing/untrusted mappings rather than forwarding the turn. Compile the Draft, run an authenticated test conversation, then configure Published credentials before publishing.

If credentials expire, refresh or replace them through the credential owner; do not retry with another customer’s record. Use HubSpot contact retrieval or Salesforce sObject Rows for the provider contract. This lookup does not return every account, deal or support case associated with that person.

Import help articles

Import public approved Salesforce help content into Knowledge.

Use approved public help articles from Salesforce as Knowledge. The URL-import recipe is separate from CRM authorization and customer records. A content owner must provide public article URLs and approve their audience; do not import private contacts, cases or conversations into a general agent’s Knowledge.

Import and verify an article

Studio

1

Choose the public source

Confirm the article is readable while signed out and contains the approved policy. In your project, open Knowledge base → Add data source → Web page(s) and paste its public URL. Import the page and wait for processing to complete.

2

Inspect and exercise the content

Open the imported article and compare it with the source. Enable Knowledge on the agent and use Run to ask two questions it answers and one it does not. Inspect the retrieved source and configured fallback. Assign an owner and refresh schedule; a listed URL does not establish indexing or continuing synchronization.

Code

Use the bearer credential and test Environment prepared above. Set ARTICLE_URL to the approved public article, then import it:

Inspect the returned document identifier, then list documents with GET /v1/stable/document using the same host, bearer header and query. Match the imported URL in documents[], retain its id and wait for status.type: "SUCCESS"; inspect an ERROR before retrying. PENDING or INITIALIZED is not completion.

Run a Knowledge diagnostic query for a known article question and compare its chunks with the source. Also run a Draft conversation to check the actual answer and fallback; diagnostic retrieval alone is not runtime acceptance. Publish the reviewed Environment and repeat in a fresh customer session.

Keep imported articles current

Reimporting the same URL can change content used by other Environments and Published agents, even when you select a test Environment. Use a dedicated test project for isolated recrawl experiments.

Studio

1

Choose a refresh schedule

Assign a content owner. In Knowledge base, select the URL source and set its Refresh rate to Never, Daily, Weekly or Monthly where available.

2

Replace and verify approved content

For an immediate update, reimport the same approved URL and confirm replacement. Recheck processing, article text and agent answers. For a new URL, import and verify it before deleting the retired source.

3

Remove a retired source

Select the retired Knowledge source and use Delete after checking which answers rely on it.

Code

For an immediate recrawl, repeat POST /v1/stable/document/url with the same approved url, the intended refreshRate, and overwrite=true in the query, alongside the same project and Environment. This deliberately replaces the existing same-URL document; wait for processing and compare content before relying on it. URL content cannot be replaced through the text-document update body.

For a changed URL, create and verify the new URL document first. List/read the old source to confirm its ID and dependencies, then DELETE /v1/stable/document/$RETIRED_DOCUMENT_ID?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT using the same bearer credential. Verify that the retired source is absent and the replacement answers the intended questions. Check other retrieval flows before deletion; it removes this source from the selected Draft’s Knowledge.

Use Importing data sources for the shared refresh controls and URL document creation for the exact reimport contract. This recipe imports a public URL; it does not connect a managed CRM article source or synchronize private CRM data.

Human agent hand-off

Connect Chat messages to a Service Cloud rep through BYOC.

Keep the customer in Voiceflow Chat while a Service Cloud teammate replies through a developer-hosted relay. This connection is separate from the built-in CRM record tools.

Prepare the support workspace

Studio

Ask your Salesforce administrator and integration developer to prepare a tested Service Cloud relay before configuring Voiceflow. Share the Code setup with them, then obtain:

  • The deployed HTTPS Base URL and Auth header name/value.
  • A separate callback Webhook secret of at least 32 characters.
  • An approved Queue ID mapped to the intended support destination.

Have them demonstrate a customer message, a human reply and conversation closure in that destination. The CRM tool connection does not provide this messaging relay.

Code

1

Activate the messaging channel

Have the Salesforce administrator enable Bring Your Own Channel for Messaging in an eligible org. Prepare the reps and Omni-Channel route, create the outbound custom platform event and Conversation Channel Definition, then activate the Messaging channel.

For a self-implementation, use connectedAppType: Customer, omit conversationVendorInfo and configure the OAuth external client app in Messaging Settings. Follow the self-implementation setup.

2

Collect the provider connection values

Obtain these from the configured org:

3

Subscribe to outbound messages

Configure an authenticated Pub/Sub subscription with durable replay/checkpoint storage. A CRM OAuth token or plain HTTP webhook does not provide this delivery path.

1

Prepare and test the relay service

Prepare Node.js 22 or later, HTTPS hosting, durable tenant-scoped storage, a per-conversation queue and an outbox. Download server.mjs, protocol.mjs and test.mjs from the common starter, including its Chatwoot module required by that test bundle. Run node --test test.mjs locally. These tests exercise fixtures, not Salesforce Service Cloud.

2

Configure secrets and callbacks

Implement the provider mapping in the disclosure below and authenticated event ingestion. The shared starter’s mock mode is not a Salesforce Service Cloud adapter.

Store these values outside source control:

  • HANDOFF_TOKEN, EVENT_TOKEN and WEBHOOK_SECRET.
  • VOICEFLOW_PROJECT_ID and VOICEFLOW_WEBHOOK_URL.

Voiceflow receives signed callbacks at https://general-runtime.voiceflow.com/handoff/webhook/custom. Provider notifications go to your service’s own receiver. The service must implement the shared create, customer-message and end operations; see the connection contract.

Connect and route the handoff

Studio

1

Connect the deployed relay

In Agent studio, open More → Integrations → Custom Handoff → Connect. Enter the supplied Base URL, Auth header name, Auth header value and Webhook secret.

Connect the tested relay through Custom Handoff. Photo:
2

Map the customer and destination

Create an escalation Workflow and add a Handoff step. Choose Custom Handoff, map the verified customer identity, name and email, and set the supplied Queue ID. The developer must map this key to the correct Service Cloud destination.

3

Choose context and continuation

Set Handoff context to Full transcript, a Custom summary or None. Populate a custom summary variable before the step. Send only information that support staff may see.

  • Enable Failure path and connect an unavailable-support fallback.
  • Enable Return path and connect the desired continuation. An enabled, unconnected return resumes the parent agent; a disabled return ends the session.
Map the customer and destination, then choose the conversation context. Photo:
4

Make escalation reachable

Attach the Workflow to the agent and describe when it should run. Publish to a test Environment and point a fresh Voiceflow Chat widget session at it before the checks below.

Code

Connect the deployed relay through the direct Custom Handoff configuration API. Use the Voiceflow credential with integration-create and Environment-update access; provider credentials and relay tokens are separate.

1

Connect the relay

POST /v1/stable/integration/custom_handoff?projectID=$PROJECT_ID with integration: "custom_handoff" and credentials containing baseUrl, authHeaderName, authHeaderValue and webhookSecret. Use the relay URL, outbound header and separate callback secret above. This writes the project’s default connection; it does not select a Draft slot. List integrations and check custom_handoff.connected without treating it as delivery acceptance.

2

Create the escalation Workflow

Create a fallback message and an escalation Workflow in the test Environment. Use a Handoff step with config.provider: "custom", trusted endUserId, userEmail, customerName, userLanguage and your mapped queueId; set handoffContext, returnPath and failPath, and connect the failure port. The complete configuration artifact supplies the schema and resource creation order.

3

Attach and compile the Workflow

Read the agent’s current workflows and instructions, append the new escalation without deleting existing entries, and PATCH only the intended fields. Creating a Workflow does not make it reachable. Compile and test before publishing to the test Environment.

4

Implement the customer Chat client

Implement the Chat handoff client: register Socket.IO listeners before connecting; resume the existing user, Environment and sessionKey with client.start; wait for client.started with newSessionRequired: false. Render action.trace handoff events and send customer text with action.send / action.type: "live-agent-handoff". An HTTP streaming response alone does not receive asynchronous human replies.

The shared contracts remain in Developers; this manual owns the Salesforce Service Cloud mapping. Verify the published customer channel before routing real customers.

Verify the complete conversation

With a test customer and a Service Cloud teammate:

  1. Escalate once. Confirm one conversation appears with the correct customer, destination and permitted context.
  2. Send a customer message and a public human reply. Each must arrive once in the other interface.
  3. Add a private note and an automated reply. Neither may appear as a human response. This recipe supports text only; files must be rejected rather than silently dropped.
  4. Send a final human reply and close immediately. The reply must arrive before the configured Return path runs.
  5. Have the integration developer replay an event and test an unknown sender. Confirm that neither produces duplicate or unapproved customer messages.
  6. Have the developer make the test relay unavailable while you verify the Failure path.

A saved connection or a simulated reply is not proof that the published customer channel works.

Code

Implement the Salesforce relay mapping

Translate customer messages, human replies and closure for the configured provider.

Use Authorization: Bearer ACCESS_TOKEN, OrgId, AuthorizationContext (channel-definition developer name), and a UUID RequestId on Interaction Service calls. For create and customer message, POST https://INTERACTION_SERVICE_HOST/api/v1/interactions as multipart/form-data with a json part of content type application/json. Use a current timestamp and real stable message UUID:

Keep identifiers distinct

This recipe uses a conservative mapped end-user client ID of at most 240 characters; do not copy a longer Voiceflow userID directly. Use a nonempty channel-address string of at most 240 characters. Generate the payload from trusted customer/channel mappings and preserve the UUID across retries. Store the returned conversationIdentifier and workItemId (MessagingSession), plus the stable end-user client ID and channel address. Case, Contact, Conversation and MessagingSession IDs have different roles; never substitute one for another. The official inbound schema defines this request; creating a Case or CaseComment does not send a live customer message.

Receive human replies

Subscribe through Salesforce Pub/Sub to the configured outbound custom platform event. Decode it with the registered event schema, then decode its conversation entry. Accept public text only when entryType is Message, the payload is StaticContentMessage/Text, the sender role is Agent or Supervisor and its subject is an approved human rep. Reject Chatbot, System, EndUser, unknown senders, private Note entries and unsupported rich content. Match the active Conversation and session, persist/deduplicate its identifier and queue message.received before advancing the replay checkpoint. See outbound event definitions.

Close and resume safely

For SessionStatusChanged with sessionStatus: "Ended", reconcile and deliver prior public messages for the active session before emitting one conversation.ended. A ParticipantChanged transfer alone does not end it. Serialize reply/closure handling and persist recovery state; a Pub/Sub reconnect must not replay duplicate customer messages.

Implement end using POST /api/v1/messagingSession at the recorded Interaction Service host with the same headers, JSON content type and channelAddressIdentifier, endUserClientId, conversationIdentifier, sessionId, operation: "End", operationBy: "System". Use API v65.0 or later for End, inspect success and ErrorReason, and reconcile the terminal event exactly once. See Messaging Session API. Closing a Case does not close the messaging session.

Serialize work per active conversation and keep tenant-scoped mappings until delivery completes. Persist messages before acknowledging the provider, use an outbox and bounded retries, and reconcile pending replies before closure. Deduplication alone does not preserve message order. After an ambiguous create timeout, reconcile the existing conversation instead of creating another session.

Replies or closure are missing

Trace the active session and event receiver before reconnecting accounts.

Studio

  • Check that the test widget uses the intended Published Environment and that the Handoff step has the approved Queue ID and Return/Failure paths.
  • Record the test time, conversation reference and which message or return was missing. Give that evidence to the integration developer.
  • Ask the developer to trace provider delivery and relay callbacks before reconnecting the account. Use Handoff troubleshooting for shared runtime recovery.

Code

Check provider delivery/subscription logs, tenant and conversation/session mapping, human-sender filtering, callback signature and the customer client’s resumed session in that order. A 401 requires credential/signature repair; rate limits require bounded backoff. Keep provider and Voiceflow callback secrets distinct. If the provider accepted a write but the response was lost, reconcile it before retrying. Use Handoff troubleshooting for shared runtime recovery.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.