VICIdial and HubSpot Integration Guide

Integration Goals and Use Cases

Marketing fills HubSpot with form submissions and ad leads. Inside sales dials those records from VICIdial because the vicidial dialer still outperforms browser-based dialers on volume, recycle control, and supervisor tools. Without integration, HubSpot contact timelines miss calls and VICIdial agents lack enrichment data that marketing paid to collect.

Typical goals include: automatic push of new HubSpot contacts into a VICIdial list; logging call dispositions back to HubSpot as engagements or calls; updating lifecycle stage when VICIdial reports a qualified disposition; and stopping outreach when HubSpot records unsubscribe or book a meeting.

HubSpot Operations Hub and custom workflows add power but also complexity. Start with one campaign and one list before enterprise-wide automation. Confirm outbound campaign basics and lead import hygiene on the dialer side first.

Architecture Overview

There is no official native VICIdial-HubSpot plugin in core VICIdial. Production integrations use one or more of these layers:

• Scheduled ETL scripts using HubSpot CRM API and VICIdial NON-AGENT API.
• Middleware platforms such as Make, Zapier, or Tray.io for no-code triggers.
• Custom Node or Python service hosted beside your vicidial server for bidirectional sync.
• HubSpot calling extensions only if you replace VICIdial agent UI, uncommon for predictive floors.

Predictive floors should keep agents in VICIdial for dialing and push results to HubSpot asynchronously. Trying to dial from HubSpot while running VICIdial predictive in parallel duplicates effort and breaks dial level management.

Prerequisites

1. HubSpot account with CRM API access and private app token or OAuth app credentials.
2. Scopes: crm.objects.contacts read/write, crm.objects.calls write, crm.schemas.contacts read as needed.
3. VICIdial API admin user with lead upload and log read permissions.
4. HTTPS endpoint reachable from HubSpot if using webhooks; static IP for allowlists on vicidial hosting firewalls.
5. Mapping sheet: HubSpot contact id to VICIdial vendor_lead_code.
6. Disposition map: VICIdial status to HubSpot call disposition property values.
7. Sandbox contacts for test cycles before touching live marketing lists.

Document API rate limits. HubSpot enforces daily and burst limits by tier. Large recycle-heavy campaigns can spike disposition writes; batch where possible.

HubSpot to VICIdial Lead Flow

Identifying Callable Contacts

Use HubSpot lists or workflow-triggered webhooks when contacts meet criteria: lifecycle stage MQL, lead score threshold, owner assigned, phone present, and marketing consent true. Export phone, firstname, lastname, timezone, hubspot_contact_id, and owner email if you route callbacks.

Transform and Load

1. Query HubSpot search API for contacts modified since last sync timestamp.
2. Normalize phone to digits; reject invalid lengths before API waste.
3. POST add_lead to VICIdial non_agent_api.php with list_id and vendor_lead_code equal to HubSpot id.
4. Set source_id field for secondary matching if vendor_lead_code is occupied.
5. On success, update HubSpot custom property vicidial_in_dialer to true.
6. Add note on contact with VICIdial list name and import batch for audit.

Schedule sync every five to fifteen minutes for inside sales SLAs. Marketing blast lists may tolerate hourly batch. Align with lead recycling so HubSpot suppression and VICIdial call caps stay coherent.

VICIdial to HubSpot Call Logging

After each call, integration service reads vicidial_agent_log entries newer than last cursor. For each row, fetch contact by vendor_lead_code via HubSpot CRM API and create a call engagement.

1. Map talk_sec to duration; set hs_call_direction OUTBOUND.
2. Map disposition code to hs_call_disposition picklist.
3. Attach recording URL if policy allows; otherwise internal note with retrieval instructions.
4. Copy agent comments from VICIdial if captured in custom fields.
5. Update lifecycle stage on qualified dispositions per playbook.
6. On DNC dispositions, set HubSpot unsubscribe or custom DNC property and remove from active VICIdial lists.

Use idempotency keys stored in a small local database to prevent duplicate call engagements if the sync job retries. HubSpot timeline clutter from duplicates erodes sales trust quickly.

Workflows and Automation in HubSpot

Once calls land on contact records, HubSpot workflows can assign tasks, send follow-up email, or notify Slack. Keep workflow triggers disposition-specific rather than any call logged to avoid noise on NA attempts.

Example: VICIdial disposition QUALIFIED sets lifecycle stage to SQL, creates deal, assigns AE, and removes contact from VICIdial list via API callback. Disposition NI increments a custom not interested counter and pauses marketing emails per policy.

