Build with

Overview

Connect Voiceflow to Pipedrive with API tools to capture confirmed enquiries, use authorized customer records and create assigned follow-up work. The tools call your CRM directly; credentials are stored in Voiceflow Secrets.

Studio

Use an editable test project, a CRM administrator and an application developer. The developer prepares trusted customer mappings for protected records and confirmed JSON payloads; the steps below name the values to obtain.

Code

Use Voiceflow APIs or CLI to create, execute and attach the same API tools. Your backend owns CRM authorization, customer identity and JSON construction. Test with records you can inspect before attaching tools to a customer-facing agent.

Connecting Pipedrive

Prepare direct API access and a protected customer lookup.

For a private account integration, obtain the user’s API token from Personal preferences → API in Pipedrive. The token belongs to one user and company and has that user’s data access. The administrator must approve person/Lead creation, person reads/updates and activity creation, plus the intended owner. Store the token as a restricted Voiceflow Secret and send it in x-api-token, not in the request URL. See Pipedrive authentication.

Use your exact company origin, such as https://YOUR_COMPANY.pipedrive.com. This recipe uses v2 Persons and Activities and the still-supported v1 Leads endpoint. A distributed application needs its own OAuth flow; this private-token recipe does not implement a Marketplace app. Rotating the user’s token invalidates other integrations sharing it.

For a public capture-only agent, prepare the credential and capture payload variable, then continue to Capturing sales enquiries. Skip the customer lookup and Contact mapping. The lookup steps below are for the authenticated customer agent.

Prepare the lookup and credentials

Studio

1

Obtain the account and application setup

Ask the CRM administrator and application developer to complete the authorization above. Obtain the fixed CRM origin, restricted Secret pipedrive_api_token, the approved owner ID and a test application URL. For a customer lookup, also obtain an authorized test login and Contact ID. Obtain the private token through your approved secret-sharing process, then create pipedrive_api_token in More → Secrets. Creating its default also writes Main’s Published value; use a dedicated test project.

2

Create the protected variables

Open Agent studio, select the test project and intended Environment, then open More → Variables. Create pipedrive_contact_id, pipedrive_capture_payload, pipedrive_phone_payload and pipedrive_followup_payload with empty defaults. Also create pipedrive_lead_payload for the second capture write and the output variables pipedrive_created_person_id and pipedrive_person_success with empty defaults. For the authenticated agent, have the developer supply the authorized mapping and prepared payloads on every turn/resume while retaining runtime credentials on the backend. The public capture-only agent supplies confirmed capture payloads without a Contact mapping. Do not accept browser overrides or ask the model to choose a record/owner.

3

Configure the customer lookup

In Agent → Global tools → + → API, create Find customer in Pipedrive. Select GET and use https://example.pipedrive.com/api/v2/persons/{contact_id}, replacing only the example origin with the approved one. Add x-api-token: {token} and Accept: application/json.

Configure the Pipedrive request and bind its protected inputs before testing. Photo:
4

Bind credential and customer identity

Save the request and click the attached tool in Global tools. Under Input variables, click the token row, then select pipedrive_api_token through Default value → Secrets. Open contact_id and select pipedrive_contact_id through Default value → Variables. Click outside to save. Enabling a switch does not bind the input. Reopen each row to verify the selected reference.

5

Test the actual record

Open the saved API tool’s editor and click Run. In its test-input panel, choose the token Secret and enter the developer-approved test contact_id, then click Run again. These test values are separate from attached runtime defaults; the proxy does not populate this panel. Inspect data.id in the provider body and compare it with the intended CRM record. Use Capture response only for approved fields; a saved request or Secret does not verify record access.

Code

Use the administrator-approved private-account token for this recipe. Keep the credential in the restricted pipedrive_api_token Secret. No OAuth renewal worker is needed for this API-token method. To stop access, disable the relevant tool and revoke/rotate the provider token deliberately; coordinate every other integration sharing that token.

Use a Voiceflow bearer credential with the required project/Environment permissions. Keep it server-side. Set VF_TOKEN, PROJECT_ID, ENVIRONMENT and CRM_CONTACT_ID to your test resources; install the CLI if choosing CLI. CRM_CONTACT_ID is the authorized Contact/Person ID, not a new Lead ID.

Download and extract the direct CRM example bundle. It contains the tool definitions, payload builders, renewal worker and fixture tests. Run node --test direct-requests.test.mjs on Node.js 22 or later; these are local fixtures, not authenticated provider tests. Set CRM_API_ORIGIN to your approved CRM origin, then prepare the definitions locally:

