Whowell setup guide
Whowell sends your customer a one-time Persona or Onfido identity verification link from the Zendesk ticket and shows the result on the ticket. Published at https://greatwork.company/apps/whowell/docs.
Before you start
You need a Persona account with at least one inquiry template, or an Onfido (Entrust Identity Verification) account with at least one active Studio workflow, or both. Verification fees are billed by Persona or Onfido under your contract with them.
Persona
- Persona Dashboard > API > API Keys > Create API key. Name it "Zendesk Whowell".
- Permissions: tick only inquiry.read, inquiry.write and verification.read. verification.read lets result notes list the checks that ran; without it the note links to the inquiry in Persona instead.
- If your plan offers it, restrict the key to the templates you'll use from Zendesk. You can also give the key its own rate limit.
- Copy the key into Whowell's Persona API key setting. Production keys start
persona_production_, sandbox keyspersona_sandbox_(sandbox inquiries don't run real checks: good for trying Whowell out). - Copy each template's id (
itmpl_...) from Inquiries > Templates into Verification flows, one line each:persona itmpl_abc123 Account recovery.
Whowell sends Persona the template, a reference zendesk-user-<id> (so repeat verifications of the
same customer group under one Persona account) and the note Zendesk ticket #<id>. No name or
email.
Onfido
- Onfido Dashboard > Developers > API authentication > Tokens > Generate API token. Use a token only for Zendesk: Onfido tokens can't be limited, so revoking it never breaks anything else.
- Copy it into Onfido API token, and set Onfido region to the region of your account:
eu(tokens startapi_live.),us(api_live_us.) orca(api_live_ca.). - In Onfido Studio, pick a workflow that collects what it needs from the customer (document,
selfie, and so on) and doesn't need custom input data. Copy its id into Verification flows:
onfido 6c1e2f0a-1b2c-4d3e-8f90-1234567890ab Payout change.
Onfido needs a first and last name to create an applicant, so Whowell sends the requester's Zendesk name. Turn on Send the requester's email to Onfido only if your workflow needs it.
Settings
| Setting | Default | What it does |
|---|---|---|
| Verification flows | (required) | One line per flow: vendor, template or workflow id, the name agents pick |
| Who sees verifications | agent | Who sees the sidebar: agent (everyone), admin, role ids, group: |
| Who may send links | agent | Who may send, resend and cancel links; everyone else sees statuses only |
| Link lifetime (hours) | 24 | 1 to 720 hours |
| Reply text | a short request with {link} | {link}, {hours} and {name} (first name) are filled in |
| Send the requester's email to Onfido | off | Onfido only |
| Record the approval date on the user | on | Sets "Whowell: identity verified on" when a verification is approved |
Using it
- Open the ticket, pick a flow in the Whowell sidebar and click Send verification link. The confirmation says exactly what the vendor gets.
- Create link and add to reply puts the link in your reply draft. Submit the reply as usual.
- The sidebar checks the status when the ticket opens and when you click Refresh. When there's a result (completed, approved, declined, needs review, failed, expired), Whowell writes it once as an internal note with the checks that ran and a link to the vendor's dashboard, sets the whowell_* tag and, on approval, the user's verified-on date.
- Send a new link if the customer lost it or it expired. Cancel link (Persona) stops a link sent by mistake.
Triggers and views
- Tags:
whowell_pending,whowell_approved,whowell_declined,whowell_review,whowell_failed,whowell_expired. One at a time, following the newest verification. - User field "Whowell: identity verified on" (date): for example a view of tickets about payout changes where the requester's verified-on date is within the last 30 days.
Troubleshooting
| Message | What to do |
|---|---|
| Persona refused the API key | Paste the key again; check it's for the right environment (production or sandbox) |
| Persona says this API key may not do that | Add inquiry.read, inquiry.write (and verification.read) to the key; if it's limited to templates, include this flow's template |
| Persona has no such inquiry or template | Check the template id in Verification flows, and that the key is from the same environment |
| Onfido refused the API token for the EU region | Set Onfido region to the token's region (see the prefix) or paste the right token |
| Onfido could not start this workflow | The workflow needs applicant data or custom input Whowell doesn't send; use a workflow that collects it from the customer |
| Onfido needs the requester's first and last name | Add the name to the requester's Zendesk profile |
| The Whowell ticket field is missing | Reinstall from the Marketplace (a test install made with zcli apps:server creates no fields) |
| Copy the reply | The reply editor didn't take the text; copy it from the box in the sidebar |
What Whowell keeps
Only ids, statuses, the flow name, who sent the link and when, and when it expires, in a hidden ticket field (at most 20 per ticket). Results go into internal notes. No documents, images, ID numbers, dates of birth or addresses, and never the link itself. Full details in the privacy policy: https://greatwork.company/apps/whowell/privacy.