API
A small JSON API for conversations, messages, contacts and tags, and webhooks for what happens. Make a key in Settings, API and webhooks. Keys act for the whole workspace, so keep them on your servers.
Calling it
Send the key in the X-Nurvedesk-Key header. Bodies and answers are JSON. A refusal is { "ok": false, "problem": "…", "detail": "…" } with a 400, 401, 404 or 409.
curl https://nurvedesk.com/api/v1/conversations.json?status=new \ -H "X-Nurvedesk-Key: nd_…"
Conversations
GET /api/v1/conversations.json | Newest first, 50 a page. Filter with status (new, open, waiting, snoozed, resolved, closed, spam) and inbox; page with after, the next of the page before. |
|---|---|
POST /api/v1/conversations.json | { "inbox": "i…", "from": { "email", "name" }, "subject", "text" }: a message from a customer, filed exactly as an email would be. Answers { "ok": true, "number": 42 }. |
GET /api/v1/conversation.json?number=42 | The conversation and its messages and notes, oldest first. |
POST /api/v1/conversation.json | { "number", "status"?, "priority"?, "assignee"? (a member's email, or "" for nobody), "add_tags"?, "remove_tags"? }. |
Messages
POST /api/v1/messages.json | { "number", "kind": "note" | "reply", "text" }. A note stays with your team. A reply is emailed to the customer from the conversation's inbox. |
|---|
Contacts and tags
GET /api/v1/contacts.json | ?email= for one, or ?q= to search, 100 a page. |
|---|---|
POST /api/v1/contacts.json | { "email", "name"?, "company"?, "notes"? }: makes the contact, or updates the one with that address. |
GET /api/v1/tags.json | Every tag in the workspace. |
Webhooks
Add an https address in Settings and choose its events. Each is a POST of JSON:
{ "id": "…", "type": "message.created", "workspace": "w…", "at": 1794570661293,
"data": { "number": 42, "kind": "inbound", "from": "ana@example.com", "subject": "…", "text": "…" } }
conversation.created | A new conversation, from mail, the form or the API. |
|---|---|
message.created | A customer's message (inbound), a reply (outbound) or a note (note). |
conversation.updated | Its status or who it's assigned to changed; data.previous has the old values. |
Check the X-Nurvedesk-Secret header against the secret shown when you added the address, and answer with any 2xx. A delivery that fails is tried again after 1, 2, 4… minutes, eight times in all. The same event may arrive twice: use its id to tell.