# VoxLink Integrations & CTI API

Base URL: `https://voxlink-econxgroup-production.up.railway.app`

VoxLink is **CRM-agnostic**. Your Salesforce / HubSpot / Zendesk / Genesys stack stays the system of record. VoxLink dials, pops the agent screen, and pushes dispositions back via webhooks.

## 1. Connect (admin UI or API)

1. Sign in as an admin → **Integrations**.
2. Click **Connect** on your CRM card (and optionally a CTI connector).
3. Copy the one-time `vx_…` API key.
4. Paste your CRM webhook URL and click **Test webhook**.

```http
POST https://voxlink-econxgroup-production.up.railway.app/api/integrations/connect
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{ "crm_provider": "salesforce", "cti_connector": "genesys", "webhook_url": "https://crm.example.com/hooks/voxlink" }
```

## 2. Auth for machine clients

| Header | Value |
|--------|-------|
| `X-VoxLink-Api-Key` | Company integration key (`vx_…`) |
| or `Authorization` | `Bearer <jwt>` from `POST /api/auth/login` |

## 3. Push customer data (screen-pop cache)

Call this when a ticket/account changes in your CRM so the agent pop is ready before the ring.

```http
POST https://voxlink-econxgroup-production.up.railway.app/api/integrations/inbound
X-VoxLink-Api-Key: vx_…
Content-Type: application/json

{
  "phone_number": "+15551234567",
  "external_system": "salesforce",
  "external_id": "001xx000003DGbE",
  "tier": "gold",
  "data": {
    "name": "Jane Customer",
    "email": "jane@example.com",
    "account_number": "AC-99102",
    "open_tickets": 2
  }
}
```

## 4. Lookup (dialer / agent)

```http
GET https://voxlink-econxgroup-production.up.railway.app/api/integrations/lookup?phone=%2B15551234567
Authorization: Bearer <agent_jwt>
```

CTI middleware can also call:

```http
GET https://voxlink-econxgroup-production.up.railway.app/api/integrations/cti/screen-pop?phone=%2B15551234567
X-VoxLink-Api-Key: vx_…
```

## 5. Click-to-dial (CRM softphone button)

```http
POST https://voxlink-econxgroup-production.up.railway.app/api/integrations/cti/click-to-dial
X-VoxLink-Api-Key: vx_…
Content-Type: application/json

{
  "phone_number": "+15551234567",
  "agent_code": "AGENT001",
  "external_id": "001xx000003DGbE",
  "screen_pop": { "name": "Jane Customer", "email": "jane@example.com" }
}
```

VoxLink places the outbound call on a Ready agent softphone and emits `crm_screen_pop`.

## 6. Webhooks you receive

VoxLink `POST`s to your `webhook_url`:

| Event | When |
|-------|------|
| `call_started` | Outbound dial or inbound ring enrichment |
| `call_answered` | Call answered |
| `disposition` | Wrap-up submitted |
| `cti_click_to_dial` | CRM-initiated dial started |
| `integration_test` | Admin test ping |

Headers: `X-VoxLink-Event`, `X-VoxLink-Company`, `X-VoxLink-Signature` (`sha256=…`).

Body shape:

```json
{
  "event": "call_started",
  "company_id": "…",
  "occurred_at": "2026-07-14T12:00:00.000Z",
  "crm_provider": "salesforce",
  "cti_connector": "genesys",
  "data": { "call_id": "…", "phone": "+1555…", "direction": "outbound" }
}
```

## Supported CRM providers

- `salesforce` — Salesforce
- `hubspot` — HubSpot
- `zendesk` — Zendesk
- `freshdesk` — Freshdesk
- `dynamics` — Microsoft Dynamics 365
- `pipedrive` — Pipedrive
- `zoho` — Zoho CRM
- `intercom` — Intercom
- `servicenow` — ServiceNow
- `custom` — Custom / proprietary CRM

## Supported CTI connectors

- `genesys` — Genesys Cloud
- `avaya` — Avaya Aura / AES
- `cisco` — Cisco Finesse / UCCE
- `five9` — Five9
- `nice` — NICE CXone
- `talkdesk` — Talkdesk
- `none` — None (VoxLink softphone only)

## OpenAPI

Machine-readable spec: [OpenAPI JSON](/developers/openapi) · raw [`/developers/openapi.json`](/developers/openapi.json)

## Native VoxLink CRM (optional)

If you also use VoxLink's built-in pipeline: `/api/crm/*` (JWT). See OpenAPI and admin Campaign Manager UI.

## Quick start checklist

1. Create a tenant admin and open **Integrations**.
2. Connect Salesforce / HubSpot / custom CRM → copy `vx_` key.
3. Push one contact via `POST /api/integrations/inbound`.
4. Put an agent **Ready**, then fire `POST /api/integrations/cti/click-to-dial`.
5. Confirm webhook `call_started` hits your endpoint.

## Try it now (copy & paste)

Replace `vx_YOUR_KEY` and phone numbers. Agent must be **Ready** in VoxLink for click-to-dial.

**1. Login (get JWT for agent UI flows)**

```bash
curl -s -X POST https://voxlink-econxgroup-production.up.railway.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"agent_code":"AGENT001","password":"password","company_slug":"demo"}'
```

**2. Push screen-pop cache**

```bash
curl -s -X POST https://voxlink-econxgroup-production.up.railway.app/api/integrations/inbound \
  -H "X-VoxLink-Api-Key: vx_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "external_system": "salesforce",
    "external_id": "001xx000003DGbE",
    "data": { "name": "Jane Customer", "email": "jane@example.com" }
  }'
```

**3. Click-to-dial from CRM**

```bash
curl -s -X POST https://voxlink-econxgroup-production.up.railway.app/api/integrations/cti/click-to-dial \
  -H "X-VoxLink-Api-Key: vx_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "agent_code": "AGENT001",
    "screen_pop": { "name": "Jane Customer" }
  }'
```

**4. Screen-pop lookup**

```bash
curl -s "https://voxlink-econxgroup-production.up.railway.app/api/integrations/cti/screen-pop?phone=%2B15551234567" \
  -H "X-VoxLink-Api-Key: vx_YOUR_KEY"
```

## HTTP status codes

| Code | Meaning |
|------|---------|
| 200 | Success (lookup, connect, webhook test) |
| 201 | Created (click-to-dial started) |
| 401 | Missing or invalid API key / JWT |
| 403 | Wrong company or role |
| 404 | Unknown phone cache / agent |
| 503 | No Ready agent for click-to-dial |

## Webhook signature verification

When `webhook_secret` is configured, verify `X-VoxLink-Signature`:

```
sha256=HMAC_SHA256(webhook_secret, raw_request_body)
```

Reject requests where the signature does not match.

## Health & discovery

```bash
curl -s https://voxlink-econxgroup-production.up.railway.app/api/health
curl -s https://voxlink-econxgroup-production.up.railway.app/api/public/platform
```

## Documentation formats

| Format | URL |
|--------|-----|
| HTML (this page) | `/developers/docs` |
| Raw Markdown | `/developers/docs.md` |
| OpenAPI browser | `/developers/openapi` |
| OpenAPI JSON | `/developers/openapi.json` |

All docs are served from the **VoxLink frontend** (works on Vercel). The API itself runs at `https://voxlink-econxgroup-production.up.railway.app`.