API Reference

Use these endpoints to build custom integrations with HelpYap. Most users don't need the API — the embeddable widget and admin dashboard handle everything. The API is for advanced use cases like custom chat UIs or server-side event ingestion.

Base URL: https://app.helpyap.com

Authentication

Public endpoints (widget config, chat) are rate-limited but do not require authentication. The social proof push endpoint requires a project-specific push secret.

Admin endpoints (used by the dashboard) require a JWT access token and are not covered in this reference.

Endpoints

GET/api/widget/config

Retrieve the public configuration for a project's chat widget. Useful if you're building a custom chat UI instead of using the embeddable widget.

Query Parameters

Parameter	Type	Required	Description
project	string	Yes	Your project slug

Response Example

JSON

{
  "name": "Support Bot",
  "company": "Acme Inc",
  "welcomeMessage": "Hi! How can I help you today?",
  "quickReplies": ["Pricing", "How to get started", "Talk to support"],
  "theme": {
    "primaryColor": "#3737f6",
    "position": "bottom-right"
  }
}

POST/api/chat

Send a message and receive a streaming AI response. Use this if you're building a custom chat interface.

Request Body

Parameter	Type	Required	Description
projectSlug	string	Yes	Your project slug
sessionId	string (UUID)	Yes	Unique session identifier (generate a UUID client-side)
messages	array	Yes	Array of message objects: [{ "role": "user", "content": "..." }]
sessionToken	string	No	Session token returned by the server on first request (include on subsequent requests)

Request Example

JSON

{
  "projectSlug": "my-store",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "messages": [
    { "role": "user", "content": "What is your return policy?" }
  ]
}

Response is a server-sent event stream (text/event-stream). The session token is returned in the X-Session-Token response header on the first request. Include it in subsequent requests.

POST/api/widget/salespop-push

Push a custom social proof event from your server. Requires a push secret generated in Project Settings > Social Proof.

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer <your-push-secret>
Content-Type	string	Yes	application/json

Request Body

Parameter	Type	Required	Description
project	string	Yes	Your project slug
type	string	Yes	Event type: purchased, subscribed, signed_up, added_to_cart, or custom
name	string	No	Customer name (e.g. "Sarah K.")
location	string	No	Location (e.g. "Austin, TX")
product	string	No	Product or plan name
message	string	No	Custom notification message

Example

bash

curl -X POST https://app.helpyap.com/api/widget/salespop-push \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sp_your_push_secret" \
  -d '{
    "project": "my-store",
    "type": "signed_up",
    "name": "Sarah K.",
    "location": "Austin, TX",
    "product": "Pro Plan"
  }'

Rate Limits

All endpoints are rate-limited per IP address.

Endpoint	Limit	Window
POST /api/chat	20 requests	60 seconds
POST /api/widget/salespop-push	10 requests	60 seconds
Other widget endpoints	60 requests	60 seconds

Error Responses

Errors return a JSON object with an error field:

JSON

{ "error": "Invalid push secret" }

Status Code	Meaning
400	Bad request (missing or invalid parameters)
401	Unauthorized (invalid credentials)
403	Forbidden (valid credentials but insufficient permissions)
404	Project not found
429	Rate limit exceeded