Skip to content

Widget config API

The widget calls this endpoint on load to fetch appearance, greeting, and deployment settings. No API key is required — access is gated by deployment ID and domain allowlist.

Endpoint

GET /api/v1/widget/config?deployment_id={id}

Query param	Required	Description
`deployment_id`	Yes	Web widget deployment ID

The browser sends Origin (or Referer) automatically. Requests from unlisted domains receive 403.

Example request

curl "https://api.chatevo.ai/api/v1/widget/config?deployment_id=dep_abc123" \
  -H "Origin: https://www.yourbusiness.com"

Example response

{
  "deployment_id": "dep_abc123",
  "assistant_id": "asst_7xK9mN2p",
  "appearance": {
    "primary_color": "#F97316",
    "theme": "light",
    "position": "bottom-right",
    "greeting": "Hi! How can we help you today?",
    "suggested_questions": [
      "What are your hours?",
      "How do I track my order?"
    ]
  },
  "features": {
    "streaming": true,
    "rich_content": true,
    "jwt_required": false
  },
  "rate_limit": {
    "messages_per_minute": 30
  }
}

Embed integration

The embed script passes data-deployment-id and fetches config automatically:

<script
  src="https://widget.chatevo.ai/chat.js"
  data-deployment-id="YOUR_DEPLOYMENT_ID"
  data-api-base="https://api.chatevo.ai"
  async
></script>

Performance

Config responses are CDN-cacheable and target ≤ 300 ms p95. Combined with chat.js, total widget load should be ≤ 2 seconds. See Rate limits.

Errors

Status	Cause	Fix
`403`	Domain not on allowlist	Domain allowlist
`404`	Invalid or archived deployment	Check deployment ID in dashboard
`429`	Widget rate limit	Rate limit troubleshooting