CRM Telephony Integration Guide

It connects your phone system with your CRM so that calling activity and CRM records stay synchronized. Common patterns: click a phone number in the CRM to place a call, automatically log the call with duration and recording, and show caller context before answering. For Indian teams using Salesforce, HubSpot or Zoho, this reduces manual dialing and errors.

Two systems plus a bridge: CRM (contact/lead/deal objects) + Telephony platform (SIP, dialer, IVR) + Integration layer (native app, REST API, webhooks, or middleware like Zapier/Make). Native app: pre-built, no code, limited customization. API/webhook: custom, full control, requires dev. Middleware: no-code sync via Zapier/Make, slower.

CRM renders a clickable phone field (tel: link or CTI button) that triggers the dialer via API. No copy-paste, no misdial. The click sends `POST /calls {to, from, record}` with CRM contact ID, and the dialer places the call, showing the correct caller ID.

On inbound, the phone system looks up the caller via CRM API (phone → contact) and pops the matching record before the agent answers: name, company, open tickets, deal stage. For Salesforce/HubSpot, this is often a CTI screen-pop; for Zoho, a similar widget.

After the call, the integration creates a timeline entry: who, when, duration, outcome (disposition), recording link, and next action. It maps to the CRM's activity/call object (e.g., Salesforce Activity, HubSpot Engagement, Zoho Calls). Manual logging is error-prone and is typically replaced.

Agent selects disposition (e.g., Interested, Callback, Not Interested) and the log includes recording link where enabled. The recording URL is written to the CRM timeline; access is via RBAC, not public.

Phone system fires webhooks: `call.ringing` (offered), `call.answered` (connected), `call.completed` (ended, with duration), `recording.available`. CRM or middleware listens and updates records. Retries on 5xx, with exponential backoff.

1. Agent clicks call in Salesforce → 2. Salesforce CTI → POST https://api.agilis.com/v1/calls {to:+919..., from:+9180..., contactId: 123} → 3. Agilis places call via SIP → 4. Webhook call.answered → Salesforce updates Activity status → 5. Webhook call.completed + recording.available → Salesforce logs duration + recording link.

Auth via API key or OAuth (e.g., HubSpot OAuth). Handle 401 (refresh), 429 (rate limit, back off), 5xx (retry). Agilis may enforce per-plan rate limits; bulk sync should paginate and respect 429.

Duplicate numbers (same phone on multiple contacts) cause logging to the wrong record. Mitigate: dedupe CRM before sync, use contact ID in click-to-call payload (not just phone), and match inbound by most recent activity or primary contact.

Private numbers have no caller ID to look up. Screen-pop will fail; log as 'Private' with no contact link. Do not fabricate a contact.

Decide which CRM object should own calls: Salesforce (Contact/Lead + Activity), HubSpot (Contact + Engagement), Zoho (Lead/Contact + Calls). Map disposition fields before go-live; custom fields may require mapping.

Request minimal CRM scopes (e.g., `crm.objects.contacts.read` not `admin`). Over-permissioning risks data exposure. Only sync fields needed for calling (name, phone, deal stage), not entire CRM.

| Method | Setup | Customization | Best For | | Native app (pre-built) | One-click, no code | Low | Salesforce/HubSpot/Zoho with supported native | | REST API | Custom code | High | Custom objects, high volume | | Webhooks | Config | Medium | Real-time events | | Middleware (Zapier/Make) | No-code | Medium | Low volume, quick sync |

- Decide which CRM object owns calls - Map disposition fields - Choose method: native vs API (verify Agilis native for Salesforce/HubSpot/Zoho per plan) - Test with small user group and verify logs - Handle private numbers and duplicates - Plan for rate limits and retries - Restrict scopes