Letterbook
All docs

Letterbook Docs

Create a conversation

Open a new customer conversation in Letterbook from an external system.

Last updated June 25, 2026

What this guide covers#

Create a conversation when a support request starts outside a connected inbox, such as an app form, web form, or internal system.

Use this endpoint for product-native support flows where your system can send structured customer context directly to Letterbook.

Endpoint#

POST /api/webhooks/conversations

Request fields#

  • customer_email: the customer's email address. Use the same address your billing or account systems use when possible.
  • customer_name: the display name to show in the conversation.
  • subject: a concise ticket title.
  • message: plain-text customer message or issue summary.
  • message_html: HTML version of the message, if your form captures rich text.
  • priority: your initial priority signal, if the source can determine one.
  • external_id: your stable identifier for the form submission, app ticket, backend event, or source object.

Include enough context for a teammate to understand the issue without opening another system. Do not include secrets, passwords, access tokens, or unnecessary sensitive data in the message body.

Example payload#

{
  "customer_email": "maya@example.com",
  "customer_name": "Maya Patel",
  "subject": "Cannot access Pro features after upgrade",
  "message": "I upgraded yesterday, but my workspace still shows Basic limits.",
  "priority": "normal",
  "external_id": "support-form-18291"
}

Response fields#

  • id
  • display_id
  • status
  • url

Store the returned id or url if your product should link back to the Letterbook conversation.

Idempotency and duplicates#

Use a stable external_id for each source submission or backend event. That lets your system reason about retries and reduces the risk of creating duplicate tickets when a network call times out.

Avoid sending the same customer issue through both API ingestion and email forwarding. If a web form also emails support@company.com, disable the email copy or make sure it does not create a second Letterbook conversation.

What metadata to include#

For app and website support flows, include useful context in the subject, message, or source system fields:

  • User ID or account ID
  • Workspace or organization ID
  • App version and platform
  • Current URL or screen
  • Recent error code
  • Subscription or plan name
  • Steps the customer already tried

Prefer structured metadata over long pasted logs when possible.