# Connector Setup

Connectors let external platforms embed the support widget, identify users, pass context, create tickets, and send normalized events to the Laravel core. The Laravel app remains canonical for AI, billing, CRM, tickets, conversations, usage, and webhooks.

## Standard Connector Rules

- Use workspace API tokens.
- Use the smallest required scope set.
- Do not store OpenAI credentials.
- Do not run AI inference inside the addon.
- Do not duplicate billing, CRM, tickets, or conversations.
- Send normalized events to the Laravel core.
- Register install and heartbeat state when supported.

## Standard Settings

Every connector should expose:

- Laravel API URL.
- Workspace API token.
- Widget public key.
- Default identity mapping.
- Debug mode.
- Connection status.
- Optional webhook secret.

## Core Endpoints

```text
GET /api/v1/connectors/bootstrap
POST /api/v1/connectors/install
POST /api/v1/connectors/events
PATCH /api/v1/connectors/{connectorKey}/heartbeat
```

## Common Scopes

- `connectors:bootstrap`
- `connectors:events`
- `connectors:install`
- `contacts:read`
- `contacts:write`
- `crm:read`
- `crm:write`
- `tickets:read`
- `tickets:write`
- `usage:write`

Required scopes are visible in Admin > Marketplace > Addon Packages and Admin > Integrations.

## Event Payload

```json
{
  "source": "wordpress-plugin",
  "event_name": "wordpress.page.viewed",
  "external_id": "post-123",
  "customer": {
    "email": "buyer@ovion.tech",
    "name": "Buyer Demo"
  },
  "order": {},
  "product": {},
  "cart": {},
  "ticket": {},
  "conversation": {},
  "meta": {
    "page": "/pricing"
  }
}
```

## Health Checks

The admin connector health UI should show:

- Installed package version.
- Missing scopes.
- Failed syncs.
- Webhook status.
- Last seen time.
- Last sync time.
- Last error.
- Documentation link.
- Screenshot count.

## Troubleshooting

- 401 means token is missing, revoked, or expired.
- 403 means the token lacks required scopes.
- Missing widget means widget key or loader URL is wrong.
- Accepted events with no CRM records usually mean missing `contacts:write` or `crm:write`.
- Missing tickets usually means missing `tickets:write` or ticket creation is disabled by the connector settings.