Each definition fixes the provider host, method and fields. Write definitions use raw JSON body {payload}; the backend builder supplies that entire serialized value. No provider credential is embedded in these files.

Create pipedrive_api_token as a restricted Secret without defaultValue through POST /v2/stable/secret?projectID=$PROJECT_ID with body {"name":"pipedrive_api_token","visibility":"restricted"} and the Voiceflow bearer header, or:

Save secret.id as SECRET_ID. The placeholder has no value. Set its explicit test Draft target using Secret value configuration. Use the private Pipedrive API token as the value. Supply environmentAlias and versionVariant; omitting the target can write Main’s Published value.

Create the identity and payload variables before attachment. The API is POST /v2/stable/variable with the same project/Environment query and body {"name":"pipedrive_contact_id","defaultValue":null,"color":"#515A63"}; repeat with each payload variable name. Through CLI:

Repeat for pipedrive_capture_payload, pipedrive_phone_payload, pipedrive_followup_payload, pipedrive_lead_payload, pipedrive_created_person_id and pipedrive_person_success with empty defaults. Keep both returned output-variable IDs for the Person-result captures. For protected customer records, your authenticated proxy must use trustedDirectTurn on every turn and resume, strip browser variables/state and retain the runtime session key. An initial launch mapping alone is insufficient.

Save each returned apiTool.id separately. Set API_TOOL_ID to the lookup’s ID for its test, and retain it as LOOKUP_TOOL_ID for later readback. List its inputs with GET /v2/stable/api-tool-variable?apiToolID=$API_TOOL_ID&projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT, or vf api-tool variable list --api-tool-id "$API_TOOL_ID" --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --output-format json. Match variables[].name to id for attachment.

Save the lookup inputs:

Require success: true, error: null, truncated: false, provider output.status: 200 and the expected output.body.data.id. Standalone execution uses the selected Environment’s Draft; it does not attach or publish the tool.

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.

Studio

1

Open the attached customer lookup

In Agent → Global tools, open Find customer in Pipedrive. Keep the lookup on the authenticated customer agent. The separate public capture-only agent gets only its create tools; a saved API request in Tools alone is not an agent attachment.

2

Set the Trigger and provided inputs

Set Trigger to “Find the signed-in customer’s contact details when they ask about their profile.” Keep token bound to the Secret and contact_id to pipedrive_contact_id. For writes, bind the complete payload from the backend variable named in that capability. The agent collects the customer’s request, not credentials, CRM IDs or raw JSON.

3

Test the question through your application

Use the authenticated test application and ask “What phone number do you have for me?” Inspect the tool call and the approved returned field before the agent answers. Repeat without a permitted mapping: the backend must stop the private read and the agent must use general help. API-editor Run tests the request separately.

Code

Attach the saved lookup to the authenticated agent with target: {"global":true}; use {"playbookID":"YOUR_PLAYBOOK_ID"} to restrict a read to one Playbook. Set the attachment’s description to “Find the signed-in customer’s contact details when they ask about their profile,” keeping token and contact_id as provided defaults. Each write uses its own saved tool ID, input IDs, description and backend-prepared payload binding. The complete attachment commands are in Attach tested tools to an agent below.

Compile the Draft, then send “What phone number do you have for me?” through the authenticated application. Inspect the actual tool call, current result and answer. Test a missing/foreign mapping and a later-turn override. For a first enquiry, use trustedEnquiryTurn with a separate capture-only agent; protected customer tools use trustedDirectTurn on every turn/resume. A Trigger describes selection; the backend enforces access and confirmation.

For API-tool Capture response, use data.id for the Person, Lead or activity, each in a separate output variable. The path starts in the provider JSON, without the standalone output.body prefix. Create any output variables with empty defaults using the variable setup above; keep returned IDs separate from pipedrive_contact_id.

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 tested tools to an agent

Bind protected inputs, compile and test a conversation after standalone execution.

Save this attachment as attachment.json, replacing the resource and input IDs with those returned above:

For a write, add the payload input using its returned input ID and defaultValue: "{pipedrive_capture_payload}", "{pipedrive_phone_payload}" or "{pipedrive_followup_payload}" for that tool; use "{pipedrive_lead_payload}" for Pipedrive Lead creation. Include contact_id only on tools whose schema declares it. Defaults are protected server-supplied values; do not leave IDs, credentials or full JSON payloads to model selection.

POST the attachment to /v2/stable/tool with the project/Environment query and Voiceflow bearer header, or:

