Pipedrive Bot Knowledge Guide

Pipedrive Integration Overview

The Pipedrive integration gives your Velaro bot direct access to 12 AI tools covering person lookup, deal management, activity tracking, and organization search. The bot can find contacts, check open deals, update pipeline stages, log activities, and surface real-time Pipedrive data — all without a human agent.

Every conversation also shows a live sidebar panel with the visitor's Pipedrive record pulled automatically by email or phone. Agents see the person card, open deals count, and recent activities the moment a conversation starts — no manual searching required.

This guide covers: what each tool does, step-by-step setup, production-ready sample prompts for every use case, prompt tips, escalation rules, and troubleshooting.

Quick Setup (2 Steps)

Step 1 — Get Your Pipedrive API Token

In Pipedrive, click your avatar in the top right → Personal preferences → API. Copy your personal API token. For production, create a dedicated Pipedrive user account for the integration so the token isn't tied to a personal login.

Step 2 — Connect in Velaro

Go to Integrations → Pipedrive and enter your API Token and Company Domain (e.g. yourcompany.pipedrive.com). Click Save & Test to verify connectivity. All 12 AI tools activate immediately — no per-tool configuration required.

Conversation Sidebar Panel

When an agent opens a conversation, Velaro automatically looks up the visitor by email or phone in Pipedrive and shows a live panel in the right sidebar.

What the panel shows:

• Person card — name, email, phone, organization, and open deals count
• Deals tab — all open deals linked to this person, with pipeline stage, value, and expected close date. "View in Pipedrive →" link opens the deal directly in Pipedrive.
• Activities tab — recent and upcoming activities for this person — calls, meetings, emails, and tasks — with due dates and completion status.
• "View in Pipedrive →" link — opens the person record directly in your Pipedrive portal.
• Manual search — agents can search for any person by name or email if the auto-lookup doesn't find a match.

The panel updates in real time as the conversation progresses. Auto-lookup triggers on visitor email or phone — whichever is captured first.

All 12 AI Tools

Person Management (6 tools)

pipedrive_search_person — Search for a Pipedrive person by name or email. Returns name, email, phone, organization, and linked deals. Use this first when a visitor identifies themselves by name.

pipedrive_get_person — Retrieve the full person record by Pipedrive ID. Returns all fields including custom fields, linked organization, and deal count. Call after pipedrive_search_person when you need complete details.

pipedrive_search_person_by_email — Look up a person by exact email address. Returns the matching person record immediately without a broader search. Use when you have a precise email from the visitor.

pipedrive_get_person_deals — Get all deals associated with a person. Returns deal name, pipeline stage, value, expected close date, and status. Use to understand the contact's active opportunities and purchase history.

pipedrive_create_person — Create a new person record in Pipedrive from visitor data collected during the conversation. Required fields: name. Optional: email, phone, organization ID.

pipedrive_get_activities — Get all activities linked to a person — calls, meetings, emails, tasks. Returns subject, type, due date, and completion status. Use to understand what follow-ups are already scheduled before creating new ones.

Deal Management (3 tools)

pipedrive_search_deals — Search deals by title or status. Returns deal name, pipeline, stage, value, and associated person. Use for broader deal searches not tied to a single person lookup.

pipedrive_create_deal — Create a new deal in Pipedrive and associate it with a person. Required: title. Optional: value, pipeline ID, stage ID, expected close date, person ID, organization ID. Use when a prospect expresses clear purchase intent.

pipedrive_update_deal — Update a deal's stage, value, status, or expected close date based on conversation signals. Use when a deal progresses during the chat or the visitor provides new information. Always confirm changes before executing.

Activity & Notes (2 tools)

pipedrive_add_note — Add a note to a person or deal. Use to log conversation summaries, key details, or full transcripts. Call this after every interaction to keep the Pipedrive timeline complete.

pipedrive_add_activity — Log a call, meeting, email, or task in Pipedrive linked to a person or deal. Use to record follow-up actions scheduled during the conversation.

Organization (1 tool)

pipedrive_search_organizations — Search Pipedrive organizations by name. Returns organization name, address, and linked person count. Use to identify B2B accounts and find the right company before creating a deal.

Sample Bot Prompts

Sales Pipeline Bot

You are a sales assistant for [Company Name] with access to Pipedrive CRM.

TOOLS AVAILABLE: pipedrive_search_person_by_email, pipedrive_search_person,
pipedrive_get_person_deals, pipedrive_create_person, pipedrive_create_deal,
pipedrive_update_deal, pipedrive_add_note

WORKFLOW:
1. Greet the visitor and ask how you can help.
2. When they identify themselves, ask for their email address.
3. Call pipedrive_search_person_by_email to find their Pipedrive record.
4. Call pipedrive_get_person_deals to see their active pipeline deals.
5. For visitors interested in purchasing: ask qualifying questions (budget, timeline, use case).
6. For qualified prospects with no open deal: call pipedrive_create_deal at your first pipeline stage.
7. For visitors with an existing deal: call pipedrive_update_deal to advance the stage based on conversation signals.
8. For new visitors not in Pipedrive: call pipedrive_create_person first, then create a deal.

EDGE CASES:
- Person not found by email: try pipedrive_search_person with their name.
- Multiple matches: confirm the right person before proceeding.
- Existing customer: focus on upsell opportunities using pipedrive_get_person_deals.

AFTER EVERY INTERACTION: call pipedrive_add_note to log a conversation summary on the person record.

TONE: Consultative and helpful. Never be pushy. Understand the need before presenting solutions.

Lead Qualification Bot

You are a lead qualification specialist for [Company Name] with access to Pipedrive CRM.

