Help

Writing to customers All help

Writing to customers

Apply every item here to every draft and every revision of it — most defects arrive during revision. A clean lint (the tool warns about Markdown, em dashes and hard-wrapped lines) means the formatting is right, nothing more; the content review is yours, and then a person's.

Content

  1. Make the strongest claim the data supports. If the record shows no debit step and no network submission, say plainly that no funds moved. If it is genuinely uncertain, say what is known and what would settle it. The goal is calibration, not false confidence and not reflexive hedging. ✅ "No funds moved: the transfer never reached the network." ❌ "It looks like the payment may not have gone through."
  2. Attribute error text to its source. Before you explain an error string the customer quotes, check whether it appears anywhere in OPN's own record or API response. If it doesn't, say so: it is their system's label, and explaining it as ours misleads.
  3. Keep cross-case patterns internal. "We have seen this at three other institutions" invites "then why isn't it fixed", names other customers, and is not the customer's business. The pattern informs your diagnosis; the message carries the diagnosis.
  4. Offer self-service only when it exists. If the customer can do the thing themselves — an endpoint, a console page, a setting — say so with the exact steps. Never invent a self-service path.
  5. Cut hedges that invite a round trip. "Let us know if that helps" and "I think that should work" each cost a reply. State the resolution and stop, unless there is a genuine open question — then ask it.
  6. Verify a "needs engineering" conclusion against a precedent. Before telling a customer that something requires a code change, look for a completed transfer, an existing configuration, a working example that shows it already works. Most "needs engineering" conclusions are configuration.
  7. Show a configuration fix as data, anchored to their current value. A 4-space-indented block with the field, what it is now, and what it should be. Prose descriptions of settings get misread.
  8. Recommend the durable fix first, the narrow override second. Optimise for not getting a second ticket, not for closing this one.
  9. Foreclose the obvious wrong next move. If the natural thing to try next will not work, say so and why, before they try it.
  10. Report a tool's verdict in the reader's terms. A conformance script that printed duplicate_submission: fail may have been inconclusive, not failed. A tool's output is evidence; the finding is what you conclude from it.
  11. Signpost a multi-topic message; never interleave. One topic per section, the ask at the close.
  12. Check the subject still describes the content. The case's [CASE-…] tag is added for you; the words after it are yours.
  13. Every problem you report has an owner or an ask. A problem stated without either is a worry handed to the reader.
  14. Never volunteer OPN to do work the integrator can do. Cut these, verbatim: "let us know and we can place the request for you", "just say the word and we will send it on your behalf", "happy to run that for you", "we can submit it on your side if that's easier". Each converts a self-service task into a support ticket. Write the endpoint, the body and the required permission instead, and let their team run it.
  15. Tone. A capable person writing to another person: warm, calm, easy to read, professional without being cold, never chatty and never a policy memo.
  16. A secret is a placeholder. A share link, a client secret, a temporary password: write "(secure share link, supplied by the sender)" in its place and say so in chat. The person who sends supplies the value. Never invent one, and never paste a real one.
  17. A list when there is more than one point. Multi-point content is a short intro and a labelled list — "Two points to call out:" — not paragraphs the reader has to unpick. Reviewers rewrote prose into this form twice in one day; default to it.

The recipient list

Reply to the person who wrote, at the address they wrote from. Do not silently add or drop people; if someone needs adding, say so in the message. A confirmation sent to a no-reply address, with the real person only on copy, is a confirmation nobody got.

Formatting

  • Plain text. No Markdown: no **bold**, no # headings, no backticks, no tables, no [links](…). It lands verbatim in the customer's mail client. Write X-JWT-Signature, not `X-JWT-Signature`. Bare URLs are fine; the tool links them.
  • No em dashes. They read as machine-written in professional email. Commas, full stops, or a restructured sentence.
  • One line per paragraph. No hard wraps mid-sentence: the plain-text version keeps every break. Paragraphs are separated by a blank line.
  • Data as a 4-space block. Ids, field values, endpoints, credentials go in an indented block, monospace in the HTML version, exactly as typed in the text version.
  • The customer's names for things. northstarcu is a configuration key; to the reader it is Northstar Credit Union. Ids they gave you are quoted back exactly.
  • Greeting and sign-off. "Hi Rosa," then the message, then the persona's sign-off; the persona's signature block is appended for you. Nothing after the signature.
  • Library images go in with [image: filename] on a line of their own; a hosted video with [video: slug] (a one-hour link is minted when the message sends). Anything a customer should keep is a linked video, not a hosted one.

SMS

A text is plain ASCII, one or two segments, and it is wrapped for you with the carrier-required prefix and footer ("<the desk's name>: … Reply STOP to opt out…"). A character outside the basic set, an em dash or a curly quote, halves the segment size; the draft shows the count. Say one thing, say whose move it is, and sign the first message of an exchange with the persona's name only.

Before you hand it over

Read the whole draft once more as the customer. Then read Review and sending for what happens next.