Resolve unresolvedReferences. Compile, exercise a conversation and inspect the resulting CRM record before publishing the reviewed Environment. Compilation does not publish. Verify that your proxy resets protected variables on later turns, including resumes, and that unprepared payloads cannot execute a write.

Rotate or stop account access

Remove credentials deliberately without deleting CRM records.

Disable affected tools before revoking access. Coordinate token rotation with every integration sharing that user token and update the intended Secret targets. Clear obsolete Secret values only after checking other tools and versions. Revoking authorization does not delete records already created.

Capturing sales enquiries

Save confirmed details for your sales team.

A first enquiry does not require an existing CRM Contact. For public prospects, use a separate capture-only agent with just these create tools and the backend’s trustedEnquiryTurn boundary. Keep customer lookup, update and linked follow-up tools on the authenticated agent.

Apply your qualification policy, then ask the customer to confirm the details and follow-up request. The qualification Guide explains that broader journey; a CRM write does not qualify the customer by itself.

Capture uses two deliberate writes: Create person saves name, emails and owner_id; Create lead saves a title, the returned numeric person_id and approved owner_id. Keep the Person ID even if Lead creation fails. Reuse an already-authorized Person when one exists; this recipe does not discover identity from email. Require provider success: true on both results. See Persons and Leads.

In the conversation: Set the capture tool’s Trigger to recording a confirmed sales enquiry when pipedrive_capture_payload is ready. Let the agent gather the enquiry details; the backend validates confirmation, selects the approved owner and supplies the complete payload. Retain the Person ID on the backend, prepare the linked Lead payload for a later conversation turn, then call the Lead tool; acknowledge completion only after both writes succeed. Test Person success followed by Lead failure: retain the Person and reconcile the Lead without creating a second Person or claiming a completed enquiry.

Save the confirmed enquiry

Studio

1

Prepare the reviewed request

Have your developer use capturePayload in the request builders to populate pipedrive_capture_payload from confirmed, validated fields and the approved owner. Require a recorded confirmation, not a model assertion.

2

Add the capture request

Create an API tool with POST https://example.pipedrive.com/api/v2/persons and the credential header from setup. Add Content-Type: application/json. Use Body → Raw → JSON with the complete input {payload}; do not interpolate customer text into a quoted JSON template.

Configure the Pipedrive request and bind its protected inputs before testing. Photo:
3

Bind and test the write

In the attached tool’s Input variables, bind token → Default value → Secrets → pipedrive_api_token. Open payload and bind Default value → Variables → pipedrive_capture_payload. Click outside and reopen to check. Open the API tool editor’s Run panel. Select the token Secret and paste the developer-prepared complete JSON string in payload. Click Run and inspect the saved Person. Retain its ID; do not announce success from HTTP status alone.

Code

Select .capture from tools.json into tool.json, then create it and retain its new apiTool.id as CAPTURE_TOOL_ID. Set API_TOOL_ID to that ID.

Use the request builders on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as prepare.mjs and run node prepare.mjs to write inputs.json:

The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied fixture tests exercise this boundary.

Require the Voiceflow execution checks from setup and the provider result described above. Keep output.body.data.id with the request.

For conversation use, create pipedrive_created_person_id and pipedrive_person_success as above. Add "captureResponse":{"person-result":{"path":"data.id","variableOrEntityID":"RETURNED_PERSON_RESULT_VARIABLE_ID"},"person-success":{"path":"success","variableOrEntityID":"RETURNED_SUCCESS_VARIABLE_ID"}} to the Person attachment. Both turn helpers reset the ID and success flag before forwarding. After the call, read the same server-owned conversation’s state with Get conversation state:

USER_ID is the application’s retained conversation identity, not browser input. The management route is GET /v1/stable/conversation-state/USER_ID with projectID, environmentAlias and version query fields; the credential needs conversation-state read permission. Use the actual Draft/Published version.

Parse the management response as stateResponse, then call pipedrivePersonResult(stateResponse.state). It requires pipedrive_person_success === true and a positive safe-integer Person ID, then converts the ID to the decimal string expected by pipedriveLeadPayload. Retain it with this enquiry server-side, prepare pipedrive_lead_payload, and supply that payload through trustedEnquiryTurn on a later turn. The first call does not automatically populate or invoke the second tool.

Keep the first write’s Person ID. Create a separate API tool using POST /api/v1/leads, the same header and JSON body {payload}. Bind its token and pipedrive_lead_payload through the same Default value controls. Have the developer construct that payload with pipedriveLeadPayload from the confirmed enquiry, saved numeric Person ID and approved owner.

