For developers of Walnut apps

Adding Help & feedback to an app.

Every Walnut app should offer a Help & feedback link. Apps that use the central Walnut sign-in only need a link. Apps with their own sign-in can use the support API.

Choose your route.

Your app	Do this
Uses the central Walnut sign-in (on a walnutdatatech.com subdomain)	Add links to the help centre. Users are already signed in.
Has its own sign-in	Call the support API from your server and show the results in your own pages, or link to the help centre and let users sign in with Walnut.

Add the links.

Pass your app key so tickets show which app they came from, and a return address so users can go back.

Link	Address
Help & feedback home	`https://login.walnutdatatech.com/support?app=<key>&return_to=<url>`
Report an issue	`https://login.walnutdatatech.com/support/new?type=IS&app=<key>&return_to=<url>`
Any type	`/support/new?type=FB`, `GR`, `SG`, `RQ` or `QY`
Check a request	`https://login.walnutdatatech.com/support/status`
One ticket	`https://login.walnutdatatech.com/support/tickets/WT-IS-000123`
Grievance officer	`https://login.walnutdatatech.com/support/grievance-officer`
Help centre	`https://login.walnutdatatech.com/support/help`

Rules for the parameters.

app: your app key from Admin, Apps. 2 to 50 lowercase letters, digits, hyphens or underscores. Anything else is ignored.
return_to: a full HTTPS address on walnutdatatech.com or one of its subdomains, URL-encoded. Other addresses are ignored.
type: one of FB, IS, GR, SG, RQ, QY. It preselects the type; the user can change it.

Example link in a page:

<a href="https://login.walnutdatatech.com/support?app=lms&return_to=https%3A%2F%2Flms.walnutdatatech.com%2Fcourses">Help &amp; feedback</a>

Use the API if you have your own sign-in.

The support API lives at https://login.walnutdatatech.com/api/support. It is server to server only: never call it from a browser, because it needs your app secret.

Send X-App-Key and X-App-Secret headers on every request. The secret is shown once when the app is registered or its secret is rotated.
Send the person's email (and optionally name and role). Your app vouches for who the person is.
Your app can read only tickets raised through it, or raised by people who have access to your app.

Method and path	Does
GET /meta	Types, departments, names list, limits, statuses and grievance officer details, for building a form
POST /tickets	Raise a request
GET /tickets?email=	List a person's requests
GET /tickets/:id?email=	One request with its public history and attachment list
POST /tickets/:id/reply	Add a reply
POST /tickets/:id/confirm	Confirm a resolved request
POST /tickets/:id/reopen	Reopen
POST /tickets/:id/rate	Rate a closed request from 1 to 5, once
POST /tickets/:id/appeal	Appeal a resolved or closed request that is not a Grievance, once per ticket, creating a linked Grievance

Attachments go as base64 in JSON, up to 3 files and 3 MB in total. Replies are limited to 30 per person per hour, a rating can be given once, and an appeal can be made once per ticket, only on a resolved or closed request that is not a Grievance. Full request and response examples, error codes and limits are in docs/SUPPORT-API.md in the walnut-login repository; the integration checklist is in docs/SUPPORT-INTEGRATION.md.

Rules for the form in your app.

Show "Who is this about? (optional)" only when the type is Issue (shows_named_person in /meta).
If the user chooses Other as the department, send department_id: "other" with other_department_name, and explain that Walnut will route it.
Tell the user that a Grievance always goes to the Grievance Cell.
Show the ticket ID and the track_url from the response after a successful submission.
Offer rating and appeal only when they are allowed (rate once after closing; appeal once, on a resolved or closed request that is not a Grievance), and show the message from any error.
Follow the Walnut brand: British spelling, sentence case, no exclamation marks.

Try the links.

Help & feedback Report an issue Check a request