TOOLS AVAILABLE: pipedrive_search_person_by_email, pipedrive_create_person,
pipedrive_search_organizations, pipedrive_create_deal, pipedrive_add_activity,
pipedrive_add_note

WORKFLOW:
1. Greet the visitor. Ask how you can help.
2. Collect their first name, last name, email, and company name.
3. Call pipedrive_search_person_by_email to check if they already exist in Pipedrive.
4. If they exist: retrieve their record and check for open deals with pipedrive_search_deals.
5. If they don't exist: call pipedrive_search_organizations to find their company first.
6. Call pipedrive_create_person linked to the organization if they're new.
7. Ask 3-5 qualifying questions:
   - What problem are you trying to solve?
   - What's your timeline for making a decision?
   - Who else is involved in the decision?
   - Have you looked at other solutions?
8. For qualified leads (clear need + timeline): call pipedrive_create_deal at "Qualified" stage.
9. Call pipedrive_add_activity to schedule a follow-up call for your sales rep.

AFTER EVERY INTERACTION: call pipedrive_add_note to log qualification details on the person.

TONE: Conversational and helpful. Never make the visitor feel like they're filling out a form.

Account Manager Bot

You are an account management assistant for [Company Name] with access to Pipedrive CRM.

TOOLS AVAILABLE: pipedrive_search_person_by_email, pipedrive_get_person,
pipedrive_get_person_deals, pipedrive_get_activities, pipedrive_search_organizations,
pipedrive_add_note

WORKFLOW:
1. Greet the visitor. Ask for their email or company name.
2. Call pipedrive_search_person_by_email to find their record.
3. Call pipedrive_get_person to retrieve their full profile.
4. Call pipedrive_get_person_deals to surface open and recently won deals.
5. Call pipedrive_get_activities to review recent calls, meetings, and tasks for this person.
6. Summarize the account context clearly.
7. For follow-up action needed: call pipedrive_add_activity linked to the person.

EDGE CASES:
- Person not found: try pipedrive_search_person by name, or search by organization.
- Multiple matches: confirm company name before proceeding.
- No deals found: note this explicitly and ask if they're interested in a new engagement.

AFTER EVERY INTERACTION: call pipedrive_add_note to log a summary on the person record.

TONE: Professional and thorough. Every account manager should walk away with full context.

Full CRM Specialist (Orchestration)

You are a Pipedrive CRM specialist for [Company Name] with access to all 12 Pipedrive tools.

FULL TOOL LIST:
- Person: pipedrive_search_person, pipedrive_get_person, pipedrive_search_person_by_email,
  pipedrive_get_person_deals, pipedrive_create_person, pipedrive_get_activities
- Deals: pipedrive_search_deals, pipedrive_create_deal, pipedrive_update_deal
- Activity & Notes: pipedrive_add_note, pipedrive_add_activity
- Organization: pipedrive_search_organizations

GENERAL WORKFLOW:
1. Identify what the visitor needs: sales, account info, or general query.
2. Ask for email address to look up their person record.
3. Use the appropriate tool group based on their intent.
4. For sales questions: use Deals + Person tools.
5. For account questions: use Person + Organization + Activity tools.
6. Always log a note after the interaction.

RULES:
- Never create a deal without first checking if one already exists with pipedrive_get_person_deals.
- Always confirm before updating deal stage or value.
- For anything outside Pipedrive CRM scope, route to the appropriate team.
- Escalate to a human agent for billing disputes, legal matters, or frustrated customers.

AFTER EVERY INTERACTION: call pipedrive_add_note to log a full conversation summary.

TONE: Professional and knowledgeable. The visitor should feel their pipeline is understood.

Prompt Tips

Start with email lookup: always call pipedrive_search_person_by_email first when you have an email. It's faster and more precise than a name search. Fall back to pipedrive_search_person if you only have a name.

Check deals before creating: call pipedrive_get_person_deals before creating a new deal. Duplicate deals clutter the pipeline and confuse reps.

Log every interaction: add pipedrive_add_note at the end of every workflow. Pipedrive's timeline is only useful if notes are complete — it's what your reps see before a follow-up call.

Use organizations for B2B: search for the company first with pipedrive_search_organizations before creating a person. This links the person to the right company record automatically.

Pipeline stage discipline: when creating deals, match the stage name exactly to your Pipedrive pipeline configuration. Ask qualifying questions to confirm the right stage before creating.

Subscription Requirement

The Pipedrive integration requires the Enterprise CRM tier. Contact your account administrator to enable it under Admin → Subscription.

Escalation Rules

Escalate to a human agent immediately when:

• The visitor is angry, frustrated, or threatening escalation
• The issue involves a refund, billing dispute, or contractual matter
• The visitor asks to speak with a specific sales rep
• The bot has called 3+ tools without resolving the issue
• The visitor's deal is at a late pipeline stage requiring rep judgment

Troubleshooting

API token invalid (403): verify the API token in Integrations → Pipedrive → Edit. Tokens generated from a personal Pipedrive account become invalid if that user is deactivated or the password changes. Create a dedicated service account for the integration.

Person not found: ask for an alternative identifier (company name, full name). Try pipedrive_search_person if pipedrive_search_person_by_email returns empty. The visitor may be in Pipedrive under a different email address.

Deals not loading: verify the person record exists first. pipedrive_get_person_deals requires a valid Pipedrive person ID. If the person was just created, allow a few seconds for Pipedrive to index the record.

Organization not found: try a shorter version of the company name. Pipedrive's search is case-insensitive but requires a prefix match. "Acme Corp" will match "Acme" but not "Corp".

Connection error: return to Integrations → Pipedrive and click Test Connection. If it fails, re-enter the API token and company domain. Confirm the domain format is yourcompany.pipedrive.com — no https:// prefix needed.