Studio

1

Retain the current Person result

In the Person tool’s Capture response, map data.id to pipedrive_created_person_id and success to pipedrive_person_success. The turn helper clears the ID and sets success to false before each attempt. After the call, have the backend read that conversation’s state and require a fresh true flag and valid numeric Person ID.

2

Prepare the linked Lead

Have the developer use pipedriveLeadPayload to populate pipedrive_lead_payload from that saved Person ID, the confirmed enquiry and approved owner. Add a second API tool: POST https://example.pipedrive.com/api/v1/leads, the token header, JSON content type and raw {payload}. Bind its payload to pipedrive_lead_payload.

3

Continue the enquiry and check both records

Set the Lead tool’s Trigger to the pending enquiry when its payload is ready. The backend supplies that value on a later turn; the Person tool does not invoke it automatically. Retain the Lead UUID separately and inspect its Person link. A failed Lead must preserve the existing Person for reconciliation.

Code

Select .lead from tools.json, create the separate tool and set API_TOOL_ID to its new ID. Replace 1042 with the actual Person ID from the first result:

Use the request builders on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as prepare.mjs and run node prepare.mjs to write inputs.json:

The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied fixture tests exercise this boundary.

Require output.body.success: true and retain the Lead UUID in output.body.data.id. This UUID is a different resource from the Person ID.

Inspect the saved CRM record and its owner before confirming completion. A write timeout is ambiguous: reconcile the existing record and execution evidence before retrying. Creation is not an idempotent upsert. It does not send a customer email, book a meeting or create a qualified opportunity.

Recognizing returning customers

Use only the customer record authorized by your application.

Customer identity comes from your application sign-in and server-side CRM mapping. A typed email, a CRM ID suggested in chat or provider account authorization is not customer authentication. Use the tested lookup after the proxy has reset the protected mapping for this turn.

Require provider success: true and the expected numeric data.id. Pipedrive v2 does not support the old field-selector URL syntax. The direct Person response can contain custom and other fields: use this tool only when the complete returned record is approved for the agent. If fields require redaction, put that filtering on your backend before exposing the result; Capture response alone does not redact the original tool output. See request behavior.

In the conversation: Set Find customer in Pipedrive to run when the signed-in customer asks about their saved profile. Provide pipedrive_contact_id from the authenticated application and the token from Secrets; neither is collected by the agent. Answer from approved fields in the current matching record; failed or empty reads use general help. Test “What phone number do you have for me?” plus a missing mapping and a later-turn override; no private data may escape the permitted record.

Use the authorized record

Studio

1

Check the supplied mapping

Have the application developer demonstrate that pipedrive_contact_id is rebuilt from the authenticated server-side map on every turn/resume and client runtime credentials stay on that backend. The lookup input must remain bound to that variable.

2

Run the customer question

Use the provided authenticated test application with an authorized test customer, then ask for another customer’s record and attempt a later-turn variable override. Neither may expose it. Test a missing mapping and fall back to general help.

3

Use only the approved result

Inspect the actual response before configuring Capture response. Verify data.id and the fields approved for this customer. Do not turn a failed lookup into automatic record creation.

Code

Set API_TOOL_ID to the saved LOOKUP_TOOL_ID. Authorize the customer and record again, prepare inputs.json with the server-mapped ID as in setup, then execute that lookup. Check the provider ID and permitted fields before returning an answer.

trustedDirectTurn discards browser variables/state and resets the Contact ID and every payload variable; integrate it behind your application authentication on all supported runtime actions. Its allowlist covers launch/text only. Additional actions require their own audited boundary. Missing mappings must fail before the tool executes; never use a shared customer ID as a default.

Updating customer details

Save a confirmed phone change and verify persistence.

Confirm the requested number and authorize the same customer before changing it. This recipe accepts international phone strings matching ^\+[1-9][0-9]{7,14}$; it does not accept free-form text or additional fields.

Use PATCH with a phones array. The helper requires the freshly retrieved phones and preserves secondary numbers/labels while replacing the primary number; it rejects multiple primaries. Review the complete submitted list before writing. The read/update pair is not atomic: if another application changes phone data concurrently, reconcile before retrying. Require provider success: true, then read the same Person again and compare the full phones list.

In the conversation: Call the phone-update tool only after the backend supplies a confirmed pipedrive_phone_payload, then run the lookup again. Let the agent collect the proposed number; the application owns validation, customer identity and the complete write payload. Use the current readback to confirm the same record changed; reconcile uncertain writes before retry. Test an unconfirmed change and a confirmed number; the first must not write, and the second must preserve the authorized record.

