API & webhooks
Automate Hellolyne from your own code. Create a key in Settings → API & webhooks (Pro plan).
Authentication
Send your key as a bearer token. Every write goes through the same operations as the app, so realtime updates, webhooks and workflows behave the same.
curl https://hellolyne.com/api/v1/contacts \
-H "Authorization: Bearer hl_…" \
-H "content-type: application/json" \
-d '{ "user_id": "42", "email": "jane@acme.com", "custom_attributes": { "plan": "Pro" } }'Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/me | The workspace and the key's owner |
GET | /api/v1/contacts?q=&email=&user_id=&page= | List or find contacts |
POST | /api/v1/contacts | Create or update a contact by user_id or email (custom_attributes, company) |
GET / PUT / DELETE | /api/v1/contacts/:id | Read, update or delete a contact |
POST | /api/v1/contacts/:id/tags | Tag a contact { name } |
POST | /api/v1/events | Track an event { event_name, user_id | email | id, metadata } |
GET / POST | /api/v1/companies | List, or create/update by company_id |
GET | /api/v1/conversations?q=&state= | Search conversations |
GET | /api/v1/conversations/:id | A conversation with its parts and contact |
POST | /api/v1/conversations | Start one, from a contact or from a teammate to a contact |
POST | /api/v1/conversations/:id/reply | Reply { type: admin | note | contact, body } |
PUT | /api/v1/conversations/:id | Change state, snooze, assignee, team, priority, tags |
GET | /api/v1/tags · /admins · /articles | Reference data |
POST | /api/v1/articles | Create or update an article |
Webhooks
Subscribe to conversation.created, conversation.user.replied, conversation.admin.replied, conversation.assigned, conversation.closed, conversation.rated, ticket.state.updated, contact.created, contact.updated.
Each delivery is a JSON POST with the headers hellolyne-event, hellolyne-delivery and hellolyne-signature : the HMAC-SHA256 of the raw body with your webhook secret, hex. Failed deliveries are retried 5 times with backoff.
Identity verification
Compute user_hash on your server and pass it with the user in hellolyneSettings :
const user_hash = crypto.createHmac("sha256", IDENTITY_SECRET).update(user.id).digest("hex");Turn on “Require identity verification” in Settings → Messenger to refuse unverified users.
Inbound email by HTTP
POST a raw MIME message to /api/inbound/email (as the body, or a message form field). The workspace is found from the inbound+token@ recipient. Set INBOUND_SECRET on the server to require Authorization: Bearer <secret>.