> ## Documentation Index
> Fetch the complete documentation index at: https://kb.vinfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate Neuron with Your CRM, Dialer, and Call Stack

> Connect Neuron to your CRM and dialer using native integrations, real-time webhooks, and the VInfer REST API to automate call outcome delivery.

Neuron is built to fit into your existing stack, not replace it. Whether you run Salesforce, Leadsquared, Freshsales, or a custom CRM — and whether your dialer infrastructure is predictive, progressive, or preview-based — Neuron connects via REST API, real-time webhooks, or native integrations. Every call outcome flows into your systems automatically, so your agents and managers work from data that is always current.

## Integration Methods

Neuron supports three ways to connect with your existing platforms:

<CardGroup cols={2}>
  <Card title="REST API" icon="code">
    Full programmatic control. Create campaigns, fetch results, manage contacts, query dispositions, and control campaign state — all via standard HTTP calls authenticated with your API key.
  </Card>

  <Card title="Webhooks" icon="webhook">
    Real-time event push. When a call completes, a disposition is set, or an escalation fires, VInfer sends a structured payload to your endpoint instantly — no polling required.
  </Card>

  <Card title="Native CRM Connectors" icon="plug">
    Pre-built connectors for popular CRM and dialer platforms that handle field mapping, authentication, and sync automatically. Contact your VInfer account team for availability on your specific platform.
  </Card>

  <Card title="Dialer Integration" icon="phone-office">
    Neuron works alongside your existing outbound dialer infrastructure — predictive, progressive, or preview. Connect it to your dialer layer so Neuron's AI conversations run on top of your existing telephony stack.
  </Card>
</CardGroup>

## REST API

The VInfer REST API gives you complete control over every aspect of Neuron programmatically. All endpoints are authenticated with a Bearer token:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Your API key is available in the VInfer console under **Settings → API Keys**. Use separate API keys for production and staging environments.

Key API capabilities:

| Endpoint                         | What It Does                                                                  |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `POST /v1/campaigns`             | Create and schedule a new campaign                                            |
| `GET /v1/campaigns/{id}`         | Fetch status, progress, and disposition breakdown                             |
| `POST /v1/campaigns/{id}/pause`  | Pause a running campaign                                                      |
| `POST /v1/campaigns/{id}/resume` | Resume a paused campaign                                                      |
| `GET /v1/campaigns/{id}/calls`   | List all calls in a campaign with individual dispositions                     |
| `GET /v1/calls/{id}`             | Fetch a single call record including disposition, duration, and recording URL |
| `POST /v1/webhooks`              | Register a webhook endpoint                                                   |
| `GET /v1/contacts/{phone}`       | Look up contact history and DNC status                                        |

See the [API Reference](/api-reference/introduction) for full endpoint documentation, request/response schemas, and rate limits.

## Webhooks

Webhooks are the recommended way to receive call outcomes in real time. Instead of polling the API for new results, VInfer pushes a structured JSON payload to your endpoint the moment an event occurs.

### Registering a Webhook

Register your endpoint using the `POST /v1/webhooks` API:

```bash theme={null}
curl -X POST https://api.vinfer.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-crm.com/vinfer-webhook",
    "events": ["call.completed", "call.disposition_set", "call.escalated"],
    "secret": "your_webhook_secret"
  }'
```

<ParamField body="url" type="string" required>
  The HTTPS endpoint where VInfer will POST event payloads. Must be publicly accessible and return a `2xx` response within 10 seconds to acknowledge receipt.
</ParamField>

<ParamField body="events" type="array of strings" required>
  The events to subscribe to. Supported values: `call.completed`, `call.disposition_set`, `call.escalated`, `campaign.completed`, `campaign.paused`.
</ParamField>

<ParamField body="secret" type="string" required>
  A secret string you choose. VInfer uses this to sign payloads with an HMAC-SHA256 signature, which you verify on your end using the `X-VInfer-Signature` header.
</ParamField>

<Note>
  Always verify incoming webhook payloads using the `X-VInfer-Signature` header. Compute `HMAC-SHA256(secret, raw_request_body)` and compare it to the signature value. Reject any request where the signature does not match — this ensures payloads are genuinely from VInfer and have not been tampered with.
</Note>

### Webhook Event: `call.completed`

This event fires when a call ends and Neuron has finalized the disposition. It is the primary event to consume for CRM updates.

```json theme={null}
{
  "event": "call.completed",
  "event_id": "evt_7c3d9f2a1b8e",
  "timestamp": "2024-01-15T11:43:22+05:30",
  "campaign_id": "cmp_8f3a2b1c9d4e",
  "call": {
    "call_id": "call_4a9e1f7b2c3d",
    "phone": "+919876543210",
    "contact_name": "Priya Sharma",
    "language": "hi-IN",
    "duration_seconds": 94,
    "disposition": "callback_requested",
    "callback_time": "2024-01-16T10:00:00+05:30",
    "escalated": false,
    "recording_url": "https://recordings.vinfer.ai/call_4a9e1f7b2c3d.mp3",
    "custom_fields": {
      "loan_amount": 50000
    }
  }
}
```

<ResponseField name="event" type="string">
  The event type. Always `"call.completed"` for this payload.
</ResponseField>

<ResponseField name="campaign_id" type="string">
  The ID of the campaign this call belongs to.
</ResponseField>