Save and read back the change

Studio

1

Prepare the permitted change

Have the developer populate pipedrive_phone_payload using phonePayload with the authorized Contact/Person ID and confirmed number. Read the current phones first and supply that complete list to the helper.

2

Configure the update tool

Create an API tool with PATCH https://example.pipedrive.com/api/v2/persons/{contact_id}, the setup credential header and Content-Type: application/json. Set Body → Raw → JSON to {payload}. Bind token to the Secret, contact_id to the protected identity variable and payload to pipedrive_phone_payload using each row’s Default value.

3

Verify persistence

In the API editor’s Run test panel, choose the token Secret, enter the approved contact_id and paste the complete prepared payload. Run the update, inspect provider errors and repeat the lookup test for that same ID. Then exercise the change through the provided authenticated application and inspect Transcripts. Compare phones with the confirmed change and open the CRM record. A failed read does not prove the write failed.

Code

Select .phone from tools.json, create the new API tool and retain its ID as PHONE_TOOL_ID. Set API_TOOL_ID to it. Use the actual mapped ID in both the prepared payload and execution input:

Use the request builders on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as prepare.mjs and run node prepare.mjs to write inputs.json:

The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied fixture tests exercise this boundary.

Check the provider result, then set API_TOOL_ID back to LOOKUP_TOOL_ID, prepare lookup inputs and re-read that same record. Compare output.body.data.id and the saved phone field. On a timeout, reconcile this read before choosing whether to retry the write.

Creating assigned follow-up

Link the requested work to the customer and approved owner.

Create a activity only after the customer has requested follow-up. The administrator supplies an active permitted owner ID and verifies assignment permissions. This is a recorded work item, not a live human conversation or a guarantee that someone has contacted the customer.

Create a v2 activity with subject, type: "task", approved numeric owner_id, due_date and done: false. Link the customer with participants: [{person_id: ID, primary: true}]; the v2 create body does not use a top-level person_id. Confirm that task is an enabled activity type and agree the calendar due date; this recipe leaves the due time unset. Inspect provider success: true and data.id, then check the actual owner, participant and due date. See Activities.

In the conversation: Set the follow-up tool’s Trigger to a requested follow-up when pipedrive_followup_payload is ready. Let the agent collect the subject and agreed date; the backend supplies the approved customer link, owner and confirmed payload. Use the current work-item ID and saved owner/date before acknowledging the request; a saved task is not a delivered message. Test a confirmed follow-up and a rejected write; only the saved, correctly linked work may be reported as recorded.

Record the assigned work

Studio

1

Prepare the linked request

Have the developer call followUpPayload with the authorized customer record, approved owner, confirmed subject and agreed due date. Obtain pipedrive_followup_payload; the customer/model must not choose a CRM owner ID.

2

Configure and bind the follow-up tool

Create an API tool with POST https://example.pipedrive.com/api/v2/activities, the setup credential header and Content-Type: application/json. Set Body → Raw → JSON to {payload}. Bind the token Secret and the payload row to pipedrive_followup_payload through Default value.

3

Check the assigned record

In the API editor’s Run panel, select the token Secret and paste the complete confirmed payload. Run once and inspect the returned activity ID and open that record in the CRM. Confirm its linked customer, intended owner, due date and request details; retain the customer-to-work-item mapping.

Code

Select .followup from tools.json, create the tool and retain its ID as FOLLOWUP_TOOL_ID. Set API_TOOL_ID to it, then prepare:

Use the request builders on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as prepare.mjs and run node prepare.mjs to write inputs.json:

The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied fixture tests exercise this boundary.

Require the Voiceflow execution checks and the provider result described above. Retain output.body.data.id and inspect the corresponding CRM record’s customer/owner/date before reporting completion. Retry only after reconciling an uncertain create; an authentication failure and a lost successful response need different handling.

Diagnose a rejected or uncertain request

Separate credential failures, record access and writes whose outcome is unknown.
  • 401 / invalid token: check the Secret target and whether the user token was revoked or rotated.
  • 403 / permission failure: have the administrator inspect object, field, record and assignment access in the selected CRM account. A token or successful read does not establish write access.
  • Validation or duplicate error: inspect the provider body and administrator-required fields. Do not treat a Voiceflow HTTP 200 as provider success.
  • 429: respect the provider’s retry/reset information and review API usage; do not loop writes.
  • Timeout or lost response: inspect the CRM and retained request/record IDs before retrying. The write may already have completed.

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