Bi-directional webhooks require HTTPS TLS 1.2 plus on your integration host. Free Let's Encrypt on the vicidial server works if your provider permits external webhook listeners on managed vicidial hosting.

Field Mapping Reference

Consistency beats cleverness. Recommended minimum map:

• hubspot_contact_id ↔ vendor_lead_code
• phone ↔ phone_number
• firstname ↔ first_name
• lastname ↔ last_name
• hubspot_owner_id ↔ optional VICIdial user group routing metadata
• timezone ↔ GMT offset field on lead
• hs_lead_status ↔ VICIdial list or campaign segment identifier

Custom HubSpot properties for vicidial_campaign and last_vicidial_disposition simplify reporting without parsing engagement bodies. Build HubSpot reports filtered on those properties for managers who do not live in the dialer.

Security and Governance

Store HubSpot private app tokens in environment variables or secrets manager, not in web-accessible PHP on the vicidial dialer host. Rotate tokens when staff with access leave. Restrict VICIdial API user to required functions only.

GDPR and CCPA deletion requests must remove or anonymize records in both systems. Document whether HubSpot or VICIdial is system of record for consent. Deleting a HubSpot contact while the lead remains callable in VICIdial is a compliance failure.

If recordings sync to HubSpot, confirm storage region and customer agreements. Many teams keep recordings on vicidial server storage and link only metadata to HubSpot to reduce vicidial cost and security scope.

Troubleshooting Integration Issues

Contacts Not Entering VICIdial

Check HubSpot workflow enrollment criteria, API 401 from expired token, and VICIdial duplicate phone rejection. Run manual add_lead with one contact in curl to isolate CRM versus dialer fault.

Calls Logged to Wrong Contact

Usually vendor_lead_code mismatch after list reimport without IDs. Reconcile using phone plus email secondary match only as fallback; fix root key mapping.

HubSpot Rate Limit Errors

Implement exponential backoff and batch creates. HubSpot batch endpoints reduce call count. Spread disposition sync over minutes if peak hangup windows overwhelm limits.

Timezone and Callback Errors

HubSpot stores timezone on contact when enriched; VICIdial needs numeric offset for state call times. Sync offset during import and on contact update webhooks.

Comparison With Other CRM Integrations

Patterns mirror Salesforce integration with different object names and auth. HubSpot engagements API is straightforward for call logging; Salesforce Task model is more familiar to enterprise admins. Google Sheets suits lighter teams before CRM maturity. GoHighLevel overlaps HubSpot for agencies running multiple subaccounts.

Pick one CRM source of truth for consent and pipeline stage. Split authority guarantees weekly firefights.

Rollout Checklist

1. Sandbox test with five contacts end to end.
2. Validate disposition map with sales leadership.
3. Enable monitoring alerts on sync job failures.
4. Train agents that HubSpot notes do not auto-sync to VICIdial unless configured.
5. Run parallel manual QA sample of ten calls per day for first two weeks.
6. Document escalation path to vicidial support and HubSpot admin.
7. Review API usage dashboard weekly during first month.

Monitoring and Ongoing Maintenance

Integration is not a launch-day task. Assign an owner to review sync logs every morning during the first month and weekly thereafter. Track error rate, average sync latency, and count of contacts stuck in limbo with vicidial_in_dialer true but no logged calls. Spikes often correlate with marketing list imports that bypass workflow filters or with VICIdial list reloads that strip vendor_lead_code. Keep a runbook that lists every cron job, token expiry date, and emergency contact for your vicidial hosting provider.

Version upgrades on either platform can break field maps. HubSpot deprecates API versions on published schedules; VICIdial updates may rename admin fields. Subscribe to both changelogs and run regression tests in sandbox before production upgrades. When renewing contracts, compare vicidial pricing for integration-friendly hosting against the cost of running your own bridge VPS.

Quarterly business reviews should compare HubSpot SQL counts to VICIdial qualified dispositions. Persistent gaps indicate mapping drift, agent miscoding, or sync failures nobody noticed because sales still hit quota. Fixing integration debt early costs less than rebuilding reports after a lost quarter.

Conclusion

VICIdial and HubSpot integration connects marketing investment to dialer execution. Automate lead push, log dispositions faithfully, and govern consent in both directions.

Begin with scheduled sync and async call logging, then add workflow automation as maturity grows. When HubSpot timelines reflect reality on the vicidial server, leadership stops asking for CSV exports and starts optimizing conversion, which is the point of both tools.