<ResponseField name="call.call_id" type="string">
  Unique identifier for this call. Use this to fetch the full call record via `GET /v1/calls/{call_id}`.
</ResponseField>

<ResponseField name="call.disposition" type="string">
  The outcome tag Neuron assigned to this call. Maps to your configured disposition list.
</ResponseField>

<ResponseField name="call.callback_time" type="string">
  ISO 8601 timestamp for the customer's requested callback time. Only present when `disposition` is `"callback_requested"`.
</ResponseField>

<ResponseField name="call.escalated" type="boolean">
  Whether this call was transferred to a human agent during the conversation.
</ResponseField>

<ResponseField name="call.recording_url" type="string">
  Pre-signed URL to the call recording audio file. URL expires after 72 hours. Fetch and store recordings in your own storage if you need longer retention.
</ResponseField>

### Webhook Event: `call.escalated`

This event fires in real time when Neuron transfers a call to a human agent — useful for triggering screen-pop or alert workflows on your side:

```json theme={null}
{
  "event": "call.escalated",
  "event_id": "evt_2b8d5f1a9c6e",
  "timestamp": "2024-01-15T11:38:05+05:30",
  "campaign_id": "cmp_8f3a2b1c9d4e",
  "call": {
    "call_id": "call_9b2c4e7f1a3d",
    "phone": "+919123456789",
    "contact_name": "Amit Patel",
    "escalation_trigger": "sentiment_negative",
    "transfer_to": "+918001234567",
    "conversation_summary": "Customer disputed the outstanding amount and requested to speak with a manager."
  }
}
```

<Tip>
  Use the `call.escalated` webhook to trigger a screen-pop for your live agent before the transferred call connects. Passing `conversation_summary` to your agent's interface means they start with context — the customer doesn't have to repeat themselves.
</Tip>

## Dialer Integration

Neuron integrates with your existing outbound dialer infrastructure without requiring you to replace it. It works alongside:

* **Predictive dialers** — Neuron handles the AI conversation layer; your dialer handles the call origination and pacing
* **Progressive dialers** — calls are connected to Neuron agents as contacts are dialed
* **Preview dialers** — agents can initiate Neuron-powered calls directly from their desktop for specific contact segments

To connect Neuron to your dialer infrastructure, contact your VInfer account team. The integration requires a brief technical setup call to configure SIP trunking or API-based call handoff depending on your dialer's architecture.

## CRM Field Mapping

After you connect your CRM, map VInfer's disposition values to your CRM's lead status or activity fields so data lands in the right places automatically:

<Steps>
  <Step title="Open CRM Mapping Settings">
    Go to **Settings → Integrations → CRM Mapping** in the VInfer console.
  </Step>

  <Step title="Select Your CRM">
    Choose your CRM from the connected integrations list. If your CRM isn't listed as a native integration, use the webhook method to push data programmatically.
  </Step>

  <Step title="Map Disposition Values">
    For each VInfer disposition value (e.g., `callback_requested`, `interested`, `dnc`), select the corresponding field value in your CRM (e.g., `Follow Up`, `Hot Lead`, `Do Not Contact`).
  </Step>

  <Step title="Map Custom Call Fields">
    Map any custom fields captured during calls (e.g., `callback_time`, `dispute_reason`, `loan_amount`) to the appropriate CRM fields.
  </Step>

  <Step title="Test the Mapping">
    Run a single test call via **Neuron → Test Call** and verify that the CRM record updates correctly before launching a full campaign.
  </Step>
</Steps>

## Webhook Reliability

VInfer delivers webhooks with the following reliability guarantees:

<AccordionGroup>
  <Accordion title="Retry Policy">
    If your endpoint returns a non-`2xx` response or times out, VInfer retries the webhook up to 5 times with exponential backoff (intervals: 1 min, 5 min, 30 min, 2 hours, 12 hours). After 5 failed attempts, the event is logged as undelivered and accessible via **Settings → Webhooks → Failed Events** for manual replay.
  </Accordion>

  <Accordion title="Event Ordering">
    Webhooks are delivered at-least-once. Under high load, you may occasionally receive duplicate events. Use the `event_id` field to deduplicate on your side — process each `event_id` only once.
  </Accordion>

  <Accordion title="Payload Verification">
    Every webhook request includes an `X-VInfer-Signature` header containing an HMAC-SHA256 signature of the raw request body, keyed with your webhook secret. Always verify this before processing the payload.
  </Accordion>

  <Accordion title="Endpoint Requirements">
    Your webhook endpoint must be reachable over HTTPS, use a valid TLS certificate, and respond with a `2xx` status code within 10 seconds. Endpoints that consistently fail are automatically disabled after 24 hours of failures — you'll receive an email alert before this happens.
  </Accordion>
</AccordionGroup>

<Warning>
  Do not perform long-running processing synchronously in your webhook handler. Return a `200 OK` immediately upon receipt, then process the payload asynchronously (e.g., push to a queue). Webhook handlers that take longer than 10 seconds to respond will be treated as failures and retried.
</Warning>

## Next Steps

* [Launch your first campaign](/neuron/campaigns) and watch outcomes flow into your CRM via webhooks
* [Configure voice agents](/neuron/voice-agents) with escalation rules for live-agent handoffs
* [Review the API Reference](/api-reference/introduction) for full endpoint documentation and authentication details